# enrique-diazv/watch-later-universal architecture

> Architecture diagram of the GitHub repository enrique-diazv/watch-later-universal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/enrique-diazv/watch-later-universal
- Repository: https://github.com/enrique-diazv/watch-later-universal

## Overview

Watch Later Universal lets people discover films and series, inspect details and streaming availability, then maintain a personal watch library. The main journey runs from the React search and detail views through the API client to FastAPI’s catalog endpoints and TMDB; authenticated users can save and organize titles in PostgreSQL. Authentication adds verification, password recovery and rotating sessions. The README documents the production email integration. Some endpoint and service implementations were not excerpted, so links involving them rely only on the source index or README; unsampled behavior is not inferred.

Main entry points: [`frontend/src/services/api.ts`](https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/services/api.ts) (API client), [`backend/app/api/v1/router.py`](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/router.py) (Versioned router), [`backend/app/api/v1/endpoints/auth.py`](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/endpoints/auth.py) (Account endpoints), [`frontend/src/App.tsx`](https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/App.tsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_spa["React application<br/>[App.tsx]"]
  node_search_ui["Search view<br/>[SearchPage.tsx]"]
  node_details_ui["Media details"]
  node_library_ui["Personal library<br/>[LibraryPage.tsx]"]
  node_auth_ui["Account views<br/>[AuthPage.tsx]"]
  node_auth_context["Auth state<br/>[AuthContext.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_api_types["API data types<br/>[api.ts]"]
end

subgraph group_api["API workflows"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_router["Versioned router<br/>[router.py]"]
  node_search_endpoint["Catalog search<br/>[search.py]"]
  node_media_endpoint["Media details<br/>[media.py]"]
  node_providers_endpoint["Watch providers<br/>[providers.py]"]
  node_library_endpoint["Library operations<br/>[library.py]"]
end

subgraph group_identity["Identity services"]
  node_auth_endpoint["Account endpoints<br/>[auth.py]"]
  node_auth_service["Session tokens<br/>[auth.py]"]
  node_security["Token security<br/>[security.py]"]
  node_verification["Email verification"]
  node_email["Email delivery<br/>[email.py]"]
end

subgraph group_catalog["Catalog integration"]
  node_tmdb_client["TMDB client<br/>[client.py]"]
end

subgraph group_persistence["Persistence"]
  node_catalog_service["Catalog persistence<br/>[catalog.py]"]
  node_media_model["Media records<br/>[media.py]"]
  node_library_model["Library records<br/>[library.py]"]
  node_user_model["User records<br/>[user.py]"]
  node_refresh_model["Refresh tokens<br/>[refresh_token.py]"]
  node_db_session["Database sessions<br/>[session.py]"]
end

node_browser(("User browser"))
node_brevo["Brevo email"]
node_tmdb["TMDB catalog"]
node_postgres[("PostgreSQL")]

node_browser -->|"uses"| node_spa
node_spa -->|"routes to"| node_search_ui
node_spa -->|"routes to"| node_details_ui
node_spa -->|"routes to"| node_library_ui
node_spa -->|"routes to"| node_auth_ui
node_auth_ui -->|"requests"| node_api_client
node_auth_ui -->|"uses"| node_auth_context
node_auth_context -->|"calls"| node_api_client
node_search_ui -->|"searches"| node_api_client
node_details_ui -->|"loads details"| node_api_client
node_library_ui -->|"manages items"| node_api_client
node_api_client -->|"uses types"| node_api_types
node_api_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"mounts"| node_router
node_router -->|"registers"| node_search_endpoint
node_router -->|"registers"| node_media_endpoint
node_router -->|"registers"| node_providers_endpoint
node_router -->|"registers"| node_library_endpoint
node_router -->|"registers"| node_auth_endpoint
node_search_endpoint -->|"queries"| node_tmdb_client
node_media_endpoint -->|"fetches details"| node_tmdb_client
node_providers_endpoint -->|"fetches providers"| node_tmdb_client
node_tmdb_client -->|"requests catalog data"| node_tmdb
node_library_endpoint -->|"uses"| node_catalog_service
node_library_endpoint -->|"queries"| node_media_model
node_library_endpoint -->|"manages"| node_library_model
node_auth_endpoint -->|"issues and rotates"| node_auth_service
node_auth_endpoint -->|"verifies accounts"| node_verification
node_auth_endpoint -->|"sends messages"| node_email
node_email -.->|"delivers via"| node_brevo
node_auth_endpoint -->|"hashes credentials"| node_security
node_auth_service -->|"hashes tokens"| node_security
node_auth_service -->|"persists tokens"| node_refresh_model
node_verification -->|"updates account"| node_user_model
node_library_endpoint -->|"uses session"| node_db_session
node_auth_endpoint -->|"uses session"| node_db_session
node_db_session -->|"connects"| node_postgres
node_catalog_service -->|"updates records"| node_media_model
node_media_model -->|"stored in"| node_postgres
node_library_model -->|"stored in"| node_postgres
node_user_model -->|"stored in"| node_postgres
node_refresh_model -->|"stored in"| node_postgres

click node_spa "https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/App.tsx"
click node_search_ui "https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/features/search/SearchPage.tsx"
click node_details_ui "https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/features/media/MediaDetailsPage.tsx"
click node_library_ui "https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/features/library/LibraryPage.tsx"
click node_auth_ui "https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/features/auth/AuthPage.tsx"
click node_auth_context "https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/features/auth/AuthContext.tsx"
click node_api_client "https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/services/api.ts"
click node_api_types "https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/types/api.ts"
click node_fastapi "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/main.py"
click node_router "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/router.py"
click node_search_endpoint "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/endpoints/search.py"
click node_media_endpoint "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/endpoints/media.py"
click node_providers_endpoint "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/endpoints/providers.py"
click node_library_endpoint "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/endpoints/library.py"
click node_auth_endpoint "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_auth_service "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/services/auth.py"
click node_security "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/core/security.py"
click node_verification "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/services/email_verification.py"
click node_email "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/services/email.py"
click node_tmdb_client "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/integrations/tmdb/client.py"
click node_catalog_service "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/services/catalog.py"
click node_media_model "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/models/media.py"
click node_library_model "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/models/library.py"
click node_user_model "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/models/user.py"
click node_refresh_model "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/models/refresh_token.py"
click node_db_session "https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/db/session.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spa,node_search_ui,node_details_ui,node_library_ui,node_auth_ui,node_auth_context,node_api_client,node_api_types,node_browser toneBlue
class node_fastapi,node_router,node_search_endpoint,node_media_endpoint,node_providers_endpoint,node_library_endpoint,node_postgres toneAmber
class node_auth_endpoint,node_auth_service,node_security,node_verification,node_email toneMint
class node_tmdb_client toneRose
class node_catalog_service,node_media_model,node_library_model,node_user_model,node_refresh_model,node_db_session,node_brevo,node_tmdb toneIndigo
```

## Components

### Web experience

- [React application](https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Search view](https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/features/search/SearchPage.tsx): `frontend/src/features/search/SearchPage.tsx`
- [Media details](https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/features/media/MediaDetailsPage.tsx): `frontend/src/features/media/MediaDetailsPage.tsx`
- [Personal library](https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/features/library/LibraryPage.tsx): `frontend/src/features/library/LibraryPage.tsx`
- [Account views](https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/features/auth/AuthPage.tsx): `frontend/src/features/auth/AuthPage.tsx`
- [Auth state](https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/features/auth/AuthContext.tsx): `frontend/src/features/auth/AuthContext.tsx`
- [API client](https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [API data types](https://github.com/enrique-diazv/watch-later-universal/blob/main/frontend/src/types/api.ts): `frontend/src/types/api.ts`

### API workflows

- [FastAPI application](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/main.py): `backend/app/main.py`
- [Versioned router](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Catalog search](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/endpoints/search.py): `backend/app/api/v1/endpoints/search.py`
- [Media details](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/endpoints/media.py): `backend/app/api/v1/endpoints/media.py`
- [Watch providers](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/endpoints/providers.py): `backend/app/api/v1/endpoints/providers.py`
- [Library operations](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/endpoints/library.py): `backend/app/api/v1/endpoints/library.py`

### Identity services

- [Account endpoints](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [Session tokens](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/services/auth.py): `backend/app/services/auth.py`
- [Token security](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Email verification](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/services/email_verification.py): `backend/app/services/email_verification.py`
- [Email delivery](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/services/email.py): `backend/app/services/email.py`

### Catalog integration

- [TMDB client](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/integrations/tmdb/client.py): `backend/app/integrations/tmdb/client.py`

### Persistence

- [Catalog persistence](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/services/catalog.py): `backend/app/services/catalog.py`
- [Media records](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/models/media.py): `backend/app/models/media.py`
- [Library records](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/models/library.py): `backend/app/models/library.py`
- [User records](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [Refresh tokens](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/models/refresh_token.py): `backend/app/models/refresh_token.py`
- [Database sessions](https://github.com/enrique-diazv/watch-later-universal/blob/main/backend/app/db/session.py): `backend/app/db/session.py`

### Other components

- **User browser**
- **Brevo email**
- **TMDB catalog**
- **PostgreSQL**

## Connections

- User browser → React application: uses
- React application → Search view: routes to (evidence: `frontend/src/App.tsx`)
- React application → Media details: routes to (evidence: `frontend/src/App.tsx`)
- React application → Personal library: routes to (evidence: `frontend/src/App.tsx`)
- React application → Account views: routes to (evidence: `frontend/src/App.tsx`)
- Account views → API client: requests (evidence: `frontend/src/features/auth/AuthPage.tsx`)
- Account views → Auth state: uses (evidence: `frontend/src/features/auth/AuthPage.tsx`)
- Auth state → API client: calls (evidence: `frontend/src/features/auth/AuthContext.tsx`)
- Search view → API client: searches (evidence: `frontend/src/features/search/SearchPage.tsx`)
- Media details → API client: loads details (evidence: `frontend/src/features/media/MediaDetailsPage.tsx`)
- Personal library → API client: manages items (evidence: `frontend/src/features/library/LibraryPage.tsx`)
- API client → API data types: uses types (evidence: `frontend/src/services/api.ts`)
- API client → FastAPI application: HTTP requests
- FastAPI application → Versioned router: mounts (evidence: `backend/app/main.py`)
- Versioned router → Catalog search: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned router → Media details: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned router → Watch providers: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned router → Library operations: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned router → Account endpoints: registers (evidence: `backend/app/api/v1/router.py`)
- Catalog search → TMDB client: queries (evidence: `backend/app/api/v1/endpoints/search.py`)
- Media details → TMDB client: fetches details (evidence: `backend/app/api/v1/endpoints/media.py`)
- Watch providers → TMDB client: fetches providers (evidence: `backend/app/api/v1/endpoints/providers.py`)
- TMDB client → TMDB catalog: requests catalog data (evidence: `backend/app/integrations/tmdb/client.py`)
- Library operations → Catalog persistence: uses (evidence: `backend/app/api/v1/endpoints/library.py`)
- Library operations → Media records: queries (evidence: `backend/app/api/v1/endpoints/library.py`)
- Library operations → Library records: manages (evidence: `backend/app/api/v1/endpoints/library.py`)
- Account endpoints → Session tokens: issues and rotates (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Account endpoints → Email verification: verifies accounts (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Account endpoints → Email delivery: sends messages (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Email delivery → Brevo email: delivers via
- Account endpoints → Token security: hashes credentials (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Session tokens → Token security: hashes tokens (evidence: `backend/app/services/auth.py`)
- Session tokens → Refresh tokens: persists tokens (evidence: `backend/app/services/auth.py`)
- Email verification → User records: updates account (evidence: `backend/app/services/email_verification.py`)
- Library operations → Database sessions: uses session (evidence: `backend/app/api/v1/endpoints/library.py`)
- Account endpoints → Database sessions: uses session (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Database sessions → PostgreSQL: connects
- Catalog persistence → Media records: updates records (evidence: `backend/app/services/catalog.py`)
- Media records → PostgreSQL: stored in
- Library records → PostgreSQL: stored in
- User records → PostgreSQL: stored in
- Refresh tokens → PostgreSQL: stored in
