# mfang0126/grab-youtube architecture

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

- Interactive diagram: https://gitdiagram.com/mfang0126/grab-youtube
- Repository: https://github.com/mfang0126/grab-youtube

## Overview

##### Project type and purpose
- This is a Next.js–based full-stack web application (“Grab your YouTube”) that lets users submit YouTube URLs, select formats, enqueue download jobs, and watch real-time progress.
- Key indicators:
- A typical Next.js directory (`pages`, `public`, `next.config.mjs`)
- API routes under `src/pages/api/*` for auth, video, jobs, cron
- Services calling MongoDB (`mongodb.ts`) and YouTube download logic (`youtube-services.ts`)
- Dockerfile and env examples for deployment.

##### File structure
- Top-level:
- `src/pages` → Next.js pages and API routes
- `src/components` → UI components (forms, tables, progress bars)
- `src/contexts` & `src/hooks` → React context and custom hooks (SSE, toasts, video logic)
- `src/services` → boundary layer for external resources (MongoDB, YouTube, generic API calls)
- `src/libs` → business logic like `ProgressTracker`
- `src/utils` → pure helpers (file I/O, formatting, merging audio/video)
- Config, build, and deployment: `Dockerfile`, `.dockerignore`, `vercel.json`, `next.config.mjs`, TypeScript (`tsconfig.json`), Tailwind config, ESLint, Prettier.

##### README for additional insights
- Describes Docker-based deployment, environment variables (MongoDB URI, Node version, etc.).
- Mentions UI irregularities and job‐progress logic, hinting at two key flows: enqueueing jobs and streaming progress events.

