# gw-dg/to-all-the-films architecture

> Architecture diagram of the GitHub repository gw-dg/to-all-the-films, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gw-dg/to-all-the-films
- Repository: https://github.com/gw-dg/to-all-the-films

## Overview

##### Project type and purpose
- This is a full-stack web application (“To All The Films I Love”) providing AI-powered, personalized movie recommendations and an AI chatbot interface.
- The frontend is a React single-page app built with Vite, Tailwind CSS, and deployed to Vercel.
- The backend is a Node.js/Express API server handling user management, movie data retrieval, rating storage, and AI/ML integrations.

##### File structure
- Top-level folders:
- /frontend – React/Vite/Tailwind code, UI components, routing and static assets.
- /backend – Express.js server, route handlers, data models, config for database and Firebase Admin.
- backend/config contains db.js (database connection, likely MongoDB) and firebaseAdmin.js (Firebase Authentication/Authorization).
- backend/models defines User and Review schemas.
- backend/routes organizes all REST endpoints: authentication (loginRoutes), profile, search, titleDetail, recommendations, AI-powered genre or trending routes, GenAI chatbot (genAIRoutes).
- notebook.ipynb suggests local experimentation or prototyping of ML embeddings.

##### Extract README insights
- Uses TMDb API for movie metadata.
- Embeddings generated via baai/bge-m3 model and stored in Pinecone (vector database) for similarity search.
- AI chatbot powered by GroqCloud Llama 3.3-70B model.
- Future plan to add caching, social mashups, UI refactor.

##### Main components
a. Frontend SPA (React/Vite/Tailwind)
b. Backend API (Node.js + Express)
c. Primary database (e.g., MongoDB or relational DB) for user profiles, reviews, ratings
d. Firebase Authentication service for user login and token verification
e. Pinecone vector database for embedding storage and similarity queries
f. External APIs:
- TMDb API for film metadata
- GroqCloud API (Llama 3.3-70B) for GenAI chatbot
g. ML pipeline (offline/service) generating embeddings via baai/bge-m3, storing to Pinecone
h. Deployment platforms: Vercel (frontend + backend)

##### Relationships and data flows
- User’s browser ↔︎ Frontend React SPA
- SPA sends HTTP(S) to Backend Express API
- Backend authenticates via Firebase Admin
- Backend reads/writes to primary DB for user data and reviews
- For recommendations:
- Backend retrieves user’s rated titles from DB
- Generates or fetches embeddings (via Pinecone)
- Queries Pinecone for nearest neighbors
- Optionally calls TMDb API for metadata enrichment
- For GenAI chatbot: Backend routes user messages to GroqCloud API, returns responses to frontend

