# cwill713/movie-catalog architecture

> Architecture diagram of the GitHub repository cwill713/movie-catalog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cwill713/movie-catalog
- Repository: https://github.com/cwill713/movie-catalog

## Overview

Movie Catalog is a household-oriented movie and TV catalog with a signed-in web UI and REST API. The main workflow resolves a session to a profile, then serves catalog searches/details or watch-list operations through repositories backed by PostgreSQL; the browser UI complements the API. Separate maintenance scripts ingest IMDb data, enrich titles, and generate embeddings. The README describes a simpler SQLite version, while sampled runtime code shows Supabase authentication and PostgreSQL with row-level security. Script and frontend connections are included only where the supplied index or excerpts support them.

Main entry points: [`app/main.py`](https://github.com/cwill713/movie-catalog/blob/main/app/main.py) (FastAPI app), [`app/routes/web.py`](https://github.com/cwill713/movie-catalog/blob/main/app/routes/web.py) (Web pages), [`app/auth.py`](https://github.com/cwill713/movie-catalog/blob/main/app/auth.py) (Session identity), [`app/db.py`](https://github.com/cwill713/movie-catalog/blob/main/app/db.py) (DB access and RLS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application runtime"]
  node_main["FastAPI app<br/>[main.py]"]
  node_web["Web pages<br/>[web.py]"]
  node_api["Watch-list API<br/>[api_movies.py]"]
  node_catalog_api["Catalog API<br/>[catalog.py]"]
  node_templates["Page templates"]
  node_frontend["Browser assets"]
end

subgraph group_identity["Identity and access"]
  node_auth_routes["Login routes<br/>[auth.py]"]
  node_auth["Session identity<br/>[auth.py]"]
  node_config["Settings<br/>[config.py]"]
end

subgraph group_catalog["Catalog and watch list"]
  node_titles_route_repo["Catalog queries<br/>[titles.py]"]
  node_watch_repo["Watch entries<br/>[watch_entries.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
  node_db["DB access and RLS<br/>[db.py]"]
end

subgraph group_maintenance["Catalog maintenance"]
  node_imdb_ingest["IMDb ingestion<br/>[ingest_imdb.py]"]
  node_omdb_enrich["OMDb enrichment<br/>[enrich_omdb.py]"]
  node_embedding["Embedding batches<br/>[db_embedding.py]"]
  node_ablation["Embedding ablation"]
  node_embedding_tests["Embedding evaluation"]
end

node_user(("Household user"))
node_supabase["Supabase Auth"]
node_postgres[("PostgreSQL")]
node_ollama["Ollama"]

node_user -->|"uses"| node_main
node_main -->|"resolves identity"| node_auth
node_main -->|"registers routes"| node_web
node_main -->|"registers routes"| node_api
node_main -->|"registers routes"| node_catalog_api
node_main -->|"registers routes"| node_auth_routes
node_web -->|"loads entries"| node_watch_repo
node_web -->|"loads catalog"| node_titles_route_repo
node_web -->|"renders pages"| node_templates
node_web -.->|"serves UI"| node_frontend
node_api -->|"dispatches operations"| node_watch_repo
node_api -->|"validates payloads"| node_schemas
node_catalog_api -->|"dispatches queries"| node_titles_route_repo
node_catalog_api -->|"uses response models"| node_schemas
node_auth_routes -->|"signs in"| node_auth
node_auth -->|"exchanges credentials"| node_supabase
node_auth -->|"looks up profile"| node_db
node_auth -->|"loads settings"| node_config
node_watch_repo -->|"opens scoped connection"| node_db
node_titles_route_repo -->|"opens scoped connection"| node_db
node_db -->|"queries with RLS"| node_postgres
node_db -->|"gets connection settings"| node_config
node_imdb_ingest -->|"loads settings"| node_config
node_omdb_enrich -->|"loads settings"| node_config
node_embedding -->|"loads settings"| node_config
node_embedding -->|"reads and updates titles"| node_postgres
node_embedding -->|"requests vectors"| node_ollama
node_ablation -->|"uses embedding module"| node_embedding
node_ablation -->|"uses evaluation module"| node_embedding_tests

click node_main "https://github.com/cwill713/movie-catalog/blob/main/app/main.py"
click node_web "https://github.com/cwill713/movie-catalog/blob/main/app/routes/web.py"
click node_api "https://github.com/cwill713/movie-catalog/blob/main/app/routes/api_movies.py"
click node_catalog_api "https://github.com/cwill713/movie-catalog/blob/main/app/routes/catalog.py"
click node_templates "https://github.com/cwill713/movie-catalog/tree/main/app/templates"
click node_frontend "https://github.com/cwill713/movie-catalog/tree/main/app/static"
click node_auth_routes "https://github.com/cwill713/movie-catalog/blob/main/app/routes/auth.py"
click node_auth "https://github.com/cwill713/movie-catalog/blob/main/app/auth.py"
click node_config "https://github.com/cwill713/movie-catalog/blob/main/app/config.py"
click node_titles_route_repo "https://github.com/cwill713/movie-catalog/blob/main/app/repositories/titles.py"
click node_watch_repo "https://github.com/cwill713/movie-catalog/blob/main/app/repositories/watch_entries.py"
click node_schemas "https://github.com/cwill713/movie-catalog/blob/main/app/schemas.py"
click node_db "https://github.com/cwill713/movie-catalog/blob/main/app/db.py"
click node_imdb_ingest "https://github.com/cwill713/movie-catalog/blob/main/scripts/ingest_imdb.py"
click node_omdb_enrich "https://github.com/cwill713/movie-catalog/blob/main/scripts/enrich_omdb.py"
click node_embedding "https://github.com/cwill713/movie-catalog/blob/main/scripts/db_embedding.py"
click node_ablation "https://github.com/cwill713/movie-catalog/blob/main/scripts/embedding_ablation.py"
click node_embedding_tests "https://github.com/cwill713/movie-catalog/blob/main/scripts/testing_embeddings.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_main,node_web,node_api,node_catalog_api,node_templates,node_frontend,node_user toneBlue
class node_auth_routes,node_auth,node_config,node_postgres toneAmber
class node_titles_route_repo,node_watch_repo,node_schemas,node_db toneMint
class node_imdb_ingest,node_omdb_enrich,node_embedding,node_ablation,node_embedding_tests toneRose
class node_supabase,node_ollama toneIndigo
```

## Components

### Application runtime

- [FastAPI app](https://github.com/cwill713/movie-catalog/blob/main/app/main.py): `app/main.py`
- [Web pages](https://github.com/cwill713/movie-catalog/blob/main/app/routes/web.py): `app/routes/web.py`
- [Watch-list API](https://github.com/cwill713/movie-catalog/blob/main/app/routes/api_movies.py): `app/routes/api_movies.py`
- [Catalog API](https://github.com/cwill713/movie-catalog/blob/main/app/routes/catalog.py): `app/routes/catalog.py`
- [Page templates](https://github.com/cwill713/movie-catalog/tree/main/app/templates): `app/templates`
- [Browser assets](https://github.com/cwill713/movie-catalog/tree/main/app/static): `app/static`

### Identity and access

- [Login routes](https://github.com/cwill713/movie-catalog/blob/main/app/routes/auth.py): `app/routes/auth.py`
- [Session identity](https://github.com/cwill713/movie-catalog/blob/main/app/auth.py): `app/auth.py`
- [Settings](https://github.com/cwill713/movie-catalog/blob/main/app/config.py): `app/config.py`

### Catalog and watch list

- [Catalog queries](https://github.com/cwill713/movie-catalog/blob/main/app/repositories/titles.py): `app/repositories/titles.py`
- [Watch entries](https://github.com/cwill713/movie-catalog/blob/main/app/repositories/watch_entries.py): `app/repositories/watch_entries.py`
- [API schemas](https://github.com/cwill713/movie-catalog/blob/main/app/schemas.py): `app/schemas.py`
- [DB access and RLS](https://github.com/cwill713/movie-catalog/blob/main/app/db.py): `app/db.py`

### Catalog maintenance

- [IMDb ingestion](https://github.com/cwill713/movie-catalog/blob/main/scripts/ingest_imdb.py): `scripts/ingest_imdb.py`
- [OMDb enrichment](https://github.com/cwill713/movie-catalog/blob/main/scripts/enrich_omdb.py): `scripts/enrich_omdb.py`
- [Embedding batches](https://github.com/cwill713/movie-catalog/blob/main/scripts/db_embedding.py): `scripts/db_embedding.py`
- [Embedding ablation](https://github.com/cwill713/movie-catalog/blob/main/scripts/embedding_ablation.py): `scripts/embedding_ablation.py`
- [Embedding evaluation](https://github.com/cwill713/movie-catalog/blob/main/scripts/testing_embeddings.py): `scripts/testing_embeddings.py`

### Other components

- **Household user**
- **Supabase Auth**
- **PostgreSQL**
- **Ollama**

## Connections

- Household user → FastAPI app: uses (evidence: `README.md`)
- FastAPI app → Session identity: resolves identity (evidence: `app/main.py`)
- FastAPI app → Web pages: registers routes (evidence: `app/main.py`)
- FastAPI app → Watch-list API: registers routes (evidence: `app/main.py`)
- FastAPI app → Catalog API: registers routes (evidence: `app/main.py`)
- FastAPI app → Login routes: registers routes (evidence: `app/main.py`)
- Web pages → Watch entries: loads entries (evidence: `app/routes/web.py`)
- Web pages → Catalog queries: loads catalog (evidence: `app/routes/web.py`)
- Web pages → Page templates: renders pages (evidence: `app/routes/web.py`)
- Web pages → Browser assets: serves UI (evidence: `README.md`)
- Watch-list API → Watch entries: dispatches operations (evidence: `app/routes/api_movies.py`)
- Watch-list API → API schemas: validates payloads (evidence: `app/routes/api_movies.py`)
- Catalog API → Catalog queries: dispatches queries (evidence: `app/routes/catalog.py`)
- Catalog API → API schemas: uses response models (evidence: `app/routes/catalog.py`)
- Login routes → Session identity: signs in (evidence: `app/routes/auth.py`)
- Session identity → Supabase Auth: exchanges credentials (evidence: `app/auth.py`)
- Session identity → DB access and RLS: looks up profile (evidence: `app/auth.py`)
- Session identity → Settings: loads settings (evidence: `app/auth.py`)
- Watch entries → DB access and RLS: opens scoped connection (evidence: `app/repositories/watch_entries.py`)
- Catalog queries → DB access and RLS: opens scoped connection (evidence: `app/repositories/titles.py`)
- DB access and RLS → PostgreSQL: queries with RLS (evidence: `app/db.py`)
- DB access and RLS → Settings: gets connection settings (evidence: `app/db.py`)
- IMDb ingestion → Settings: loads settings (evidence: `scripts/ingest_imdb.py`)
- OMDb enrichment → Settings: loads settings (evidence: `scripts/enrich_omdb.py`)
- Embedding batches → Settings: loads settings (evidence: `scripts/db_embedding.py`)
- Embedding batches → PostgreSQL: reads and updates titles (evidence: `scripts/db_embedding.py`)
- Embedding batches → Ollama: requests vectors (evidence: `scripts/db_embedding.py`)
- Embedding ablation → Embedding batches: uses embedding module (evidence: `scripts/embedding_ablation.py`)
- Embedding ablation → Embedding evaluation: uses evaluation module (evidence: `scripts/embedding_ablation.py`)
