# How it works

> Every Avtrz request runs the same four-stage pipeline: match, decode, encode, cache. The first request to a profile finds the photo; every later request is a CDN hit.

## The pipeline

1. **Match the profile.** The LinkedIn URL or username is normalized and resolved against the directory of business profiles.
2. **Decode the photo.** The source image is fetched and face-aware square-cropped so the subject stays centered at every size.
3. **Encode for the client.** The crop is encoded to the format and size the client asked for (WEBP or PNG, 32 through 512 pixels).
4. **Cache 24 hours.** The response is pinned on the CDN with `Cache-Control: public, max-age=86400`. Subsequent hits return in single-digit milliseconds.

## Where the photos come from

Avtrz resolves a LinkedIn profile (by full URL or by username) and serves the profile photo associated with it. Avtrz does not scrape personal social accounts, does not pull from inboxes, and does not use photos the person did not choose as their profile image.

## Fallbacks

When a profile cannot be resolved, the endpoint returns a deterministic SVG fallback at the size you requested: a soft monogram on a stable background. It is visually consistent across a list and easy to swap with your own avatar component if you prefer.

## Cache strategy

Two layers, both opaque. You do not need to set headers or invalidate anything.

| Layer | Scope | Behavior |
| --- | --- | --- |
| CDN cache | edge | Successful redirects ship `Cache-Control: public, max-age=86400`. The browser, your CDN, and intermediate proxies reuse the response for 24 hours. |
| Fallback responses | edge | SVG fallbacks ship `Cache-Control: no-store` so a transient miss cannot pin a placeholder in your CDN. |
| Profile cache | origin | The resolved profile-to-photo mapping is cached server-side. The first hit warms the cache for everyone else in your workspace. |
| Billing | meter | Every request meters `avatar_requests`. The first lookup of a new profile also meters `avatar_new_profiles`. |

## The data path, end to end

| Data | State | Notes |
| --- | --- | --- |
| LinkedIn URL / username | in transit | TLS only. Used to resolve the profile; not used for anything else. |
| Resolved profile | stored | The matched LinkedIn profile and its photo URL, cached server-side so subsequent requests do not re-resolve. |
| Your IP / referer | logged | Standard request log, used for abuse detection and your usage chart. |