# Media Streamlining Plan: Driver Avatars, Team Logos, League Logos

## Goal
Create one clean, conflict-free way to represent and deliver:

- Driver avatars (defaults now; user uploads later)
- Team logos (seeded)
- League logos (seeded)

So that:

- Seeding never produces conflicting behavior across environments.
- The UI never has to guess whether a value is a file path, an API route, a generated asset, or an uploaded asset.
- There is exactly one place that decides the final image URL for each entity.

## What exists today (inventory, by responsibility)

### Driver avatars

Where they surface:

- Driver lists, driver leaderboards, race entry lists, dashboard summaries, and social/friend UI elements.
- API payloads sometimes include an avatar URL; other times the client constructs a URL from the driver id.
- There are multiple fallback strategies: empty string, null, or client-side default image.

Where they come from:

- A “default avatar set” of three files exists in the website public assets.
- There is also a server route that can generate an avatar image for a driver id.
- Some parts of the system treat driver avatar as a user-uploadable media setting.

Observed problems:

- Mixed meaning of the avatar field: sometimes it is an absolute URL, sometimes a relative path, sometimes a server route string.
- Multiple fallbacks implemented in multiple places leads to inconsistent UI and hard-to-debug “missing image” bugs.
- Multiple “demo/fake” avatar generators exist, creating divergent behavior between environments.

### Team logos

Where they surface:

- Team cards, team leaderboards, recruiting/featured team sections.
- Sometimes the UI uses `logoUrl` from the API payload; other times it falls back to a server route based on id.

Where they come from:

- A server route can generate a team logo image for a team id.
- Seed logic also “pre-seeds” team logos by writing route strings into an in-memory store.

Observed problems:

- Team “logoUrl” may be an actual URL, or it may be a placeholder, or it may be a server route string stored as data.
- Storing route strings as if they were media values creates conflicts when routes change.
- In some persistence modes the “seeded logo store” is not truly persisted, so bootstrapping may re-trigger reseeding or create inconsistent results.

### League logos

Where they surface:

- League cards, league headers, league pages.
- UI tends to call a client-side helper that builds a league-logo URL from id.

Where they come from:

- A server route can generate a league logo image for a league id.
- Seed logic also “pre-seeds” league logos by writing route strings into an in-memory store.

Observed problems:

- Same class of conflicts as team logos.
- There is no single authoritative rule for when a league has a “real” logo versus a generated one.

## Proposed streamlined model (single canonical representation)

### Canonical concept: Media Reference (not a URL)
Instead of treating stored values as “final URLs”, define a single canonical *media reference* for each entity image.

Media reference types:

- **System default**: a fixed asset shipped with the website (driver defaults: male/female/neutral).
- **Generated**: deterministically generated from an entity id and a seeded pseudo-random source (team/league logos).
- **Uploaded**: a user-uploaded object managed by the media subsystem.
- **None**: intentionally unset.

Key rule: **only one layer resolves media references into URLs**.

### URL resolution responsibilities

- **Backend** resolves *references* into *final URLs* for API payloads.
- **Backend** also serves the image bytes for generated assets and uploaded assets.
- **Frontend** treats received URLs as ready-to-render and does not invent additional fallbacks beyond a single last-resort placeholder.

## Seeding strategy (cleanest route)

### Teams and leagues: seeded via faker, but without storing URLs

Requirement: “seed team and league logos via faker”.

Clean approach:

- During seed, assign each team/league a **Generated** media reference.
- The generator uses faker with a seed derived from the entity id to produce a deterministic “logo identity” (colors, initials, shapes, etc.).
- The stored value is **only the reference** (type + seed key), not a route string and not a URL.
- When the UI needs to show the logo, it either receives a resolved URL in the API payload or uses a single, standardized media URL builder.

Benefits:

- Deterministic results: same team id always yields the same logo.
- No conflicts when URLs/routes change.
- No need to persist binary files for seeded logos.

### Drivers: seeded from the 3 default avatar images

Requirement: “seed driver logos from these defaults” and later “normally these would be user uploads”.

Clean approach:

- During seed, assign each driver a **System default** media reference selecting one of:
  - male-default-avatar
  - female-default-avatar
  - neutral-default-avatar
- Selection is deterministic (based on driver id) so reseeding does not change faces randomly.
- Later, if a user uploads an avatar, the reference switches to **Uploaded** and overrides the default.

Benefits:

- No dependency on generated avatars for baseline.
- No ambiguous meaning of the avatar field.

## Contract rules (what the UI can rely on)

### Field semantics

- Every API payload that includes a driver/team/league image should provide a **single resolved URL field** for that image.
- Resolved URL is either:
  - a valid URL string the UI can render immediately, or
  - null (meaning: show a generic placeholder).
- Never send empty strings.
- Never send “sometimes relative file path, sometimes server route” style mixed values.

### Fallback rules

- The backend resolver must guarantee a valid URL whenever it can (system default or generated).
- The frontend uses exactly one last-resort placeholder if it receives null.
- No per-component bespoke fallbacks.

## Streamlining work items (what changes where)

### 1) Centralize media reference resolution

Create one “media resolver” concept used by:

- API payload assembly for all places that include avatars/logos.
- Image-serving routes for generated assets and uploaded assets.

This resolver is the only place that knows:

- how to map media references to a concrete image URL
- what the fallback is when no uploaded media exists

### 2) Stop storing server route strings as data

Remove the pattern where seed logic writes values like “/api/media/.../logo” into an in-memory media store.

Replace it with:

- stored media references (generated/system-default/uploaded)
- consistent URL resolution at response time

### 3) Normalize route prefixes and caching behavior

- Choose one public URL shape for these images and apply it universally.
- Add consistent cache headers for generated assets (deterministic) so the browser and CDN can cache safely.

### 4) Align frontend consumption

- Ensure the UI always prefers the resolved URL from the API payload.
- Where the UI only has an id (e.g. very lightweight list items), use a single shared “URL builder” instead of ad-hoc string concatenation.
- Remove duplicate “if missing then fallback to …” logic sprinkled across components.

### 5) Align tests and demo fakes

- Eliminate competing fake avatar/logo generators.
- Ensure all test fixtures use the same deterministic rules as seed and runtime generation.
- Ensure snapshot/contract tests treat empty string as invalid and expect null instead.

### 6) Make bootstrapping/reseeding conflict-proof

- Reseed decision should be based on durable data correctness (presence of required entities) rather than transient “in-memory media store” state.
- Ensure “missing avatar/logo” checks are aligned with the new media reference model.

### 7) Migration and cleanup

- Define how existing seeded databases are handled:
  - either a one-time cleanup that rewrites old stored values into the new reference model, or
  - a documented wipe-and-reseed path for local/dev environments.
- Ensure the migration path eliminates stored route strings.

## Mermaid: Target flow

```mermaid
flowchart TD
  UI[Website UI] --> API[API payloads include resolved image URLs]
  API --> RES[Media resolver]
  RES --> UP[Uploaded media storage]
  RES --> GEN[Deterministic generator]
  RES --> DEF[System default assets]
  GEN --> IMG[Image response with cache headers]
  UP --> IMG
  DEF --> UI
  IMG --> UI
```

## Acceptance criteria

- Driver avatars always render with one of the three defaults unless an upload exists.
- Team and league logos always render deterministically in dev/test seed, without persisting URLs.
- No API payload returns empty string for avatar/logo.
- No UI component constructs its own bespoke fallback logic.
- No bootstrapping loop caused by “missing media” when media is generated or defaults are available.