# lordzedith/tiktok architecture

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

- Interactive diagram: https://gitdiagram.com/lordzedith/tiktok
- Repository: https://github.com/lordzedith/tiktok

## Overview

##### Project type and purpose
- This is a full-stack video-sharing platform (a TikTok clone) with two React SPAs (user frontend + admin dashboard), a FastAPI backend, a background processing service for moderation & recommendation (in backend_constant), and a relational database. It implements AI-powered content moderation (video & comments) and a self-training recommendation engine.

##### File structure
- Top-level directories:
- frontend/ – user-facing React app
- admin/ – admin React app for human overrides and dashboards
- backend/ – FastAPI HTTP server (APIs for video upload, streaming, user auth, comments)
- backend_constant/ – long-running Python process that executes scheduled jobs (video moderation via Gemini AI, comment moderation with DistilBERT, recommendation model training, user preference analysis)
- testing/ – scripts to seed/test database & upload sample videos
- Root configs (.env, tailwind.config.js, vite.config.ts) govern environment variables, styling, and builds.
- backend/ contains auth.py, database.py, models.py, schemas.py, recommend_videos.py, and main.py (entry point).
- backend_constant/constant_run.py orchestrates daily and continuous tasks.

##### README for additional insights
- The README outlines:
- AI-moderation pipeline stages (automated screening → human review)
- Video transcoding & thumbnail generation (via FFmpeg)
- Content-based + engagement-based hybrid recommendation, with daily batch retraining
- Continuous user-preference analysis
- Admin dashboard features (override decisions, view logs)
- It even includes a high-level directory sketch under “Architecture.”

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Applications
    subgraph "Frontend Applications"
        direction TB
        UserSPA["User SPA"]:::frontend
        AdminSPA["Admin SPA"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        direction TB
        FastAPI["FastAPI Backend Service"]:::backend
    end

    %% Background Processor
    subgraph "Background Processor (backend_constant)" 
        direction TB
        Worker["Mod & Rec Orchestrator"]:::background
    end

    %% Storage & Data
    subgraph "Storage & Data"
        direction TB
        DB[(Relational Database)]:::storage
        ObjectStorage[(Object Storage / CDN)]:::storage
    end

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        Gemini["Gemini AI"]:::external
        DistilBERT["DistilBERT Model"]:::external
        FFmpeg["FFmpeg Transcoding Engine"]:::external
    end

    %% Testing & Data Setup
    subgraph "Testing & Data Setup"
        direction TB
        TestDB["DB Seed & Test Data"]:::testing
        TestRec["Recommendation Tests"]:::testing
        TestUpload["Video Upload Simulation"]:::testing
    end

    %% Connections
    UserSPA -->|"HTTP(S)"| FastAPI
    AdminSPA -->|"HTTP(S)"| FastAPI

    FastAPI -->|"SQL"| DB
    FastAPI -->|"GET/PUT Files"| ObjectStorage
    FastAPI -->|"Enqueue Tasks"| Worker
    FastAPI -->|"Trigger Transcoding"| FFmpeg
    FastAPI -->|"Serve Recommendations"| ObjectStorage

    Worker -->|"Analyse Video"| Gemini
    Worker -->|"Moderate Comments"| DistilBERT
    Worker -->|"Write Results"| DB
    Worker -->|"Train Models"| DB
    Worker -->|"Store Models"| ObjectStorage

    FFmpeg -->|"Output Media"| ObjectStorage

    TestDB -->|"Seed"| DB
    TestRec -->|"Test APIs"| FastAPI
    TestUpload -->|"Simulate Upload"| FastAPI

    %% Click Events
    click UserSPA "https://github.com/lordzedith/tiktok/blob/main/frontend/main.tsx"
    click UserSPA "https://github.com/lordzedith/tiktok/tree/main/frontend/components/"
    click AdminSPA "https://github.com/lordzedith/tiktok/blob/main/admin/src/main.tsx"
    click AdminSPA "https://github.com/lordzedith/tiktok/blob/main/admin/src/components/ContentModeration.tsx"
    click FastAPI "https://github.com/lordzedith/tiktok/blob/main/backend/main.py"
    click FastAPI "https://github.com/lordzedith/tiktok/blob/main/backend/auth.py"
    click FastAPI "https://github.com/lordzedith/tiktok/blob/main/backend/database.py"
    click FastAPI "https://github.com/lordzedith/tiktok/blob/main/backend/models.py"
    click FastAPI "https://github.com/lordzedith/tiktok/blob/main/backend/schemas.py"
    click FastAPI "https://github.com/lordzedith/tiktok/blob/main/backend/recommend_videos.py"
    click FastAPI "https://github.com/lordzedith/tiktok/blob/main/backend/data_setup.py"
    click Worker "https://github.com/lordzedith/tiktok/blob/main/backend_constant/constant_run.py"
    click DB "https://github.com/lordzedith/tiktok/blob/main/backend/models.py"
    click DB "https://github.com/lordzedith/tiktok/blob/main/backend/database.py"
    click TestDB "https://github.com/lordzedith/tiktok/blob/main/testing/data_setup.py"
    click TestRec "https://github.com/lordzedith/tiktok/blob/main/testing/recommend_videos.py"
    click TestUpload "https://github.com/lordzedith/tiktok/blob/main/testing/upload_videos.py"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#0288D1,color:#000
    classDef backend fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef background fill:#FFE0B2,stroke:#FB8C00,color:#000
    classDef external fill:#FFCDD2,stroke:#C62828,color:#000
    classDef storage fill:#E1BEE7,stroke:#8E24AA,color:#000
    classDef testing fill:#F0F4C3,stroke:#9E9D24,color:#000
```
