# dracula-5/news-recommender architecture

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

- Interactive diagram: https://gitdiagram.com/dracula-5/news-recommender
- Repository: https://github.com/dracula-5/news-recommender

## Overview

NeuroFeed is an adaptive news-recommendation product: users browse a feed, and each interaction can update their profile and influence subsequent recommendations. The principal path runs from the browser through the FastAPI service to the recommender, which retrieves and scores candidates, blends cold-start and learning signals, diversifies results, and persists interaction state in SQLite. Separate branches cover authentication, live-news ingestion, webcam attention, and evaluation. Connections involving unsampled modules are limited to relationships documented in the README or listed in the source index.

Main entry points: [`final/recommender.py`](https://github.com/dracula-5/news-recommender/blob/main/final/recommender.py) (Recommendation engine), [`final/backend/main.py`](https://github.com/dracula-5/news-recommender/blob/main/final/backend/main.py) (FastAPI service), [`final/database.py`](https://github.com/dracula-5/news-recommender/blob/main/final/database.py) (News and interaction store), [`final/live_news.py`](https://github.com/dracula-5/news-recommender/blob/main/final/live_news.py) (Live-news ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Feed UI<br/>[app.js]"]
end

subgraph group_service["API service"]
  node_api["FastAPI service<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_cache["TTL cache<br/>[cache.py]"]
  node_config["Runtime config<br/>[config.py]"]
end

subgraph group_recommendation["Recommendation"]
  node_recommender["Recommendation engine<br/>[recommender.py]"]
  node_nlp["Ensemble retrieval<br/>[nlp_engine.py]"]
  node_reranking["MMR reranking<br/>[reranking.py]"]
  node_mood["Mood signals<br/>[mood_signals.py]"]
  node_graph["Interest graph<br/>[graph_memory.py]"]
  node_attention["Webcam attention"]
end

subgraph group_state["State and ingestion"]
  node_live_news["Live-news ingestion<br/>[live_news.py]"]
  node_news_db[("News and interaction store<br/>[database.py]")]
  node_auth_db[("Auth token store<br/>[auth.py]")]
end

subgraph group_learning["Learning and evaluation"]
  node_ddqn["Dueling DDQN<br/>[ddqn_agent.py]"]
  node_bandits["Hybrid bandits<br/>[rl_policies.py]"]
  node_evaluation["Offline evaluation<br/>[evaluation.py]"]
end

node_browser(("Browser user"))
node_news_api["NewsAPI"]

node_browser -->|"uses"| node_frontend
node_frontend -->|"REST requests"| node_api
node_api -->|"routes requests"| node_recommender
node_api -->|"authenticates users"| node_auth
node_api -->|"uses cache"| node_cache
node_api -->|"routes live news"| node_live_news
node_api -->|"routes evaluation"| node_evaluation
node_api -->|"reads attention"| node_attention
node_api -->|"loads settings"| node_config
node_recommender -->|"scores candidates"| node_nlp
node_recommender -->|"diversifies results"| node_reranking
node_recommender -->|"uses mood signals"| node_mood
node_recommender -->|"uses interest graph"| node_graph
node_recommender -->|"uses Q-values"| node_ddqn
node_recommender -->|"uses bandit signals"| node_bandits
node_recommender -->|"reads attention"| node_attention
node_recommender -->|"reads and writes"| node_news_db
node_graph -->|"persists graph state"| node_news_db
node_ddqn -->|"blends policy"| node_bandits
node_ddqn -->|"loads agent state"| node_news_db
node_evaluation -->|"evaluates rankings"| node_recommender
node_evaluation -->|"reads catalog"| node_news_db
node_live_news -->|"fetches headlines"| node_news_api
node_live_news -->|"upserts articles"| node_news_db
node_auth -->|"stores credentials"| node_auth_db

click node_frontend "https://github.com/dracula-5/news-recommender/blob/main/final/frontend/app.js"
click node_api "https://github.com/dracula-5/news-recommender/blob/main/final/backend/main.py"
click node_auth "https://github.com/dracula-5/news-recommender/blob/main/final/auth.py"
click node_cache "https://github.com/dracula-5/news-recommender/blob/main/final/cache.py"
click node_config "https://github.com/dracula-5/news-recommender/blob/main/final/config.py"
click node_recommender "https://github.com/dracula-5/news-recommender/blob/main/final/recommender.py"
click node_nlp "https://github.com/dracula-5/news-recommender/blob/main/final/nlp_engine.py"
click node_reranking "https://github.com/dracula-5/news-recommender/blob/main/final/reranking.py"
click node_mood "https://github.com/dracula-5/news-recommender/blob/main/final/mood_signals.py"
click node_graph "https://github.com/dracula-5/news-recommender/blob/main/final/graph_memory.py"
click node_attention "https://github.com/dracula-5/news-recommender/blob/main/final/webcam_attention.py"
click node_ddqn "https://github.com/dracula-5/news-recommender/blob/main/final/ddqn_agent.py"
click node_bandits "https://github.com/dracula-5/news-recommender/blob/main/final/rl_policies.py"
click node_evaluation "https://github.com/dracula-5/news-recommender/blob/main/final/evaluation.py"
click node_live_news "https://github.com/dracula-5/news-recommender/blob/main/final/live_news.py"
click node_news_db "https://github.com/dracula-5/news-recommender/blob/main/final/database.py"
click node_auth_db "https://github.com/dracula-5/news-recommender/blob/main/final/auth.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_frontend,node_browser toneBlue
class node_api,node_auth,node_cache,node_config toneAmber
class node_recommender,node_nlp,node_reranking,node_mood,node_graph,node_attention,node_news_api toneMint
class node_live_news,node_news_db,node_auth_db toneRose
class node_ddqn,node_bandits,node_evaluation toneIndigo
```

## Components

### User experience

- [Feed UI](https://github.com/dracula-5/news-recommender/blob/main/final/frontend/app.js): `final/frontend/app.js`

### API service

- [FastAPI service](https://github.com/dracula-5/news-recommender/blob/main/final/backend/main.py): `final/backend/main.py`
- [Authentication](https://github.com/dracula-5/news-recommender/blob/main/final/auth.py): `final/auth.py`
- [TTL cache](https://github.com/dracula-5/news-recommender/blob/main/final/cache.py): `final/cache.py`
- [Runtime config](https://github.com/dracula-5/news-recommender/blob/main/final/config.py): `final/config.py`

### Recommendation

- [Recommendation engine](https://github.com/dracula-5/news-recommender/blob/main/final/recommender.py): `final/recommender.py`
- [Ensemble retrieval](https://github.com/dracula-5/news-recommender/blob/main/final/nlp_engine.py): `final/nlp_engine.py`
- [MMR reranking](https://github.com/dracula-5/news-recommender/blob/main/final/reranking.py): `final/reranking.py`
- [Mood signals](https://github.com/dracula-5/news-recommender/blob/main/final/mood_signals.py): `final/mood_signals.py`
- [Interest graph](https://github.com/dracula-5/news-recommender/blob/main/final/graph_memory.py): `final/graph_memory.py`
- [Webcam attention](https://github.com/dracula-5/news-recommender/blob/main/final/webcam_attention.py): `final/webcam_attention.py`

### State and ingestion

- [Live-news ingestion](https://github.com/dracula-5/news-recommender/blob/main/final/live_news.py): `final/live_news.py`
- [News and interaction store](https://github.com/dracula-5/news-recommender/blob/main/final/database.py): `final/database.py`
- [Auth token store](https://github.com/dracula-5/news-recommender/blob/main/final/auth.py): `final/auth.py`

### Learning and evaluation

- [Dueling DDQN](https://github.com/dracula-5/news-recommender/blob/main/final/ddqn_agent.py): `final/ddqn_agent.py`
- [Hybrid bandits](https://github.com/dracula-5/news-recommender/blob/main/final/rl_policies.py): `final/rl_policies.py`
- [Offline evaluation](https://github.com/dracula-5/news-recommender/blob/main/final/evaluation.py): `final/evaluation.py`

### Other components

- **Browser user**
- **NewsAPI**

## Connections

- Browser user → Feed UI: uses (evidence: `README.md`)
- Feed UI → FastAPI service: REST requests (evidence: `README.md`)
- FastAPI service → Recommendation engine: routes requests (evidence: `final/backend/main.py`)
- FastAPI service → Authentication: authenticates users (evidence: `final/backend/main.py`)
- FastAPI service → TTL cache: uses cache (evidence: `final/backend/main.py`)
- FastAPI service → Live-news ingestion: routes live news (evidence: `final/backend/main.py`)
- FastAPI service → Offline evaluation: routes evaluation (evidence: `final/backend/main.py`)
- FastAPI service → Webcam attention: reads attention (evidence: `final/backend/main.py`)
- FastAPI service → Runtime config: loads settings (evidence: `final/backend/main.py`)
- Recommendation engine → Ensemble retrieval: scores candidates (evidence: `final/recommender.py`)
- Recommendation engine → MMR reranking: diversifies results (evidence: `final/recommender.py`)
- Recommendation engine → Mood signals: uses mood signals (evidence: `final/recommender.py`)
- Recommendation engine → Interest graph: uses interest graph (evidence: `final/recommender.py`)
- Recommendation engine → Dueling DDQN: uses Q-values (evidence: `final/recommender.py`)
- Recommendation engine → Hybrid bandits: uses bandit signals (evidence: `final/recommender.py`)
- Recommendation engine → Webcam attention: reads attention (evidence: `final/recommender.py`)
- Recommendation engine → News and interaction store: reads and writes (evidence: `final/recommender.py`)
- Interest graph → News and interaction store: persists graph state (evidence: `final/graph_memory.py`)
- Dueling DDQN → Hybrid bandits: blends policy (evidence: `final/ddqn_agent.py`)
- Dueling DDQN → News and interaction store: loads agent state (evidence: `final/ddqn_agent.py`)
- Offline evaluation → Recommendation engine: evaluates rankings (evidence: `final/evaluation.py`)
- Offline evaluation → News and interaction store: reads catalog (evidence: `final/evaluation.py`)
- Live-news ingestion → NewsAPI: fetches headlines (evidence: `final/live_news.py`)
- Live-news ingestion → News and interaction store: upserts articles (evidence: `final/live_news.py`)
- Authentication → Auth token store: stores credentials (evidence: `final/auth.py`)
