# icecold009/movie-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/icecold009/movie-tracker
- Repository: https://github.com/icecold009/movie-tracker

## Overview

My Watch Tracker is a Flask-backed public watchlist with a password-protected single-admin workflow. Visitors browse movie and TV entries; the admin signs in to add titles, search TMDB metadata, edit ratings and status, or delete entries. The app stores watchlist data and aggregate usage counts in PostgreSQL, and offers explainable recommendations using saved genre metadata with popular-title fallback. The graph preserves the documented recommendation benchmark and browser features. Some route-to-module links rely on the SOURCE INDEX and README; unsampled implementation details are not inferred.

Main entry points: [`api/index.py`](https://github.com/icecold009/movie-tracker/blob/main/api/index.py) (Flask routes), [`database.py`](https://github.com/icecold009/movie-tracker/blob/main/database.py) (Watchlist operations), [`tmdb.py`](https://github.com/icecold009/movie-tracker/blob/main/tmdb.py) (TMDB metadata lookup), [`observability.py`](https://github.com/icecold009/movie-tracker/blob/main/observability.py) (Structured diagnostics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_flask["Flask routes<br/>[index.py]"]
  node_browser["Watchlist interface"]
  node_ui["Browser interactions<br/>[app.js]"]
  node_auth["Admin session and validation<br/>[index.py]"]
end

subgraph group_domain["Watchlist domain"]
  node_entries["Watchlist operations<br/>[database.py]"]
  node_postgres[("PostgreSQL watchlist")]
  node_logging["Structured diagnostics<br/>[observability.py]"]
end

subgraph group_integrations["External services"]
  node_metadata["TMDB metadata lookup<br/>[tmdb.py]"]
  node_tmdb["TMDB API"]
end

subgraph group_insights["Recommendations and measurement"]
  node_recommender["Explainable recommendations<br/>[recommendations.py]"]
  node_recommendation_page["Recommendations page"]
  node_usage["Daily usage counts<br/>[database.py]"]
  node_evaluation["Offline recommender evaluation"]
end

node_visitor(("Public visitor"))
node_admin(("Admin"))

node_visitor -->|"browses"| node_flask
node_admin -->|"manages watchlist"| node_flask
node_flask -->|"checks session"| node_auth
node_flask -->|"renders pages"| node_browser
node_browser -.->|"loads interactions"| node_ui
node_ui -->|"searches titles"| node_flask
node_flask -->|"reads and mutates"| node_entries
node_entries -->|"queries and updates"| node_postgres
node_flask -->|"searches titles"| node_metadata
node_metadata -->|"requests metadata"| node_tmdb
node_flask -.->|"builds suggestions"| node_recommender
node_flask -.->|"renders suggestions"| node_recommendation_page
node_flask -->|"records activity"| node_usage
node_usage -->|"increments counters"| node_postgres
node_evaluation -->|"evaluates ranking"| node_recommender
node_evaluation -->|"fetches catalog"| node_tmdb
node_flask -.->|"emits events"| node_logging
node_entries -->|"emits events"| node_logging
node_metadata -->|"emits events"| node_logging

click node_flask "https://github.com/icecold009/movie-tracker/blob/main/api/index.py"
click node_browser "https://github.com/icecold009/movie-tracker/tree/main/templates"
click node_ui "https://github.com/icecold009/movie-tracker/blob/main/static/app.js"
click node_auth "https://github.com/icecold009/movie-tracker/blob/main/api/index.py"
click node_entries "https://github.com/icecold009/movie-tracker/blob/main/database.py"
click node_metadata "https://github.com/icecold009/movie-tracker/blob/main/tmdb.py"
click node_recommender "https://github.com/icecold009/movie-tracker/blob/main/recommendations.py"
click node_recommendation_page "https://github.com/icecold009/movie-tracker/tree/main/templates"
click node_usage "https://github.com/icecold009/movie-tracker/blob/main/database.py"
click node_evaluation "https://github.com/icecold009/movie-tracker/blob/main/scripts/evaluate_recommender.py"
click node_logging "https://github.com/icecold009/movie-tracker/blob/main/observability.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_flask,node_browser,node_ui,node_auth toneBlue
class node_entries,node_postgres,node_logging toneAmber
class node_metadata,node_tmdb toneMint
class node_recommender,node_recommendation_page,node_usage,node_evaluation toneRose
class node_visitor,node_admin toneIndigo
```

## Components

### Web application

- [Flask routes](https://github.com/icecold009/movie-tracker/blob/main/api/index.py): `api/index.py`
- [Watchlist interface](https://github.com/icecold009/movie-tracker/tree/main/templates): `templates`
- [Browser interactions](https://github.com/icecold009/movie-tracker/blob/main/static/app.js): `static/app.js`
- [Admin session and validation](https://github.com/icecold009/movie-tracker/blob/main/api/index.py): `api/index.py`

### Watchlist domain

- [Watchlist operations](https://github.com/icecold009/movie-tracker/blob/main/database.py): `database.py`
- **PostgreSQL watchlist**
- [Structured diagnostics](https://github.com/icecold009/movie-tracker/blob/main/observability.py): `observability.py`

### External services

- [TMDB metadata lookup](https://github.com/icecold009/movie-tracker/blob/main/tmdb.py): `tmdb.py`
- **TMDB API**

### Recommendations and measurement

- [Explainable recommendations](https://github.com/icecold009/movie-tracker/blob/main/recommendations.py): `recommendations.py`
- [Recommendations page](https://github.com/icecold009/movie-tracker/tree/main/templates): `templates`
- [Daily usage counts](https://github.com/icecold009/movie-tracker/blob/main/database.py): `database.py`
- [Offline recommender evaluation](https://github.com/icecold009/movie-tracker/blob/main/scripts/evaluate_recommender.py): `scripts/evaluate_recommender.py`

### Other components

- **Public visitor**
- **Admin**

## Connections

- Public visitor → Flask routes: browses (evidence: `README.md`)
- Admin → Flask routes: manages watchlist (evidence: `README.md`)
- Flask routes → Admin session and validation: checks session (evidence: `api/index.py`)
- Flask routes → Watchlist interface: renders pages (evidence: `api/index.py`)
- Watchlist interface → Browser interactions: loads interactions
- Browser interactions → Flask routes: searches titles (evidence: `static/app.js`)
- Flask routes → Watchlist operations: reads and mutates (evidence: `api/index.py`)
- Watchlist operations → PostgreSQL watchlist: queries and updates (evidence: `database.py`)
- Flask routes → TMDB metadata lookup: searches titles (evidence: `api/index.py`)
- TMDB metadata lookup → TMDB API: requests metadata (evidence: `tmdb.py`)
- Flask routes → Explainable recommendations: builds suggestions (evidence: `api/index.py`)
- Flask routes → Recommendations page: renders suggestions
- Flask routes → Daily usage counts: records activity (evidence: `api/index.py`)
- Daily usage counts → PostgreSQL watchlist: increments counters (evidence: `database.py`)
- Offline recommender evaluation → Explainable recommendations: evaluates ranking (evidence: `scripts/evaluate_recommender.py`)
- Offline recommender evaluation → TMDB API: fetches catalog (evidence: `scripts/evaluate_recommender.py`)
- Flask routes → Structured diagnostics: emits events (evidence: `api/index.py`)
- Watchlist operations → Structured diagnostics: emits events (evidence: `database.py`)
- TMDB metadata lookup → Structured diagnostics: emits events (evidence: `tmdb.py`)