##### Elements
- Labels: e.g., “Next.js Frontend,” “API /jobs Queue,” “MongoDB Cluster,” “YouTube Service.”
- Blue for client/UI
- Green for API routes/services
- Yellow for external dependencies (YouTube, MongoDB)
- Docker container outline for the entire system
- Cloud or external-service cloud for YouTube/OAuth

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User Browser"]:::client

    %% Docker Container Group
    subgraph "Docker Container" 
        direction TB

        %% Frontend
        subgraph "Next.js Frontend" 
            direction TB
            HomePage["Home Page"]:::client
            LoginPage["Login Page"]:::client
            AppWrapper["_app.tsx"]:::client
            Document["_document.tsx"]:::client
            UrlInput["URL Input Form"]:::client
            FormatsSel["Format Selection"]:::client
            FormatsBtn["Formats Button Group"]:::client
            JobsSection["Jobs Section"]:::client
            JobsTable["Jobs Table"]:::client
            ProgressJob["Progress Job"]:::client
            ProgressBar["Progress Bar"]:::client
            DownloadFilesList["Download Files List"]:::client
            Toast["Toast Notifications"]:::client
            Wrapper["Layout Wrapper"]:::client
            Heading["Heading"]:::client
            Title["Title"]:::client
            ToastContext["Toast Context"]:::client
            EventSourceHook["useEventSource Hook"]:::client
            ProgressHook["useProgress Hook"]:::client
            VideoHook["useVideo Hook"]:::client
            ToastHook["useToast Hook"]:::client
            APIServiceWrapper["API Service Wrapper"]:::api
        end

        %% Backend
        subgraph "Next.js API Server" 
            direction TB
            Auth["Auth Service ([...nextauth].ts)"]:::api
            VideoAPI["Video API (/api/video)"]:::api
            EnqueueJob["Enqueue Job (/api/jobs/queue)"]:::api
            StartJob["Start Job (/api/jobs/[id]/start)"]:::api
            JobDetails["Job Details (/api/jobs/[id])"]:::api
            ProgressSSE["Progress SSE (/api/jobs/[id]/progress)"]:::api
            FileService["File Service (/api/files)"]:::api
            Cron["Cron Endpoint (/api/cron)"]:::api
            MongoService["MongoDB Service"]:::service
            YouTubeService["YouTube Service"]:::service
            ProgressTracker["ProgressTracker"]:::service
            MergeAV["mergeAudioVideo"]:::service
            DirHelper["dirHelper"]:::service
            FormatHelper["videoFormatHelper"]:::service
            FormatBytes["formatBytes"]:::service
            RemoveFiles["removeFilesWithExtensions"]:::service
            StringHelper["stringHelper"]:::service
        end
    end

    %% External Services
    MongoDB["MongoDB Cluster"]:::external
    YouTube["YouTube"]:::external
    OAuth["OAuth Provider"]:::external

    %% Connections
    User -->|"interacts with"| HomePage
    User --> LoginPage
    HomePage -->|"calls API"| APIServiceWrapper
    LoginPage --> APIServiceWrapper
    APIServiceWrapper --> Auth
    APIServiceWrapper --> VideoAPI
    APIServiceWrapper --> EnqueueJob
    APIServiceWrapper --> FileService
    APIServiceWrapper --> Cron

    EnqueueJob --> StartJob
    StartJob --> ProgressSSE
    StartJob --> MongoService
    EnqueueJob --> MongoService
    JobDetails --> MongoService
    ProgressSSE --> ProgressTracker
    ProgressTracker -->|"uses"| MergeAV
    MergeAV --> DirHelper
    MergeAV --> FormatHelper
    MergeAV --> FormatBytes
    MergeAV --> RemoveFiles
    MergeAV --> StringHelper
    MergeAV --> YouTubeService
    YouTubeService --> YouTube
    Auth --> OAuth
    MongoService --> MongoDB

    ProgressSSE -.->|"SSE stream"| EventSourceHook
    EventSourceHook --> ProgressHook
    ProgressHook --> ProgressJob
    ProgressJob --> ProgressBar
    JobsSection --> JobsTable
    JobsSection --> ProgressJob
    JobsSection --> DownloadFilesList
    ToastContext --> Toast
    ToastHook --> ToastContext

    %% Click Events
    click HomePage "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/index.tsx"
    click LoginPage "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/login.tsx"
    click AppWrapper "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/_app.tsx"
    click Document "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/_document.tsx"
    click UrlInput "https://github.com/mfang0126/grab-youtube/blob/master/src/components/UrlInput.tsx"
    click FormatsSel "https://github.com/mfang0126/grab-youtube/blob/master/src/components/FormatsSelection.tsx"
    click FormatsBtn "https://github.com/mfang0126/grab-youtube/blob/master/src/components/FormatsButtonGroup.tsx"
    click JobsSection "https://github.com/mfang0126/grab-youtube/blob/master/src/components/JobsSection.tsx"
    click JobsTable "https://github.com/mfang0126/grab-youtube/blob/master/src/components/JobsTable.tsx"
    click ProgressJob "https://github.com/mfang0126/grab-youtube/blob/master/src/components/ProgressJob.tsx"
    click ProgressBar "https://github.com/mfang0126/grab-youtube/blob/master/src/components/ProgressBar.tsx"
    click DownloadFilesList "https://github.com/mfang0126/grab-youtube/blob/master/src/components/DownloadFilesList.tsx"
    click Toast "https://github.com/mfang0126/grab-youtube/blob/master/src/components/Toast.tsx"
    click Wrapper "https://github.com/mfang0126/grab-youtube/blob/master/src/components/Wrapper.tsx"
    click Heading "https://github.com/mfang0126/grab-youtube/blob/master/src/components/Heading.tsx"
    click Title "https://github.com/mfang0126/grab-youtube/blob/master/src/components/Title.tsx"
    click ToastContext "https://github.com/mfang0126/grab-youtube/blob/master/src/contexts/ToastContext.tsx"
    click EventSourceHook "https://github.com/mfang0126/grab-youtube/blob/master/src/hooks/useEventSource.ts"
    click ProgressHook "https://github.com/mfang0126/grab-youtube/blob/master/src/hooks/useProgress.ts"
    click VideoHook "https://github.com/mfang0126/grab-youtube/blob/master/src/hooks/useVideo.ts"
    click ToastHook "https://github.com/mfang0126/grab-youtube/blob/master/src/hooks/useToast.ts"
    click Auth "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/api/auth/[...nextauth].ts"
    click VideoAPI "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/api/video.ts"
    click EnqueueJob "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/api/jobs/queue.ts"
    click StartJob "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/api/jobs/[id]/start.ts"
    click JobDetails "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/api/jobs/[id].ts"
    click ProgressSSE "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/api/jobs/[id]/progress.ts"
    click FileService "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/api/files.ts"
    click Cron "https://github.com/mfang0126/grab-youtube/blob/master/src/pages/api/cron.ts"
    click MongoService "https://github.com/mfang0126/grab-youtube/blob/master/src/services/mongodb.ts"
    click YouTubeService "https://github.com/mfang0126/grab-youtube/blob/master/src/services/youtube-services.ts"
    click APIServiceWrapper "https://github.com/mfang0126/grab-youtube/blob/master/src/services/api-service.ts"
    click ProgressTracker "https://github.com/mfang0126/grab-youtube/blob/master/src/libs/ProgressTracker.ts"
    click MergeAV "https://github.com/mfang0126/grab-youtube/blob/master/src/utils/mergeAudioVideo.ts"
    click DirHelper "https://github.com/mfang0126/grab-youtube/blob/master/src/utils/dirHelper.ts"
    click FormatHelper "https://github.com/mfang0126/grab-youtube/blob/master/src/utils/videoFormatHelper.ts"
    click FormatBytes "https://github.com/mfang0126/grab-youtube/blob/master/src/utils/formatBytes.ts"
    click RemoveFiles "https://github.com/mfang0126/grab-youtube/blob/master/src/utils/removeFilesWithExtensions.ts"
    click StringHelper "https://github.com/mfang0126/grab-youtube/blob/master/src/utils/stringHelper.ts"

    %% Styles
    classDef client fill:#D6EFFF,stroke:#0284C7,stroke-width:2px
    classDef api fill:#D1FAE5,stroke:#10B981,stroke-width:2px
    classDef service fill:#FEF9C3,stroke:#CA8A04,stroke-width:2px
    classDef external fill:#FEE2E2,stroke:#DC2626,stroke-width:2px
```
