# charan9665/advml2 architecture

> Architecture diagram of the GitHub repository charan9665/advml2, 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/charan9665/advml2
- Repository: https://github.com/charan9665/advml2

## Overview

MovieMind is a full-stack personalized movie recommender. A profile selects a MovieLens user; the API serves catalog recommendations, accepts ratings, converts them to rewards, updates per-profile Q-learning state, and persists feedback for later recommendations and history. Separate offline workflows compare epsilon strategies and evaluate tabular and fitted Q-learning against popularity using chronological MovieLens holdouts. The graph preserves those capabilities and poster lookup; unsampled route details are represented only where documented, so some internal links are omitted.

Main entry points: [`backend/main.py`](https://github.com/charan9665/advml2/blob/main/backend/main.py) (FastAPI service), [`experiments/evaluate.py`](https://github.com/charan9665/advml2/blob/main/experiments/evaluate.py) (Offline evaluation), [`backend/rl/q_learning.py`](https://github.com/charan9665/advml2/blob/main/backend/rl/q_learning.py) (Tabular Q-learner), [`backend/data_loader.py`](https://github.com/charan9665/advml2/blob/main/backend/data_loader.py) (MovieLens loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_app["Web app<br/>[App.jsx]"]
end

subgraph group_api["API and catalog"]
  node_api_service["FastAPI service<br/>[main.py]"]
  node_dataset["MovieLens loader<br/>[data_loader.py]"]
  node_catalog["Movie catalog<br/>[main.py]"]
  node_database[("SQLite persistence<br/>[database.py]")]
  node_poster["Poster lookup<br/>[poster_loader.py]"]
  node_popularity["Popularity ranking<br/>[popularity.py]"]
end

subgraph group_learning["Interactive learning"]
  node_profile["Profile preferences<br/>[main.py]"]
  node_state["Preference state<br/>[state_manager.py]"]
  node_reward["Rating reward<br/>[reward.py]"]
  node_qlearn["Tabular Q-learner<br/>[q_learning.py]"]
  node_qstore[("Persisted Q-table<br/>[main.py]")]
  node_feedback["Rating feedback<br/>[main.py]"]
end

subgraph group_offline["Offline models and evaluation"]
  node_fitted["Fitted Q model"]
  node_experiments["Offline evaluation<br/>[evaluate.py]"]
  node_metrics["Ranking metrics<br/>[evaluation.py]"]
  node_epsilon["Epsilon replay"]
end

node_user(("MovieMind user"))
node_wikipedia["Wikipedia"]

node_user -->|"uses"| node_app
node_app -->|"requests API"| node_api_service
node_api_service -->|"loads dataset"| node_dataset
node_api_service -->|"persists profile data"| node_database
node_api_service -->|"serves catalog"| node_catalog
node_api_service -->|"loads poster"| node_poster
node_poster -->|"looks up artwork"| node_wikipedia
node_api_service -->|"ranks popular titles"| node_popularity
node_api_service -->|"loads preferences"| node_profile
node_profile -->|"derives state"| node_state
node_user -->|"rates recommendation"| node_feedback
node_api_service -->|"accepts rating"| node_feedback
node_feedback -->|"maps rating"| node_reward
node_feedback -->|"updates preferences"| node_state
node_feedback -->|"updates Q-values"| node_qlearn
node_qlearn -->|"saves policy"| node_qstore
node_qstore -->|"restores policy"| node_qlearn
node_api_service -->|"stores feedback history"| node_database
node_experiments -->|"loads ratings"| node_dataset
node_experiments -->|"replays training"| node_qlearn
node_experiments -->|"builds baseline"| node_popularity
node_experiments -->|"trains model"| node_fitted
node_experiments -->|"measures rankings"| node_metrics
node_epsilon -->|"loads ratings"| node_dataset
node_epsilon -->|"compares policies"| node_qlearn
node_api_service -->|"runs training evaluation"| node_metrics

click node_app "https://github.com/charan9665/advml2/blob/main/frontend/src/App.jsx"
click node_api_service "https://github.com/charan9665/advml2/blob/main/backend/main.py"
click node_dataset "https://github.com/charan9665/advml2/blob/main/backend/data_loader.py"
click node_catalog "https://github.com/charan9665/advml2/blob/main/backend/main.py"
click node_database "https://github.com/charan9665/advml2/blob/main/backend/database.py"
click node_poster "https://github.com/charan9665/advml2/blob/main/backend/poster_loader.py"
click node_popularity "https://github.com/charan9665/advml2/blob/main/backend/recommender/popularity.py"
click node_profile "https://github.com/charan9665/advml2/blob/main/backend/main.py"
click node_state "https://github.com/charan9665/advml2/blob/main/backend/rl/state_manager.py"
click node_reward "https://github.com/charan9665/advml2/blob/main/backend/rl/reward.py"
click node_qlearn "https://github.com/charan9665/advml2/blob/main/backend/rl/q_learning.py"
click node_qstore "https://github.com/charan9665/advml2/blob/main/backend/main.py"
click node_feedback "https://github.com/charan9665/advml2/blob/main/backend/main.py"
click node_fitted "https://github.com/charan9665/advml2/blob/main/backend/rl/fitted_q_learning.py"
click node_experiments "https://github.com/charan9665/advml2/blob/main/experiments/evaluate.py"
click node_metrics "https://github.com/charan9665/advml2/blob/main/backend/recommender/evaluation.py"
click node_epsilon "https://github.com/charan9665/advml2/blob/main/experiments/epsilon_experiments.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_app,node_user toneBlue
class node_api_service,node_dataset,node_catalog,node_database,node_poster,node_popularity toneAmber
class node_profile,node_state,node_reward,node_qlearn,node_qstore,node_feedback toneMint
class node_fitted,node_experiments,node_metrics,node_epsilon toneRose
class node_wikipedia toneIndigo
```

## Components

### Web interface

- [Web app](https://github.com/charan9665/advml2/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### API and catalog

- [FastAPI service](https://github.com/charan9665/advml2/blob/main/backend/main.py): `backend/main.py`
- [MovieLens loader](https://github.com/charan9665/advml2/blob/main/backend/data_loader.py): `backend/data_loader.py`
- [Movie catalog](https://github.com/charan9665/advml2/blob/main/backend/main.py): `backend/main.py`
- [SQLite persistence](https://github.com/charan9665/advml2/blob/main/backend/database.py): `backend/database.py`
- [Poster lookup](https://github.com/charan9665/advml2/blob/main/backend/poster_loader.py): `backend/poster_loader.py`
- [Popularity ranking](https://github.com/charan9665/advml2/blob/main/backend/recommender/popularity.py): `backend/recommender/popularity.py`

### Interactive learning

- [Profile preferences](https://github.com/charan9665/advml2/blob/main/backend/main.py): `backend/main.py`
- [Preference state](https://github.com/charan9665/advml2/blob/main/backend/rl/state_manager.py): `backend/rl/state_manager.py`
- [Rating reward](https://github.com/charan9665/advml2/blob/main/backend/rl/reward.py): `backend/rl/reward.py`
- [Tabular Q-learner](https://github.com/charan9665/advml2/blob/main/backend/rl/q_learning.py): `backend/rl/q_learning.py`
- [Persisted Q-table](https://github.com/charan9665/advml2/blob/main/backend/main.py): `backend/main.py`
- [Rating feedback](https://github.com/charan9665/advml2/blob/main/backend/main.py): `backend/main.py`

### Offline models and evaluation

- [Fitted Q model](https://github.com/charan9665/advml2/blob/main/backend/rl/fitted_q_learning.py): `backend/rl/fitted_q_learning.py`
- [Offline evaluation](https://github.com/charan9665/advml2/blob/main/experiments/evaluate.py): `experiments/evaluate.py`
- [Ranking metrics](https://github.com/charan9665/advml2/blob/main/backend/recommender/evaluation.py): `backend/recommender/evaluation.py`
- [Epsilon replay](https://github.com/charan9665/advml2/blob/main/experiments/epsilon_experiments.py): `experiments/epsilon_experiments.py`

### Other components

- **MovieMind user**
- **Wikipedia**

## Connections

- MovieMind user → Web app: uses (evidence: `README.md`)
- Web app → FastAPI service: requests API (evidence: `frontend/src/App.jsx`)
- FastAPI service → MovieLens loader: loads dataset (evidence: `backend/main.py`)
- FastAPI service → SQLite persistence: persists profile data (evidence: `README.md`)
- FastAPI service → Movie catalog: serves catalog (evidence: `backend/main.py`)
- FastAPI service → Poster lookup: loads poster (evidence: `backend/main.py`)
- Poster lookup → Wikipedia: looks up artwork (evidence: `backend/poster_loader.py`)
- FastAPI service → Popularity ranking: ranks popular titles (evidence: `README.md`)
- FastAPI service → Profile preferences: loads preferences (evidence: `README.md`)
- Profile preferences → Preference state: derives state (evidence: `backend/rl/state_manager.py`)
- MovieMind user → Rating feedback: rates recommendation (evidence: `README.md`)
- FastAPI service → Rating feedback: accepts rating (evidence: `README.md`)
- Rating feedback → Rating reward: maps rating (evidence: `README.md`)
- Rating feedback → Preference state: updates preferences (evidence: `README.md`)
- Rating feedback → Tabular Q-learner: updates Q-values (evidence: `README.md`)
- Tabular Q-learner → Persisted Q-table: saves policy (evidence: `README.md`)
- Persisted Q-table → Tabular Q-learner: restores policy (evidence: `README.md`)
- FastAPI service → SQLite persistence: stores feedback history (evidence: `README.md`)
- Offline evaluation → MovieLens loader: loads ratings (evidence: `experiments/evaluate.py`)
- Offline evaluation → Tabular Q-learner: replays training (evidence: `experiments/evaluate.py`)
- Offline evaluation → Popularity ranking: builds baseline (evidence: `experiments/evaluate.py`)
- Offline evaluation → Fitted Q model: trains model (evidence: `experiments/evaluate.py`)
- Offline evaluation → Ranking metrics: measures rankings (evidence: `experiments/evaluate.py`)
- Epsilon replay → MovieLens loader: loads ratings (evidence: `experiments/epsilon_experiments.py`)
- Epsilon replay → Tabular Q-learner: compares policies (evidence: `experiments/epsilon_experiments.py`)
- FastAPI service → Ranking metrics: runs training evaluation (evidence: `backend/main.py`)
