# arunnkutty/videostreaming architecture

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

- Interactive diagram: https://gitdiagram.com/arunnkutty/videostreaming
- Repository: https://github.com/arunnkutty/videostreaming

## Overview

##### Project Type & Purpose
- This is a full-stack video streaming and email-scheduling platform.
- Frontend: TypeScript/React app (HLS.js video player, scheduling UI).
- Backend: Python FastAPI monolith providing video APIs, upload/processing (FFmpeg + HLS), email scheduling (APScheduler + Resend), and health endpoints.

##### Main Components
a. Frontend (Browser/React App)
- Video Player component (HLS.js)
- Video Scheduler component (FullCalendar.js UI)
- HTTP calls to backend REST API
b. Backend (FastAPI Server)
- API Routes layer (/api/v1/health, /videos, /schedules, /calendar)
- Core layer (config, error handling)
- Models layer (Pydantic schemas for video & schedule)
- Services layer:
- video_service (invokes FFmpeg, writes HLS segments to local storage)
- scheduler_service (APScheduler job registration & management)
- email_service (calls Resend API with chosen template)
- Static file server (serves /videos/[video‐id]/index.m3u8 and .ts segments)
c. Storage & External Systems
- Local File System storage (“videos” directory)
- External Email API (Resend)
- FFmpeg process (for video ingestion → HLS conversion)

##### Relationships & Data Flows
- User’s browser → HTTP(S) → Frontend React App
- React App → REST API calls → FastAPI server
- FastAPI video upload endpoint → FFmpeg → write HLS segments → videos/ directory
- FastAPI HLS endpoints → serve .m3u8 + .ts files back to React/HLS.js
- React/HLS.js streams video segments in real time
- Scheduler creation calls FastAPI → scheduler_service registers APScheduler job
- APScheduler (in-process background) triggers job at scheduled times → calls email_service → Resend API → email delivered
- Calendar UI fetches scheduled events from FastAPI → FullCalendar renders on React side

##### Architectural Patterns & Design Principles
- Layered architecture: API → services → models → storage
- Separation of concerns: video logic vs. scheduling vs. emailing
- Monolithic deployment (single FastAPI container), but clearly modularized for future microservices split
- Use of background job scheduler (APScheduler) for decoupled timed tasks

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (React/TypeScript)" 
        direction TB
        Browser["User's Browser"]:::frontend
        ReactApp["React App"]:::frontend
        HLSComp["HLSPlayer Component"]:::frontend
        SchedulerComp["VideoScheduler Component"]:::frontend
        Types["API Types"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI/Python)" 
        direction TB
        APIRoutes["API Routes"]:::backend
        subgraph "API Routes"
            direction TB
            Health["/api/v1/health"]:::api
            VideoAPI["/api/v1/videos"]:::api
            ScheduleAPI["/api/v1/schedules"]:::api
            CalendarAPI["/api/v1/calendar"]:::api
        end
        subgraph "Core & Models"
            direction TB
            Config["Configuration"]:::backend
            Exceptions["Error Handling"]:::backend
            VideoModel["Video Schema"]:::backend
            SchedulerModel["Scheduler Schema"]:::backend
        end
        subgraph "Services"
            direction TB
            VideoService["video_service"]:::service
            SchedulerService["scheduler_service"]:::service
            EmailService["email_service"]:::service
        end
        StaticServer["Static File Server"]:::service
        APScheduler["APScheduler (Background Scheduler)"]:::service
    end

    %% Storage & External Systems
    Storage["Local File System (videos/)"]:::storage
    FFmpeg["FFmpeg Process"]:::storage
    Resend["Resend Email API"]:::external

    %% Data Flows
    Browser --> ReactApp
    ReactApp -->|HTTP REST| APIRoutes
    ReactApp --> HLSComp
    ReactApp --> SchedulerComp
    ReactApp --> Types

    HLSComp -->|Fetch HLS Segments| StaticServer
    StaticServer --> Storage

    APIRoutes --> VideoAPI
    APIRoutes --> ScheduleAPI
    APIRoutes --> CalendarAPI
    APIRoutes --> Health

    VideoAPI --> VideoService
    VideoService --> FFmpeg
    VideoService --> Storage

    ScheduleAPI --> SchedulerService
    SchedulerService --> APScheduler
    APScheduler -->|Trigger Job| EmailService
    EmailService -->|Send Email| Resend

    APIRoutes --> Config
    APIRoutes --> Exceptions
    APIRoutes --> VideoModel
    APIRoutes --> SchedulerModel

    %% Click Events
    click ReactApp "https://github.com/arunnkutty/videostreaming/tree/main/react-hls-player/"
    click HLSComp "https://github.com/arunnkutty/videostreaming/blob/main/react-hls-player/src/components/HLSPlayer.tsx"
    click SchedulerComp "https://github.com/arunnkutty/videostreaming/blob/main/react-hls-player/src/components/VideoScheduler.tsx"
    click Types "https://github.com/arunnkutty/videostreaming/blob/main/react-hls-player/src/types/api.ts"
    click main "https://github.com/arunnkutty/videostreaming/blob/main/app/main.py"
    click Health "https://github.com/arunnkutty/videostreaming/blob/main/app/api/routes/health.py"
    click VideoAPI "https://github.com/arunnkutty/videostreaming/blob/main/app/api/routes/video.py"
    click ScheduleAPI "https://github.com/arunnkutty/videostreaming/blob/main/app/api/routes/scheduler.py"
    click Config "https://github.com/arunnkutty/videostreaming/blob/main/app/core/config.py"
    click Exceptions "https://github.com/arunnkutty/videostreaming/blob/main/app/core/exceptions.py"
    click VideoModel "https://github.com/arunnkutty/videostreaming/blob/main/app/models/video.py"
    click SchedulerModel "https://github.com/arunnkutty/videostreaming/blob/main/app/models/scheduler.py"
    click VideoService "https://github.com/arunnkutty/videostreaming/blob/main/app/services/video_service.py"
    click SchedulerService "https://github.com/arunnkutty/videostreaming/blob/main/app/services/scheduler_service.py"
    click EmailService "https://github.com/arunnkutty/videostreaming/blob/main/app/services/email_service.py"
    click Storage "https://github.com/arunnkutty/videostreaming/tree/main/videos/"
    click main "https://github.com/arunnkutty/videostreaming/blob/main/main.py"
    click _env "https://github.com/arunnkutty/videostreaming/blob/main/.env.example"
    click Dockerfile "https://github.com/arunnkutty/videostreaming/tree/main/Dockerfile"
    click requirements "https://github.com/arunnkutty/videostreaming/blob/main/requirements.txt"
    click EMAIL_SCHEDULER_SETUP "https://github.com/arunnkutty/videostreaming/blob/main/EMAIL_SCHEDULER_SETUP.md"

    %% Styling
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#DFFFE0,stroke:#28A745,color:#1B5E20;
    classDef api fill:#E0F7FA,stroke:#00ACC1,color:#006064;
    classDef service fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef storage fill:#FFF9C4,stroke:#FBC02D,color:#F57F17;
    classDef external fill:#FFE0B2,stroke:#FB8C00,color:#E65100
```