##### Architectural patterns and design principles
- Layered architecture: Presentation (UI) → API Layer → Data Services → External Services.
- Separation of concerns:
- UI components vs. business logic vs. data access
- Authentication as a separate cross-cutting concern (Firebase Admin)
- Micro-service-esque modules within the API (each route file = one domain service)
- Eventual consistency in recommendations powered by vector DB

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client"
        direction TB
        Browser["User Browser"]:::client
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        ReactSPA["React SPA<br/>(Vite/Tailwind)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend API Layer"
        direction TB
        API["Express API Server"]:::backend
        subgraph "Auth Services"
            direction TB
            FirebaseAuth["Firebase Auth"]:::external
        end
        subgraph "Route Handlers"
            direction TB
            LoginRoutes["Login Routes"]:::backend
            ProfileRoutes["Profile Routes"]:::backend
            SearchRoutes["Search Routes"]:::backend
            TitleDetailRoutes["TitleDetail Routes"]:::backend
            GetReccRoutes["Recommendations Routes"]:::backend
            GenreRoutes["Genre Routes"]:::backend
            TrendingRoutes["Trending Routes"]:::backend
            GenAIRoutes["GenAI Chatbot Routes"]:::backend
        end
        subgraph "Data Models"
            direction TB
            UserModel["User Model"]:::backend
            ReviewModel["Review Model"]:::backend
        end
        subgraph "Config"
            direction TB
            DBConfig["DB Config"]:::backend
            FirebaseConfig["Firebase Admin"]:::backend
        end
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        MongoDB[("MongoDB")]:::datastore
        Pinecone[("Pinecone Vector DB")]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        TMDbAPI["TMDb API"]:::external
        GroqCloudAPI["GroqCloud API"]:::external
    end

    %% ML Pipeline
    subgraph "ML Pipeline (Offline)"
        direction TB
        Notebook["notebook.ipynb"]:::ml
    end

    %% Connections
    Browser -->|HTTPS| ReactSPA
    ReactSPA -->|REST calls| API

    API -->|Validate Token| FirebaseAuth
    FirebaseAuth -->|Token Validated| API

    API -->|CRUD operations| MongoDB
    API -->|Query embeddings| Pinecone
    API -->|Store embeddings| Pinecone

    API -->|GET /titles, POST /search| TMDbAPI
    API -->|Chat request| GroqCloudAPI

    Notebook -->|Generate embeddings| Pinecone

    %% Internal flow among API components
    API --> LoginRoutes
    API --> ProfileRoutes
    API --> SearchRoutes
    API --> TitleDetailRoutes
    API --> GetReccRoutes
    API --> GenreRoutes
    API --> TrendingRoutes
    API --> GenAIRoutes

    LoginRoutes --> DBConfig
    ProfileRoutes --> DBConfig
    SearchRoutes --> DBConfig
    TitleDetailRoutes --> DBConfig
    GetReccRoutes --> DBConfig
    GenreRoutes --> DBConfig
    TrendingRoutes --> DBConfig
    GenAIRoutes --> DBConfig

    LoginRoutes -->|Use| FirebaseConfig
    ProfileRoutes -->|Use| FirebaseConfig

    SearchRoutes --> UserModel
    TitleDetailRoutes --> UserModel
    GetReccRoutes --> ReviewModel
    GenreRoutes --> ReviewModel
    TrendingRoutes --> ReviewModel
    GenAIRoutes --> ReviewModel

    %% Click Events
    click ReactSPA "https://github.com/gw-dg/to-all-the-films/tree/main/frontend/"
    click API "https://github.com/gw-dg/to-all-the-films/blob/main/backend/index.js"
    click DBConfig "https://github.com/gw-dg/to-all-the-films/blob/main/backend/config/db.js"
    click FirebaseConfig "https://github.com/gw-dg/to-all-the-films/blob/main/backend/config/firebaseAdmin.js"
    click UserModel "https://github.com/gw-dg/to-all-the-films/blob/main/backend/models/user.js"
    click ReviewModel "https://github.com/gw-dg/to-all-the-films/blob/main/backend/models/review.js"
    click SearchRoutes "https://github.com/gw-dg/to-all-the-films/blob/main/backend/routes/searchRoutes.js"
    click TitleDetailRoutes "https://github.com/gw-dg/to-all-the-films/blob/main/backend/routes/titleDetailRoutes.js"
    click GetReccRoutes "https://github.com/gw-dg/to-all-the-films/blob/main/backend/routes/getReccRoutes.js"
    click GenreRoutes "https://github.com/gw-dg/to-all-the-films/blob/main/backend/routes/genreRoutes.js"
    click TrendingRoutes "https://github.com/gw-dg/to-all-the-films/blob/main/backend/routes/trendingRoutes.js"
    click GenAIRoutes "https://github.com/gw-dg/to-all-the-films/blob/main/backend/routes/genAIRoutes.js"
    click LoginRoutes "https://github.com/gw-dg/to-all-the-films/blob/main/backend/routes/loginRoutes.js"
    click ProfileRoutes "https://github.com/gw-dg/to-all-the-films/blob/main/backend/routes/profileRoutes.js"
    click Notebook "https://github.com/gw-dg/to-all-the-films/blob/main/notebook.ipynb"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px
    classDef frontend fill:#8f8,stroke:#333,stroke-width:2px
    classDef backend fill:#88f,stroke:#333,stroke-width:2px
    classDef datastore fill:#f96,stroke:#333,stroke-width:2px
    classDef external fill:#ccc,stroke-dasharray: 5 5,stroke:#333,stroke-width:2px
    classDef ml fill:#ff8,stroke:#333,stroke-width:2px
```
