# earnstein/yt-clone architecture

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

- Interactive diagram: https://gitdiagram.com/earnstein/yt-clone
- Repository: https://github.com/earnstein/yt-clone

## Overview

Based on your provided file tree and README, you’re working on a Next.js-based YouTube clone. The project is a full-stack web application that combines a modern frontend built on Next.js (using the new App Router), type-safe APIs via tRPC, authentication with Clerk, ORM and database management using Drizzle, video processing with Mux, and several other external services (Upstash for Redis rate limiting, UploadThing for file uploads, React Query for data fetching/caching, and Tailwind for styling).

##### Main system components
- Frontend (Client-side):
– Next.js App structure with separate routes for Authentication ((auth): sign-in/sign-up), Home ((home): video browsing, search, and general viewing), and Studio ((studio): video uploads, editing, and management)
– Common UI components found under both “src/components” and module-specific UI folders (e.g., UI elements like buttons, forms, modals, etc.)
– Application layouts, sections, and views that guide the user interactions

- API and Services Layer:
– API endpoints in the “src/app/api” directory that provide tRPC endpoints, UploadThing handlers, and webhooks (for users, videos, etc.)
– tRPC routers and client integration under “src/trpc” and within module folders for handling type-safe backend procedures

- Backend Logic and Database:
– Database integration and schema managed by Drizzle ORM under “src/db”
– Server-side logic and procedures distributed across “src/modules” (e.g., auth, home, studio, subscriptions, users, videos, video-views) with clear separation of concerns
– Middleware definitions in “src/middleware.ts”, aggregating cross-cutting concerns

- External Integrations:
– Authentication handled by Clerk
– Video processing via Mux for upload and playback management
– Redis/upstash for rate limiting and caching
– File uploads using UploadThing
– Data fetching and caching assisted by React Query, and API interactions managed by tRPC

##### Relationships and interactions
- Frontend communicates with backend APIs (tRPC based) using React Query to ensure efficient data fetching and caching.
- User authentication and session management are handled by Clerk, so user requests flow through Clerk before reaching the protected API endpoints.
- When users interact with video features (playback, upload), data flows from the browser to the Next.js application, which then calls either internal endpoints (for database operations) or triggers external endpoints via Mux or UploadThing.
- Webhook-based integrations: There are endpoints for webhooks under “src/app/api/users/webhook” and “src/app/api/videos/webhook” that interact with external services (like Clerk and Mux) for real-time notifications or rate limiting.
- tRPC routers and procedures (found in “src/trpc/routers” and “src/modules/**/server/”) handle the core business logic, connecting the frontend requests to database transactions (using Drizzle ORM).

##### Architectural patterns and design principles
- Modularity: The project clearly separates concerns (authentication, video, subscriptions, etc.) with dedicated modules and subdirectories.
- Type Safety: With tRPC and TypeScript, there is an end-to-end type-safe contract between client and server.
- Component Reusability: Shared UI components are centralized in “src/components” and reused across various modules.
- Service Integration: External APIs, services, and webhooks are integrated in a decoupled manner, each responsible for a single area (e.g., Mux for video processing, Clerk for auth).

##### And reference the relevant technologies
- Next.js as the framework for React-based SSR/SSG and App Router.
- tRPC for type-safe API creation.
- Drizzle ORM for database management.
- Clerk (auth), Mux (video processing), Upstash (Redis), UploadThing (uploads), Tailwind CSS (styling), and React Query (data management).

