# charan9665/advml architecture

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

- Interactive diagram: https://gitdiagram.com/charan9665/advml
- Repository: https://github.com/charan9665/advml

## Overview

This repository combines an offline MovieLens reinforcement-learning study with a personalized movie web application served from its trained Q-table. The research workflow loads and prepares logged ratings, replays user histories to train policies, then compares and evaluates them. The web workflow authenticates users, serves recommendations and movie features, and persists account-specific state; the React client calls the API and renders those features. The backend’s catalog and poster resolver are useful internal layers. Several backend routes and frontend page details are unsampled, so those links rely only on explicit imports, API calls, or documented behavior.

Main entry points: [`main.py`](https://github.com/charan9665/advml/blob/main/main.py) (Study runner), [`webapp/backend/app.py`](https://github.com/charan9665/advml/blob/main/webapp/backend/app.py) (FastAPI service), [`src/experiments.py`](https://github.com/charan9665/advml/blob/main/src/experiments.py) (Parameter experiments), [`src/train.py`](https://github.com/charan9665/advml/blob/main/src/train.py) (Policy training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_study["Offline RL study"]
  node_runner["Study runner<br/>[main.py]"]
  node_settings["Experiment settings<br/>[config.py]"]
  node_loader["MovieLens loader<br/>[data_loader.py]"]
  node_eda["Data exploration<br/>[eda.py]"]
  node_prep["Chronological splits<br/>[preprocessing.py]"]
  node_replay["Replay environment<br/>[environment.py]"]
  node_agents["Q-learning agents<br/>[agents.py]"]
  node_trainer["Policy training<br/>[train.py]"]
  node_baselines["Baseline policies<br/>[baselines.py]"]
  node_evaluation["Policy evaluation<br/>[evaluate.py]"]
  node_experiments["Parameter experiments<br/>[experiments.py]"]
  node_plots["Results plots<br/>[plots.py]"]
end

subgraph group_serving["Recommendation backend"]
  node_backend["FastAPI service<br/>[app.py]"]
  node_catalog[("Movie catalog<br/>[app.py]")]
  node_state[("SQLite user and cache data<br/>[app.py]")]
end

subgraph group_web["Web client"]
  node_client["React application<br/>[App.jsx]"]
  node_pages["Application pages<br/>[pages.jsx]"]
  node_api["API client<br/>[api.js]"]
  node_cards["Movie cards<br/>[MovieCard.jsx]"]
end

subgraph group_artwork["Movie artwork"]
  node_posterui["Poster display<br/>[Poster.jsx]"]
  node_resolver["TMDB poster resolver<br/>[tmdb_posters.py]"]
end

node_user(("Movie viewer"))
node_tmdb["TMDB"]

node_runner -->|"loads data"| node_loader
node_runner -->|"runs exploration"| node_eda
node_runner -->|"prepares splits"| node_prep
node_runner -->|"trains policy"| node_trainer
node_runner -->|"tunes parameters"| node_experiments
node_runner -->|"evaluates policies"| node_evaluation
node_runner -->|"saves plots"| node_plots
node_runner -->|"creates baselines"| node_baselines
node_trainer -->|"replays histories"| node_replay
node_trainer -->|"updates policy"| node_agents
node_evaluation -->|"replays test histories"| node_replay
node_experiments -->|"runs training"| node_trainer
node_experiments -->|"compares policies"| node_evaluation
node_experiments -->|"plots comparisons"| node_plots
node_user -->|"uses"| node_client
node_client -->|"renders pages"| node_pages
node_client -->|"requests data"| node_api
node_pages -->|"requests page data"| node_api
node_api -->|"sends HTTP requests"| node_backend
node_backend -->|"loads MovieLens and Q table"| node_catalog
node_backend -->|"uses Q policy"| node_agents
node_backend -->|"creates resolver"| node_resolver
node_backend -->|"reads and writes"| node_state
node_resolver -->|"caches artwork"| node_state
node_resolver -->|"searches titles"| node_tmdb
node_cards -->|"renders artwork"| node_posterui
node_posterui -->|"resolves artwork"| node_api
node_backend -.->|"returns recommendations and features"| node_user

click node_runner "https://github.com/charan9665/advml/blob/main/main.py"
click node_settings "https://github.com/charan9665/advml/blob/main/config.py"
click node_loader "https://github.com/charan9665/advml/blob/main/src/data_loader.py"
click node_eda "https://github.com/charan9665/advml/blob/main/src/eda.py"
click node_prep "https://github.com/charan9665/advml/blob/main/src/preprocessing.py"
click node_replay "https://github.com/charan9665/advml/blob/main/src/environment.py"
click node_agents "https://github.com/charan9665/advml/blob/main/src/agents.py"
click node_trainer "https://github.com/charan9665/advml/blob/main/src/train.py"
click node_baselines "https://github.com/charan9665/advml/blob/main/src/baselines.py"
click node_evaluation "https://github.com/charan9665/advml/blob/main/src/evaluate.py"
click node_experiments "https://github.com/charan9665/advml/blob/main/src/experiments.py"
click node_plots "https://github.com/charan9665/advml/blob/main/src/plots.py"
click node_client "https://github.com/charan9665/advml/blob/main/webapp/frontend/src/App.jsx"
click node_pages "https://github.com/charan9665/advml/blob/main/webapp/frontend/src/pages.jsx"
click node_api "https://github.com/charan9665/advml/blob/main/webapp/frontend/src/api.js"
click node_cards "https://github.com/charan9665/advml/blob/main/webapp/frontend/src/components/MovieCard.jsx"
click node_posterui "https://github.com/charan9665/advml/blob/main/webapp/frontend/src/components/Poster.jsx"
click node_backend "https://github.com/charan9665/advml/blob/main/webapp/backend/app.py"
click node_catalog "https://github.com/charan9665/advml/blob/main/webapp/backend/app.py"
click node_resolver "https://github.com/charan9665/advml/blob/main/webapp/backend/tmdb_posters.py"
click node_state "https://github.com/charan9665/advml/blob/main/webapp/backend/app.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_runner,node_settings,node_loader,node_eda,node_prep,node_replay,node_agents,node_trainer,node_baselines,node_evaluation,node_experiments,node_plots,node_user toneBlue
class node_backend,node_catalog,node_state toneAmber
class node_client,node_pages,node_api,node_cards toneMint
class node_posterui,node_resolver toneRose
class node_tmdb toneIndigo
```

## Components

### Offline RL study

- [Study runner](https://github.com/charan9665/advml/blob/main/main.py): `main.py`
- [Experiment settings](https://github.com/charan9665/advml/blob/main/config.py): `config.py`
- [MovieLens loader](https://github.com/charan9665/advml/blob/main/src/data_loader.py): `src/data_loader.py`
- [Data exploration](https://github.com/charan9665/advml/blob/main/src/eda.py): `src/eda.py`
- [Chronological splits](https://github.com/charan9665/advml/blob/main/src/preprocessing.py): `src/preprocessing.py`
- [Replay environment](https://github.com/charan9665/advml/blob/main/src/environment.py): `src/environment.py`
- [Q-learning agents](https://github.com/charan9665/advml/blob/main/src/agents.py): `src/agents.py`
- [Policy training](https://github.com/charan9665/advml/blob/main/src/train.py): `src/train.py`
- [Baseline policies](https://github.com/charan9665/advml/blob/main/src/baselines.py): `src/baselines.py`
- [Policy evaluation](https://github.com/charan9665/advml/blob/main/src/evaluate.py): `src/evaluate.py`
- [Parameter experiments](https://github.com/charan9665/advml/blob/main/src/experiments.py): `src/experiments.py`
- [Results plots](https://github.com/charan9665/advml/blob/main/src/plots.py): `src/plots.py`

### Recommendation backend

- [FastAPI service](https://github.com/charan9665/advml/blob/main/webapp/backend/app.py): `webapp/backend/app.py`
- [Movie catalog](https://github.com/charan9665/advml/blob/main/webapp/backend/app.py): `webapp/backend/app.py`
- [SQLite user and cache data](https://github.com/charan9665/advml/blob/main/webapp/backend/app.py): `webapp/backend/app.py`

### Web client

- [React application](https://github.com/charan9665/advml/blob/main/webapp/frontend/src/App.jsx): `webapp/frontend/src/App.jsx`
- [Application pages](https://github.com/charan9665/advml/blob/main/webapp/frontend/src/pages.jsx): `webapp/frontend/src/pages.jsx`
- [API client](https://github.com/charan9665/advml/blob/main/webapp/frontend/src/api.js): `webapp/frontend/src/api.js`
- [Movie cards](https://github.com/charan9665/advml/blob/main/webapp/frontend/src/components/MovieCard.jsx): `webapp/frontend/src/components/MovieCard.jsx`

### Movie artwork

- [Poster display](https://github.com/charan9665/advml/blob/main/webapp/frontend/src/components/Poster.jsx): `webapp/frontend/src/components/Poster.jsx`
- [TMDB poster resolver](https://github.com/charan9665/advml/blob/main/webapp/backend/tmdb_posters.py): `webapp/backend/tmdb_posters.py`

### Other components

- **Movie viewer**
- **TMDB**

## Connections

- Study runner → MovieLens loader: loads data (evidence: `main.py`)
- Study runner → Data exploration: runs exploration (evidence: `main.py`)
- Study runner → Chronological splits: prepares splits (evidence: `main.py`)
- Study runner → Policy training: trains policy (evidence: `main.py`)
- Study runner → Parameter experiments: tunes parameters (evidence: `main.py`)
- Study runner → Policy evaluation: evaluates policies (evidence: `main.py`)
- Study runner → Results plots: saves plots (evidence: `main.py`)
- Study runner → Baseline policies: creates baselines (evidence: `main.py`)
- Policy training → Replay environment: replays histories (evidence: `src/train.py`)
- Policy training → Q-learning agents: updates policy (evidence: `src/train.py`)
- Policy evaluation → Replay environment: replays test histories (evidence: `src/evaluate.py`)
- Parameter experiments → Policy training: runs training (evidence: `src/experiments.py`)
- Parameter experiments → Policy evaluation: compares policies (evidence: `src/experiments.py`)
- Parameter experiments → Results plots: plots comparisons (evidence: `src/experiments.py`)
- Movie viewer → React application: uses (evidence: `webapp/frontend/src/App.jsx`)
- React application → Application pages: renders pages (evidence: `webapp/frontend/src/App.jsx`)
- React application → API client: requests data (evidence: `webapp/frontend/src/App.jsx`)
- Application pages → API client: requests page data (evidence: `webapp/frontend/src/pages.jsx`)
- API client → FastAPI service: sends HTTP requests (evidence: `webapp/frontend/src/api.js`)
- FastAPI service → Movie catalog: loads MovieLens and Q table (evidence: `webapp/backend/app.py`)
- FastAPI service → Q-learning agents: uses Q policy (evidence: `webapp/backend/app.py`)
- FastAPI service → TMDB poster resolver: creates resolver (evidence: `webapp/backend/app.py`)
- FastAPI service → SQLite user and cache data: reads and writes (evidence: `webapp/backend/app.py`)
- TMDB poster resolver → SQLite user and cache data: caches artwork (evidence: `webapp/backend/tmdb_posters.py`)
- TMDB poster resolver → TMDB: searches titles (evidence: `webapp/backend/tmdb_posters.py`)
- Movie cards → Poster display: renders artwork (evidence: `webapp/frontend/src/components/MovieCard.jsx`)
- Poster display → API client: resolves artwork (evidence: `webapp/frontend/src/components/Poster.jsx`)
- FastAPI service → Movie viewer: returns recommendations and features
