# gael-gautho/youtube-player-and-analytics architecture

> Architecture diagram of the GitHub repository gael-gautho/youtube-player-and-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gael-gautho/youtube-player-and-analytics
- Repository: https://github.com/gael-gautho/youtube-player-and-analytics

## Overview

##### Project type and purpose
- This is a full-stack web application for embedding a YouTube player and collecting analytics about video watch sessions and events.
- Next.js (React) powers the frontend UI. FastAPI (Python) provides the backend REST API. Data is persisted in a relational database via SQLAlchemy.

##### File structure
- Top level:
- fastapi_backend/ – Python backend, Dockerized, with API routers under src/api/video_events and src/api/watch_sessions, database session in src/api/db, and main.py entrypoint.
- nextjs_frontend/ – React/Next.js application, organized under src/app (pages + layouts), src/components (UI widgets), src/hooks (custom hooks), and src/lib (utility).
- Docker‐related files in fastapi_backend: Dockerfile.web, compose.yaml, and boot/docker-run.sh for orchestrating containers.
- Backend follows a modular API router pattern. Frontend uses Next.js file‐based routing and React hooks for data fetching.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    User["User (Browser)"]:::user

    %% Frontend Layer
    subgraph "Next.js Frontend"
        direction TB
        PageHome["Home Page (/)" ]:::frontend
        PageTop["Top Videos Page (/top)" ]:::frontend
        PageWatch["Watch Session Page (/watch)" ]:::frontend
        Layout["Global Layout"]:::frontend
        Styles["Global Styles"]:::frontend
        YouTubeForm["YouTubeUrlForm"]:::frontend
        TimeBucket["TimeBucketSelector"]:::frontend
        TopTable["TopVideoTable"]:::frontend
        MetricsTable["MetricsTable"]:::frontend
        HookWatch["useWatchSession"]:::frontend
        HookPlayer["useYouTubePlayer"]:::frontend
        UtilExtract["extractYouTubeInfo"]:::frontend
    end

    %% Backend Layer
    subgraph "FastAPI Backend"
        direction TB
        Main["main.py"]:::backend
        DBSess["DB Session (session.py)"]:::backend
        subgraph "Video Events Module"
            VEModels["models.py"]:::backend
            VERouting["routing.py"]:::backend
        end
        subgraph "Watch Sessions Module"
            WSModels["models.py"]:::backend
            WSRouting["routing.py"]:::backend
        end
    end

    %% Database and External
    DB["Database (PostgreSQL)"]:::db
    YTAPI["YouTube Data API"]:::external

    %% Docker Compose
    subgraph "Docker Compose"
        direction TB
        DCFrontend["Frontend Container"]:::docker
        DCBackend["Backend Container"]:::docker
        DCDatabase["DB Container"]:::docker
    end

    %% Data Flows
    User -->|visits| PageHome
    PageHome -->|renders| YouTubeForm
    PageHome -->|uses| HookWatch
    PageHome -->|wraps via| Layout
    YouTubeForm -->|calls| HookPlayer
    HookPlayer -->|fetches metadata| YTAPI
    PageTop -->|renders| TopTable
    PageWatch -->|renders| MetricsTable
    PageWatch -->|uses| HookWatch
    TopTable -->|requests data| HookWatch
    HookWatch -->|API call| Main
    HookWatch -->|stores session| Main
    Main -->|manages| DBSess
    DBSess -->|queries| DB
    Main -->|routes| VERouting
    VERouting -->|uses| VEModels
    Main -->|routes| WSRouting
    WSRouting -->|uses| WSModels
    Main -->|requests video info| YTAPI

    %% Docker Compose Connections
    DCFrontend -->|communicates| DCBackend
    DCBackend -->|connects| DCDatabase

    %% Click Events - Frontend
    click PageHome "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/app/page.js"
    click PageTop "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/app/top/page.jsx"
    click PageWatch "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/app/watch/page.js"
    click Layout "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/app/layout.js"
    click Styles "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/app/globals.css"
    click YouTubeForm "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/components/YouTubeUrlForm.jsx"
    click TimeBucket "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/components/TimeBucketSelector.jsx"
    click TopTable "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/app/top/topVideoTable.jsx"
    click MetricsTable "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/app/watch/metricsTable.jsx"
    click HookWatch "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/hooks/useWatchSession.jsx"
    click HookPlayer "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/hooks/useYouTubePlayer.jsx"
    click UtilExtract "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/nextjs_frontend/src/lib/extractYouTubeInfo.js"

    %% Click Events - Backend
    click Main "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/fastapi_backend/src/main.py"
    click DBSess "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/fastapi_backend/src/api/db/session.py"
    click VEModels "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/fastapi_backend/src/api/video_events/models.py"
    click VERouting "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/fastapi_backend/src/api/video_events/routing.py"
    click WSModels "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/fastapi_backend/src/api/watch_sessions/models.py"
    click WSRouting "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/fastapi_backend/src/api/watch_sessions/routing.py"

    %% Click Events - Docker
    click DCFrontend "https://github.com/gael-gautho/youtube-player-and-analytics/tree/main/nextjs_frontend/"
    click DCBackend "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/fastapi_backend/Dockerfile.web"
    click DCDatabase "https://github.com/gael-gautho/youtube-player-and-analytics/blob/main/fastapi_backend/compose.yaml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#E6FFDA,stroke:#22863a,stroke-width:1px
    classDef db fill:#FFE5B4,stroke:#d73a49,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#6a737d,stroke-dasharray: 5 5
    classDef docker fill:#F5E1FF,stroke:#6f42c1,stroke-width:1px
    classDef user fill:#FFFFFF,stroke:#444444,stroke-width:1px,stroke-dasharray: 2 2
```