- Separate blocks or sections for Frontend Components (Next.js page routes, shared components, module-based UI) and Backend Components (tRPC API endpoints, server-side procedures, DB via Drizzle).
- Clearly labeled components for authentication (Clerk), video streaming/upload (Mux/UploadThing), database operations (Drizzle ORM), rate limiting (Upstash/Redis), and state/data management (React Query).
– From the client (browser) to the Next.js pages.
– From these pages to API endpoints (tRPC).
– From API endpoints to the database and external integrations.
– Back from external responses to the client.
- Annotations for any middleware or rate limiting (e.g., Upstash integration) where applicable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Components
    subgraph "Frontend Components"
        FE_Auth["Auth Routes"]
        FE_Home["Home Routes"]
        FE_Studio["Studio Routes"]
        FE_UI["Shared UI Components"]
        FE_ModuleUI["Module UI Components"]
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        BE_API["tRPC API Endpoints"]
        BE_Middleware["Middleware"]
        BE_Routers["tRPC Routers & Client Integration"]
        subgraph "Modules"
            BE_Auth_Mod["Auth Module"]
            BE_Videos["Videos Module"]
            BE_VideoViews["Video Views Module"]
            BE_Studio_Mod["Studio Module"]
            BE_Others["Other Modules"]
        end
        BE_DB(("Drizzle ORM Database"))
    end

    %% External Integrations
    subgraph "External Integrations"
        EXT_Clerk["Clerk (Authentication)"]
        EXT_Mux["Mux (Video Processing)"]
        EXT_UploadThing["UploadThing (File Uploads)"]
        EXT_Redis["Redis/Upstash (Rate Limiting)"]
        EXT_ReactQuery["React Query (Data Fetching)"]
    end

    %% Data Flow: Frontend to Backend
    FE_Auth -->|"request"| BE_API
    FE_Home -->|"request"| BE_API
    FE_Studio -->|"request"| BE_API

    %% Authentication Flow through Clerk
    FE_Auth -- "auth request" --> EXT_Clerk
    EXT_Clerk -- "verified"|--> BE_API

    %% Backend processing flow
    BE_API -->|"passes"| BE_Middleware
    BE_Middleware -->|"routes to"| BE_Routers

    %% tRPC routers dispatch to domain modules
    BE_Routers -->|"handles"| BE_Auth_Mod
    BE_Routers -->|"handles"| BE_Videos
    BE_Routers -->|"handles"| BE_VideoViews
    BE_Routers -->|"handles"| BE_Studio_Mod
    BE_Routers -->|"handles"| BE_Others

    %% Database interactions from modules
    BE_Auth_Mod -->|"db query"| BE_DB
    BE_Videos -->|"db query"| BE_DB
    BE_VideoViews -->|"db query"| BE_DB
    BE_Studio_Mod -->|"db query"| BE_DB
    BE_Others -->|"db query"| BE_DB

    %% External service integrations from modules
    BE_Videos -- "video process" --> EXT_Mux
    BE_Videos -- "file upload trigger" --> EXT_UploadThing
    BE_Studio_Mod -- "file upload trigger" --> EXT_UploadThing
    BE_VideoViews -- "rate limit check" --> EXT_Redis

    %% React Query integration with tRPC client
    BE_Routers -- "data cache" --> EXT_ReactQuery

    %% Styles for nodes
    class FE_Auth,FE_Home,FE_Studio,FE_UI,FE_ModuleUI frontend
    class BE_API,BE_Middleware,BE_Routers,BE_Auth_Mod,BE_Videos,BE_VideoViews,BE_Studio_Mod,BE_Others,BE_DB backend
    class EXT_Clerk,EXT_Mux,EXT_UploadThing,EXT_Redis,EXT_ReactQuery external

    %% Click Events for Frontend Components
    click FE_Auth "https://github.com/earnstein/yt-clone/tree/main/src/app/(auth)"
    click FE_Home "https://github.com/earnstein/yt-clone/tree/main/src/app/(home)"
    click FE_Studio "https://github.com/earnstein/yt-clone/tree/main/src/app/(studio)"
    click FE_UI "https://github.com/earnstein/yt-clone/tree/main/src/components"
    click FE_ModuleUI "https://github.com/earnstein/yt-clone/tree/main/src/modules"

    %% Click Events for Backend/API Endpoints and Middleware
    click BE_API "https://github.com/earnstein/yt-clone/blob/main/src/app/api/trpc/[trpc]/route.ts"
    click BE_Routers "https://github.com/earnstein/yt-clone/tree/main/src/trpc/routers"
    click BE_Middleware "https://github.com/earnstein/yt-clone/blob/main/src/middleware.ts"
    click BE_DB "https://github.com/earnstein/yt-clone/tree/main/src/db"

    %% Click Events for Domain Modules
    click BE_Auth_Mod "https://github.com/earnstein/yt-clone/tree/main/src/modules/auth"
    click BE_Videos "https://github.com/earnstein/yt-clone/blob/main/src/modules/videos/server/procedures.ts"
    click BE_VideoViews "https://github.com/earnstein/yt-clone/blob/main/src/modules/video-views/server/procedure.ts"
    click BE_Studio_Mod "https://github.com/earnstein/yt-clone/blob/main/src/modules/studio/server/procedures.ts"

    %% Click Events for External Integrations
    click EXT_Mux "https://github.com/earnstein/yt-clone/blob/main/src/lib/mux.ts"
    click EXT_UploadThing "https://github.com/earnstein/yt-clone/tree/main/src/app/api/uploadthing"
    click EXT_Redis "https://github.com/earnstein/yt-clone/blob/main/src/lib/redis.ts"
    click EXT_ReactQuery "https://github.com/earnstein/yt-clone/blob/main/src/trpc/query-client.ts"

    %% Class definitions with colors
    classDef frontend fill:#fde2e4,stroke:#d64161,stroke-width:2px;
    classDef backend fill:#e0fbfc,stroke:#007ea7,stroke-width:2px;
    classDef external fill:#e7f6f2,stroke:#379683,stroke-width:2px;
```
