# karanvirheer/statflix architecture

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

- Interactive diagram: https://gitdiagram.com/karanvirheer/statflix
- Repository: https://github.com/karanvirheer/statflix

## Overview

##### Project type and purpose
- This is a full-stack web application named “StatFlix.”
- Purpose: Allow users to upload their Netflix viewing history, normalize and enrich the data via TMDb, persist it in PostgreSQL, and display interactive analytics in the browser.

##### File structure
- Top-level:
- docker-compose.yml – orchestrates frontend, backend, and database containers.
- frontend/ – React app with TailwindCSS; Dockerfile, public and src folders.
- backend/ – Node.js/Express API; Dockerfile, src (api, db, utils), data (csv files & tests).
- Patterns: clear separation of concerns (frontend vs. backend vs. DB).
- Tests: sample CSV files under backend/data/tests to validate parsing/normalization logic.

##### Extract insights from the README
- Components: React UI, Express API, PostgreSQL, TMDb external service.
- Deploy: Docker, docker-compose, hosting on Vercel/Render.
- Data flow: Upload CSV → backend normalizes/enriches → store in Postgres → analytics served to frontend.

##### Main components
a. Frontend (React + Tailwind)
b. Backend (Node.js/Express)
c. PostgreSQL database
d. TMDb external API
f. Users (browser client)

##### Relationships & interactions
- User’s browser ↔ Frontend: HTTP(S) requests, UI flows.
- Frontend ↔ Backend: REST API calls (file upload, fetch analytics endpoints).
- Backend ↔ PostgreSQL: SQL queries to read/write normalized/enriched data.
- Backend ↔ TMDb API: HTTP calls to fetch metadata (genres, runtime).
- Docker-Compose: shows co-located containers and their exposed ports.

##### Architectural patterns & design principles
- Separation of concerns: UI, business logic, data persistence.
- Layered design:
- API layer (Express routes)
- Service/util layer (helpers, TMDb client, normalization)
- Data access layer (db.js)
- Stateless backend: user session data persisted in Postgres.
- Containerization: each component runs in an isolated Docker container for consistency.

##### Key technologies/frameworks
- React.js, TailwindCSS (frontend)
- Node.js, Express.js (backend)
- PostgreSQL (database)
- TMDb API (external enrichment)
- Docker & docker-compose (container orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Compose Orchestrator
    subgraph "Docker-Compose Orchestrator"
        direction TB
        DC["docker-compose.yml"]:::orchestrator
        %% Frontend Container
        subgraph "Frontend Container (3000)" 
            direction TB
            FEdocker["Dockerfile"]:::frontend
            FEApp["App.js"]:::frontend
            FEIndex["index.js"]:::frontend
            FEHome["HomePage.js"]:::frontend
            FECarousel["CarouselPage.js"]:::frontend
            FEComp["components/"]:::frontend
        end
        %% Backend Container
        subgraph "Backend Container (8000)"
            direction TB
            BEdocker["Dockerfile"]:::backend
            BEServer["server.js"]:::backend
            %% Layers
            subgraph "API Layer"
                direction TB
                BETMDB["tmdb.js"]:::backend
            end
            subgraph "Business Logic"
                direction TB
                BEHelper["helpers.js"]:::backend
                BEKaggle["kaggle.js"]:::backend
                BELog["logging.js"]:::backend
            end
            subgraph "Data Layer"
                direction TB
                BEdb["db.js"]:::backend
            end
            subgraph "CSV Data & Tests"
                direction TB
                CSV1["ViewingActivity.csv"]:::backend
                CSV2["big.csv"]:::backend
                KaggleData["kaggle/"]:::backend
                Tests["tests/"]:::backend
            end
        end
        %% Database Container
        subgraph "PostgreSQL (5432)"
            direction TB
            DB["PostgreSQL"]:::database
        end
    end

    %% External Entities
    User["User (Browser)"]:::external
    TMDb["TMDb API"]:::external

    %% Interactions
    User -->|"HTTP GET/POST"| FEApp
    FEApp -->|"HTTP POST /upload\nHTTP GET /analytics"| BEServer
    BEServer -->|"SQL INSERT/SELECT"| BEdb
    BEServer -->|"HTTP GET metadata"| BETMDB
    BETMDB -->|"HTTPS"| TMDb

    %% Click Events
    click DC "https://github.com/karanvirheer/statflix/blob/main/docker-compose.yml"
    click FEdocker "https://github.com/karanvirheer/statflix/tree/main/frontend/Dockerfile"
    click FEApp "https://github.com/karanvirheer/statflix/blob/main/frontend/src/App.js"
    click FEIndex "https://github.com/karanvirheer/statflix/blob/main/frontend/src/index.js"
    click FEHome "https://github.com/karanvirheer/statflix/blob/main/frontend/src/pages/HomePage.js"
    click FECarousel "https://github.com/karanvirheer/statflix/blob/main/frontend/src/pages/CarouselPage.js"
    click FEComp "https://github.com/karanvirheer/statflix/tree/main/frontend/src/components/"
    click BEdocker "https://github.com/karanvirheer/statflix/tree/main/backend/Dockerfile"
    click BEServer "https://github.com/karanvirheer/statflix/blob/main/backend/src/server.js"
    click BETMDB "https://github.com/karanvirheer/statflix/blob/main/backend/src/api/tmdb.js"
    click BEHelper "https://github.com/karanvirheer/statflix/blob/main/backend/src/utils/helpers.js"
    click BEKaggle "https://github.com/karanvirheer/statflix/blob/main/backend/src/utils/kaggle.js"
    click BELog "https://github.com/karanvirheer/statflix/blob/main/backend/src/utils/logging.js"
    click BEdb "https://github.com/karanvirheer/statflix/blob/main/backend/src/db/db.js"
    click CSV1 "https://github.com/karanvirheer/statflix/blob/main/backend/data/ViewingActivity.csv"
    click CSV2 "https://github.com/karanvirheer/statflix/blob/main/backend/data/big.csv"
    click KaggleData "https://github.com/karanvirheer/statflix/tree/main/backend/data/kaggle/"
    click Tests "https://github.com/karanvirheer/statflix/tree/main/backend/data/tests/"

    %% Styles
    classDef orchestrator fill:#D6BBFA,stroke:#79589F,color:#000;
    classDef frontend fill:#B3E5FC,stroke:#0288D1,color:#000;
    classDef backend fill:#C8E6C9,stroke:#388E3C,color:#000;
    classDef database fill:#FFE0B2,stroke:#F57C00,color:#000;
    classDef external fill:#E0E0E0,stroke:#9E9E9E,color:#000;
```
