# lawliet119/kg-movie-recommender architecture

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

- Interactive diagram: https://gitdiagram.com/lawliet119/kg-movie-recommender
- Repository: https://github.com/lawliet119/kg-movie-recommender

## Overview

KGenSam is a knowledge-graph conversational movie recommender, with a browser chat/visualization frontend and a FastAPI recommendation backend. The main workflow is user chat → backend session and recommendation handling → preference-aware ranking → movie recommendations and feedback. The repository also includes interaction-data/model training and offline evaluation capabilities. The graph reflects explicit imports and documented frontend/backend responsibilities; some internal endpoint wiring is not shown in the excerpts, so uncertain links are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/main.py) (FastAPI endpoints), [`backend/app/recommender.py`](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/recommender.py) (Recommendation engine), [`src/ui/chat.js`](https://github.com/lawliet119/kg-movie-recommender/blob/main/src/ui/chat.js) (Chat interface), [`backend/app/interaction_data.py`](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/interaction_data.py) (Interaction profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Browser experience"]
  node_chat["Chat interface<br/>[chat.js]"]
  node_browser["App entry<br/>[main.js]"]
  node_graphviz["Graph visualization<br/>[graphViz.js]"]
  node_localdata[("Browser movie graph<br/>[movieKG.js]")]
  node_localengine["Browser recommender<br/>[recommender.js]"]
end

subgraph group_backend["API and conversation"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_sessions["Conversation sessions"]
end

subgraph group_knowledge["Knowledge and models"]
  node_nlu["Semantic NLU<br/>[semantic_nlu.py]"]
  node_kg[("Movie knowledge graph<br/>[kg_builder.py]")]
  node_kgsource["MovieLens and TMDB KG<br/>[tmdb_kg.py]"]
  node_embeddings["KG embeddings<br/>[kg_embeddings.py]"]
  node_interactions[("Interaction profiles")]
end

subgraph group_recommend["Recommendation"]
  node_engine["Recommendation engine<br/>[recommender.py]"]
  node_active["Active question sampler<br/>[active_sampler.py]"]
  node_policy["Ask-recommend policy<br/>[interact_policy.py]"]
  node_propagation["Preference propagation"]
  node_fm["Factorization model<br/>[fm_model.py]"]
  node_fusion["Fusion ranker<br/>[fusion_ranker.py]"]
  node_negative["Negative sampler"]
end

subgraph group_research["Training and evaluation"]
  node_training["Policy training<br/>[policy_training.py]"]
  node_evaluation["Offline evaluation<br/>[evaluation.py]"]
  node_simulator["User simulator<br/>[user_simulator.py]"]
  node_checkpoint["Runtime checkpoints"]
end

node_user(("Movie seeker"))
node_externalrag{{"Gemini Graph-RAG"}}

node_user -->|"sends chat"| node_chat
node_browser -->|"initializes"| node_chat
node_browser -->|"builds graph"| node_localdata
node_browser -->|"creates engine"| node_localengine
node_chat -->|"updates graph"| node_graphviz
node_chat -->|"local fallback"| node_localengine
node_chat -->|"requests backend"| node_api
node_api -.->|"manages sessions"| node_sessions
node_api -->|"serves recommendations"| node_engine
node_api -->|"loads graph"| node_kg
node_api -->|"loads embeddings"| node_embeddings
node_api -->|"loads language model"| node_nlu
node_api -->|"loads interactions"| node_interactions
node_kgsource -.->|"builds graph data"| node_kg
node_engine -->|"traverses graph"| node_kg
node_engine -->|"scores embeddings"| node_embeddings
node_engine -->|"selects questions"| node_active
node_engine -->|"chooses action"| node_policy
node_engine -->|"propagates preferences"| node_propagation
node_engine -->|"scores candidates"| node_fm
node_engine -->|"ranks features"| node_fusion
node_negative -->|"uses profiles"| node_interactions
node_fm -->|"trains from feedback"| node_interactions
node_training -->|"trains policy"| node_policy
node_training -->|"uses profiles"| node_interactions
node_evaluation -->|"evaluates ranking"| node_engine
node_evaluation -->|"simulates users"| node_simulator
node_api -->|"runs evaluation"| node_evaluation
node_api -->|"loads checkpoint"| node_checkpoint
node_chat -.->|"requests grounded answer"| node_externalrag

click node_chat "https://github.com/lawliet119/kg-movie-recommender/blob/main/src/ui/chat.js"
click node_browser "https://github.com/lawliet119/kg-movie-recommender/blob/main/src/main.js"
click node_graphviz "https://github.com/lawliet119/kg-movie-recommender/blob/main/src/ui/graphViz.js"
click node_localdata "https://github.com/lawliet119/kg-movie-recommender/blob/main/src/data/movieKG.js"
click node_localengine "https://github.com/lawliet119/kg-movie-recommender/blob/main/src/engine/recommender.js"
click node_api "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/main.py"
click node_sessions "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/conversation_manager.py"
click node_nlu "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/semantic_nlu.py"
click node_kg "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/kg_builder.py"
click node_kgsource "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/tmdb_kg.py"
click node_embeddings "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/kg_embeddings.py"
click node_interactions "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/interaction_data.py"
click node_engine "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/recommender.py"
click node_active "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/active_sampler.py"
click node_policy "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/interact_policy.py"
click node_propagation "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/preference_propagator.py"
click node_fm "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/fm_model.py"
click node_fusion "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/fusion_ranker.py"
click node_negative "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/negative_sampler.py"
click node_training "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/policy_training.py"
click node_evaluation "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/evaluation.py"
click node_simulator "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/user_simulator.py"
click node_checkpoint "https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/model_checkpoint.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_chat,node_browser,node_graphviz,node_localdata,node_localengine toneBlue
class node_api,node_sessions toneAmber
class node_nlu,node_kg,node_kgsource,node_embeddings,node_interactions toneMint
class node_engine,node_active,node_policy,node_propagation,node_fm,node_fusion,node_negative toneRose
class node_training,node_evaluation,node_simulator,node_checkpoint,node_user,node_externalrag toneIndigo
```

## Components

### Browser experience

- [Chat interface](https://github.com/lawliet119/kg-movie-recommender/blob/main/src/ui/chat.js): `src/ui/chat.js`
- [App entry](https://github.com/lawliet119/kg-movie-recommender/blob/main/src/main.js): `src/main.js`
- [Graph visualization](https://github.com/lawliet119/kg-movie-recommender/blob/main/src/ui/graphViz.js): `src/ui/graphViz.js`
- [Browser movie graph](https://github.com/lawliet119/kg-movie-recommender/blob/main/src/data/movieKG.js): `src/data/movieKG.js`
- [Browser recommender](https://github.com/lawliet119/kg-movie-recommender/blob/main/src/engine/recommender.js): `src/engine/recommender.js`

### API and conversation

- [FastAPI endpoints](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/main.py): `backend/app/main.py`
- [Conversation sessions](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/conversation_manager.py): `backend/app/conversation_manager.py`

### Knowledge and models

- [Semantic NLU](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/semantic_nlu.py): `backend/app/semantic_nlu.py`
- [Movie knowledge graph](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/kg_builder.py): `backend/app/kg_builder.py`
- [MovieLens and TMDB KG](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/tmdb_kg.py): `backend/app/tmdb_kg.py`
- [KG embeddings](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/kg_embeddings.py): `backend/app/kg_embeddings.py`
- [Interaction profiles](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/interaction_data.py): `backend/app/interaction_data.py`

### Recommendation

- [Recommendation engine](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/recommender.py): `backend/app/recommender.py`
- [Active question sampler](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/active_sampler.py): `backend/app/active_sampler.py`
- [Ask-recommend policy](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/interact_policy.py): `backend/app/interact_policy.py`
- [Preference propagation](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/preference_propagator.py): `backend/app/preference_propagator.py`
- [Factorization model](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/fm_model.py): `backend/app/fm_model.py`
- [Fusion ranker](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/fusion_ranker.py): `backend/app/fusion_ranker.py`
- [Negative sampler](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/negative_sampler.py): `backend/app/negative_sampler.py`

### Training and evaluation

- [Policy training](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/policy_training.py): `backend/app/policy_training.py`
- [Offline evaluation](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/evaluation.py): `backend/app/evaluation.py`
- [User simulator](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/user_simulator.py): `backend/app/user_simulator.py`
- [Runtime checkpoints](https://github.com/lawliet119/kg-movie-recommender/blob/main/backend/app/model_checkpoint.py): `backend/app/model_checkpoint.py`

### Other components

- **Movie seeker**
- **Gemini Graph-RAG**

## Connections

- Movie seeker → Chat interface: sends chat (evidence: `src/ui/chat.js`)
- App entry → Chat interface: initializes (evidence: `src/main.js`)
- App entry → Browser movie graph: builds graph (evidence: `src/main.js`)
- App entry → Browser recommender: creates engine (evidence: `src/main.js`)
- Chat interface → Graph visualization: updates graph (evidence: `src/ui/chat.js`)
- Chat interface → Browser recommender: local fallback (evidence: `src/ui/chat.js`)
- Chat interface → FastAPI endpoints: requests backend
- FastAPI endpoints → Conversation sessions: manages sessions (evidence: `backend/app/main.py`)
- FastAPI endpoints → Recommendation engine: serves recommendations (evidence: `backend/app/main.py`)
- FastAPI endpoints → Movie knowledge graph: loads graph (evidence: `backend/app/main.py`)
- FastAPI endpoints → KG embeddings: loads embeddings (evidence: `backend/app/main.py`)
- FastAPI endpoints → Semantic NLU: loads language model (evidence: `backend/app/main.py`)
- FastAPI endpoints → Interaction profiles: loads interactions (evidence: `backend/app/main.py`)
- MovieLens and TMDB KG → Movie knowledge graph: builds graph data
- Recommendation engine → Movie knowledge graph: traverses graph (evidence: `backend/app/recommender.py`)
- Recommendation engine → KG embeddings: scores embeddings (evidence: `backend/app/recommender.py`)
- Recommendation engine → Active question sampler: selects questions (evidence: `backend/app/recommender.py`)
- Recommendation engine → Ask-recommend policy: chooses action (evidence: `backend/app/recommender.py`)
- Recommendation engine → Preference propagation: propagates preferences (evidence: `backend/app/recommender.py`)
- Recommendation engine → Factorization model: scores candidates (evidence: `backend/app/recommender.py`)
- Recommendation engine → Fusion ranker: ranks features (evidence: `backend/app/recommender.py`)
- Negative sampler → Interaction profiles: uses profiles (evidence: `backend/app/negative_sampler.py`)
- Factorization model → Interaction profiles: trains from feedback (evidence: `backend/app/fm_model.py`)
- Policy training → Ask-recommend policy: trains policy (evidence: `backend/app/policy_training.py`)
- Policy training → Interaction profiles: uses profiles (evidence: `backend/app/policy_training.py`)
- Offline evaluation → Recommendation engine: evaluates ranking (evidence: `backend/app/evaluation.py`)
- Offline evaluation → User simulator: simulates users (evidence: `backend/app/evaluation.py`)
- FastAPI endpoints → Offline evaluation: runs evaluation (evidence: `backend/app/main.py`)
- FastAPI endpoints → Runtime checkpoints: loads checkpoint (evidence: `backend/app/main.py`)
- Chat interface → Gemini Graph-RAG: requests grounded answer (evidence: `src/ui/chat.js`)
