# thanhtungvudata/cinemood_chatbot architecture

> Architecture diagram of the GitHub repository thanhtungvudata/cinemood_chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thanhtungvudata/cinemood_chatbot
- Repository: https://github.com/thanhtungvudata/cinemood_chatbot

## Overview

##### Project type and purpose
- CineMood_Chatbot is a full-stack, RAG-enabled semantic-search chatbot built with Streamlit. It ingests trending movie data from TMDB, generates vector embeddings (using OpenAI or similar), stores them in ChromaDB for fast retrieval, and serves recommendations in a conversational UI. A GitHub Actions workflow automates the data/embedding update pipeline.

##### File structure
- Top-level scripts:
- fetch_movies.py – pulls trending movie JSON from TMDB API → trending_movies.json
- generate_embeddings.py – reads trending_movies.json → movie_embeddings.json via embedding API
- store_in_chromadb.py – loads movie_embeddings.json → persists vectors in the local chroma_db/ folder
- app.py – Streamlit app implementing the chatbot UI + retrieval + LLM calls
- Configuration: config.py holds API keys and other settings.
- Persistence:
- trending_movies.json & movie_embeddings.json – intermediate files
- chroma_db/ – flat-file ChromaDB instance (SQLite + binary vector shards)
- Automation: .github/workflows/update_db.yml triggers the three scripts on a schedule.

##### README for insights
- The README describes a classical ETL → vector-store → RAG serv­ing flow, hosted on Hugging Face Spaces, using TMDB/API calls, OpenAI for embeddings & responses, and Streamlit UI.

##### Main components & interactions (how to reflect them
a. Data Ingestion Pipeline (ETL)
- TMDB API → fetch_movies.py → trending_movies.json → generate_embeddings.py → movie_embeddings.json → store_in_chromadb.py → local ChromaDB
b. Vector Database
- ChromaDB instance (chroma_db/ folder) stores vectors & metadata in SQLite + binary files
c. Chatbot Service (Streamlit App)
- app.py acts as both frontend (UI) and backend logic:
- Takes user input (mood/preference)
- Queries ChromaDB for nearest-neighbor embeddings
- Optionally calls OpenAI (or another LLM) for RAG-style response generation
- Renders results in the browser
d. External Services
- TMDB API (movie data)
- OpenAI API (embeddings + LLM for RAG)
- Hugging Face Spaces (deployment target)
e. CI/CD Automation
- GitHub Actions (.github/workflows/update_db.yml) orchestrates the ETL on a schedule, pushing updated JSONs & vectors.

##### Architectural patterns & design principles
- Separation of Concerns: distinct ETL scripts, vector database, UI layer
- RAG pattern: retrieval from vector store → augmentation of LLM prompt
- Modular pipeline: independent scripts for each step, orchestrated by CI
- Local-first persistence (ChromaDB) for fast, offline semantic search

##### Working flow visualization
1. GitHub Actions (scheduler)
2. fetch_movies.py → trending_movies.json
3. generate_embeddings.py → movie_embeddings.json
4. store_in_chromadb.py → chroma_db/
5. User opens Streamlit (app.py)
6. User input → ChromaDB query → LLM call → UI response

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Control Plane
    subgraph "Control Plane"
        GH["GitHub Actions\n(.github/workflows/update_db.yml)"]:::external
    end

    %% Data Plane - ETL Scripts and Data Stores
    subgraph "Data Ingestion Pipeline"
        TMDB["TMDB API"]:::external
        FM["fetch_movies.py"]:::etl
        TMJSON(("trending_movies.json")):::store
        GE["generate_embeddings.py"]:::etl
        MEJSON(("movie_embeddings.json")):::store
        SC["store_in_chromadb.py"]:::etl
        CHROMA(("ChromaDB Instance\n(chroma_db/)")):::db
    end

    %% User Plane - Chatbot Service
    subgraph "User Plane"
        User["End User Browser"]:::external
        App["app.py"]:::ui
        OPENAI["OpenAI API"]:::external
        HF["Hugging Face Spaces"]:::external
    end

    %% Connections - Control Plane to Data Plane
    GH -->|"scheduled trigger"| FM
    GH -->|"scheduled trigger"| GE
    GH -->|"scheduled trigger"| SC

    %% ETL Flow
    TMDB -->|"fetch trending movies"| FM
    FM -->|"writes"| TMJSON
    TMJSON -->|"reads"| GE
    GE -->|"writes"| MEJSON
    MEJSON -->|"reads"| SC
    SC -->|"persists vectors"| CHROMA

    %% User Interaction Flow
    User -->|"access UI"| App
    App -->|"semantic search query"| CHROMA
    CHROMA -->|"returns embeddings"| App
    App -->|"RAG prompt"| OPENAI
    OPENAI -->|"LLM response"| App
    App -->|"render recommendations"| User
    App -->|"deployed on"| HF

    %% Click Events
    click FM "https://github.com/thanhtungvudata/cinemood_chatbot/blob/main/fetch_movies.py"
    click GE "https://github.com/thanhtungvudata/cinemood_chatbot/blob/main/generate_embeddings.py"
    click SC "https://github.com/thanhtungvudata/cinemood_chatbot/blob/main/store_in_chromadb.py"
    click TMJSON "https://github.com/thanhtungvudata/cinemood_chatbot/blob/main/trending_movies.json"
    click MEJSON "https://github.com/thanhtungvudata/cinemood_chatbot/blob/main/movie_embeddings.json"
    click CHROMA "https://github.com/thanhtungvudata/cinemood_chatbot/tree/main/chroma_db/"
    click GH "https://github.com/thanhtungvudata/cinemood_chatbot/blob/main/.github/workflows/update_db.yml"
    click App "https://github.com/thanhtungvudata/cinemood_chatbot/blob/main/app.py"

    %% Styling
    classDef etl fill:#FFA500,stroke:#333,stroke-width:1px
    classDef store fill:#ADFF2F,stroke:#333,stroke-width:1px
    classDef db fill:#32CD32,stroke:#333,stroke-width:1px
    classDef ui fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
