# candyhuang940730/cinerecommend architecture

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

- Interactive diagram: https://gitdiagram.com/candyhuang940730/cinerecommend
- Repository: https://github.com/candyhuang940730/cinerecommend

## Overview

CineRecommend is a Streamlit movie recommender. A user selects or creates a profile, rates movies, then requests genre-filtered recommendations with a slider balancing multimodal content similarity against trust-weighted social ratings. The repository also includes MovieLens loading, TMDB metadata retrieval, feature embedding, trust-score computation, spam injection for experiments, and recommendation evaluation. The graph distinguishes these domain stages and the database access layer. Edges follow excerpts, SOURCE INDEX references, or README statements; unsampled schema details and unshown runtime wiring are not inferred.

Main entry points: [`core/db.py`](https://github.com/candyhuang940730/cinerecommend/blob/main/core/db.py) (Database connection), [`app.py`](https://github.com/candyhuang940730/cinerecommend/blob/main/app.py) (Streamlit interface), [`core/recommend.py`](https://github.com/candyhuang940730/cinerecommend/blob/main/core/recommend.py) (Hybrid recommender), [`etl/fetch_tmdb.py`](https://github.com/candyhuang940730/cinerecommend/blob/main/etl/fetch_tmdb.py) (TMDB metadata fetch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User experience"]
  node_app["Streamlit interface<br/>[app.py]"]
  node_profile["User profiles and ratings<br/>[profile.py]"]
end

subgraph group_recommendation["Recommendation"]
  node_recommender["Hybrid recommender<br/>[recommend.py]"]
  node_content["Text and poster embeddings<br/>[embed.py]"]
  node_trust["User trust scores<br/>[trust.py]"]
end

subgraph group_data["Data and trust"]
  node_movielens["MovieLens data"]
  node_loader["MovieLens import<br/>[load_movielens.py]"]
  node_metadata["TMDB metadata fetch<br/>[fetch_tmdb.py]"]
  node_db_access["Database connection<br/>[db.py]"]
  node_database[("PostgreSQL and pgvector<br/>[schema.sql]")]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Ranking evaluation<br/>[evaluate.py]"]
  node_spam["Spam experiment data<br/>[inject_spam.py]"]
end

node_user(("Moviegoer"))
node_tmdb{{"TMDB metadata API"}}

node_user -->|"uses"| node_app
node_app -->|"reads and rates"| node_profile
node_app -->|"requests recommendations"| node_recommender
node_app -->|"reads year range"| node_db_access
node_profile -->|"reads and writes"| node_db_access
node_recommender -->|"queries ratings and movies"| node_db_access
node_evaluation -->|"evaluates rankings"| node_recommender
node_evaluation -->|"reads ratings"| node_db_access
node_trust -->|"reads and stores scores"| node_db_access
node_loader -->|"loads records"| node_db_access
node_movielens -->|"supplies dataset"| node_loader
node_metadata -->|"fetches metadata"| node_tmdb
node_metadata -->|"updates movie metadata"| node_db_access
node_content -->|"stores vectors"| node_db_access
node_spam -->|"inserts synthetic ratings"| node_db_access
node_db_access -->|"connects to"| node_database

click node_app "https://github.com/candyhuang940730/cinerecommend/blob/main/app.py"
click node_profile "https://github.com/candyhuang940730/cinerecommend/blob/main/core/profile.py"
click node_recommender "https://github.com/candyhuang940730/cinerecommend/blob/main/core/recommend.py"
click node_content "https://github.com/candyhuang940730/cinerecommend/blob/main/features/embed.py"
click node_trust "https://github.com/candyhuang940730/cinerecommend/blob/main/core/trust.py"
click node_evaluation "https://github.com/candyhuang940730/cinerecommend/blob/main/core/evaluate.py"
click node_spam "https://github.com/candyhuang940730/cinerecommend/blob/main/etl/inject_spam.py"
click node_loader "https://github.com/candyhuang940730/cinerecommend/blob/main/etl/load_movielens.py"
click node_metadata "https://github.com/candyhuang940730/cinerecommend/blob/main/etl/fetch_tmdb.py"
click node_db_access "https://github.com/candyhuang940730/cinerecommend/blob/main/core/db.py"
click node_database "https://github.com/candyhuang940730/cinerecommend/blob/main/schema.sql"

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_profile toneBlue
class node_recommender,node_content,node_trust toneAmber
class node_movielens,node_loader,node_metadata,node_db_access,node_database,node_tmdb toneMint
class node_evaluation,node_spam toneRose
class node_user toneIndigo
```

## Components

### User experience

- [Streamlit interface](https://github.com/candyhuang940730/cinerecommend/blob/main/app.py): `app.py`
- [User profiles and ratings](https://github.com/candyhuang940730/cinerecommend/blob/main/core/profile.py): `core/profile.py`

### Recommendation

- [Hybrid recommender](https://github.com/candyhuang940730/cinerecommend/blob/main/core/recommend.py): `core/recommend.py`
- [Text and poster embeddings](https://github.com/candyhuang940730/cinerecommend/blob/main/features/embed.py): `features/embed.py`
- [User trust scores](https://github.com/candyhuang940730/cinerecommend/blob/main/core/trust.py): `core/trust.py`

### Data and trust

- **MovieLens data**
- [MovieLens import](https://github.com/candyhuang940730/cinerecommend/blob/main/etl/load_movielens.py): `etl/load_movielens.py`
- [TMDB metadata fetch](https://github.com/candyhuang940730/cinerecommend/blob/main/etl/fetch_tmdb.py): `etl/fetch_tmdb.py`
- [Database connection](https://github.com/candyhuang940730/cinerecommend/blob/main/core/db.py): `core/db.py`
- [PostgreSQL and pgvector](https://github.com/candyhuang940730/cinerecommend/blob/main/schema.sql): `schema.sql`

### Evaluation

- [Ranking evaluation](https://github.com/candyhuang940730/cinerecommend/blob/main/core/evaluate.py): `core/evaluate.py`
- [Spam experiment data](https://github.com/candyhuang940730/cinerecommend/blob/main/etl/inject_spam.py): `etl/inject_spam.py`

### Other components

- **Moviegoer**
- **TMDB metadata API**

## Connections

- Moviegoer → Streamlit interface: uses (evidence: `README.md`)
- Streamlit interface → User profiles and ratings: reads and rates (evidence: `app.py`)
- Streamlit interface → Hybrid recommender: requests recommendations (evidence: `app.py`)
- Streamlit interface → Database connection: reads year range (evidence: `app.py`)
- User profiles and ratings → Database connection: reads and writes (evidence: `core/profile.py`)
- Hybrid recommender → Database connection: queries ratings and movies (evidence: `core/recommend.py`)
- Ranking evaluation → Hybrid recommender: evaluates rankings (evidence: `core/evaluate.py`)
- Ranking evaluation → Database connection: reads ratings (evidence: `core/evaluate.py`)
- User trust scores → Database connection: reads and stores scores (evidence: `core/trust.py`)
- MovieLens import → Database connection: loads records (evidence: `etl/load_movielens.py`)
- MovieLens data → MovieLens import: supplies dataset (evidence: `README.md`)
- TMDB metadata fetch → TMDB metadata API: fetches metadata (evidence: `etl/fetch_tmdb.py`)
- TMDB metadata fetch → Database connection: updates movie metadata (evidence: `etl/fetch_tmdb.py`)
- Text and poster embeddings → Database connection: stores vectors (evidence: `features/embed.py`)
- Spam experiment data → Database connection: inserts synthetic ratings (evidence: `etl/inject_spam.py`)
- Database connection → PostgreSQL and pgvector: connects to (evidence: `README.md`)
