# mitthui2k5/cobalt architecture

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

- Interactive diagram: https://gitdiagram.com/mitthui2k5/cobalt
- Repository: https://github.com/mitthui2k5/cobalt

## Overview

##### Project type and purpose
- This is a full-stack monorepo for “cobalt,” a friendly media-downloader service.
- It consists of three logical units:
- An API backend (Node.js) under `/api` that handles link processing, streaming, security and rate-limiting.
- A SvelteKit frontend under `/web` that provides the user interface in the browser.
- Shared libraries and tooling in `/packages`, plus documentation in `/docs`.

##### File structure (top-level)
- Dockerfile, CI configs and workspace files define the build and deploy environment.
- `/api` – a modular Node.js service:
- `src/core` (entrypoint, environment, tunnel)
- `src/processing` (URL matching, service-specific adapters)
- `src/stream` (internal/external HLS, stream management)
- `src/security` (API keys, JWT, Turnstile anti-bot)
- `src/store` (in-memory or Redis back-ends for sessions & rate limits)
- `/web` – a SvelteKit app:
- `src/routes` (page & API routes)
- `src/lib` (API client, state management, task-manager, storage)
- `src/components` (UI building blocks)
- `/packages` – reusable npm modules (e.g., API client, version-info).

##### README for additional insights
- Describes “cobalt” as a proxy-like downloader that never caches content permanently.
- References environment variables and deployment docs.
- Points to Docker and CI flows for “run-an-instance” and “protect-an-instance.”

##### Essential details
- Ffmpeg worker pool under stream processing.
- Don’t over-compartmentalize; show modules only if they represent distinct runtime components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Tier
    subgraph "Frontend Tier"
        Browser["User Browser"]:::frontend
        SvelteKit["/web (SvelteKit)"]:::frontend
    end

    %% Backend Tier
    subgraph "API Backend Tier"
        %% Core Modules
        subgraph "Core Modules"
            Cobalt["cobalt.js"]:::api
            ApiCore["api.js"]:::api
            Env["env.js"]:::api
            ITunnel["itunnel.js"]:::api
        end

        %% Processing Pipeline
        subgraph "Processing Pipeline"
            Match["match.js"]:::api
            Request["request.js"]:::api
            MatchAction["match-action.js"]:::api
            URL["url.js"]:::api
            Helpers["youtube-session.js"]:::api
            Adapters["+20 service adapters"]:::api
        end

        %% Streaming Engine
        subgraph "Streaming Engine"
            InternalHLS["internal-hls.js"]:::api
            Internal["internal.js"]:::api
            Manage["manage.js"]:::api
            Stream["stream.js"]:::api
            SharedStream["shared.js"]:::api
        end

        %% Security Layer
        subgraph "Security Layer"
            ApiKeys["api-keys.js"]:::security
            JWT["jwt.js"]:::security
            Turnstile["turnstile.js"]:::security
            Secrets["secrets.js"]:::security
        end

        %% State Store
        subgraph "State Store"
            BaseStore["base-store.js"]:::store
            MemStore["memory-store.js"]:::store
            RedisStore["redis-store.js"]:::store
            RedisRL["redis-ratelimit.js"]:::store
        end
    end

    %% External & Infrastructure
    External["External Content Providers"]:::external
    Redis["Redis"]:::storeExternal
    CI["CI/CD & Deployment"]:::infra
    Monorepo["Monorepo Packages"]:::infra
    Docs["Documentation (docs/**)"]:::infra

    %% Connections
    Browser -->|"HTTP(S) Static & API" | SvelteKit
    SvelteKit -->|"REST/JSON or WebSocket"| Cobalt
    Cobalt -->|"uses"| ApiCore
    Cobalt -->|"loads"| Env
    Cobalt -->|"initializes"| ITunnel

    Cobalt -->|"invoke"| Match
    Cobalt -->|"invoke"| Request
    Cobalt -->|"invoke"| MatchAction
    Cobalt -->|"invoke"| URL
    Cobalt -->|"invoke"| Helpers
    Cobalt -->|"loads adapters"| Adapters

    Cobalt -->|"spawn"| InternalHLS
    Cobalt -->|"spawn"| Internal
    Cobalt -->|"manage"| Manage
    Cobalt -->|"stream"| Stream
    Cobalt -->|"share"| SharedStream

    Cobalt -->|"validate"| ApiKeys
    Cobalt -->|"validate"| JWT
    Cobalt -->|"validate"| Turnstile
    Cobalt -->|"reads secrets"| Secrets

    Cobalt -->|"reads/writes"| BaseStore
    Cobalt -->|"reads/writes"| MemStore
    Cobalt -->|"reads/writes"| RedisStore
    Cobalt -->|"reads/writes"| RedisRL

    Match -->|"HTTP"| External
    Request -->|"HTTP"| External
    Adapters -->|"HTTP"| External
    InternalHLS -->|"HLS segments"| SvelteKit

    Cobalt -->|"uses"| Redis
    CI -->|"build & deploy"| Monorepo
    CI -->|"deploy container"| CI

    Monorepo -->|"packages"| SvelteKit
    Monorepo -->|"packages"| Cobalt
    Monorepo -->|"packages"| Docs

    %% Click Events
    click Cobalt "https://github.com/mitthui2k5/cobalt/blob/main/api/src/cobalt.js"
    click ApiCore "https://github.com/mitthui2k5/cobalt/blob/main/api/src/core/api.js"
    click Env "https://github.com/mitthui2k5/cobalt/blob/main/api/src/core/env.js"
    click ITunnel "https://github.com/mitthui2k5/cobalt/blob/main/api/src/core/itunnel.js"
    click Match "https://github.com/mitthui2k5/cobalt/blob/main/api/src/processing/match.js"
    click Request "https://github.com/mitthui2k5/cobalt/blob/main/api/src/processing/request.js"
    click MatchAction "https://github.com/mitthui2k5/cobalt/blob/main/api/src/processing/match-action.js"
    click Adapters "https://github.com/mitthui2k5/cobalt/tree/main/api/src/processing/services"
    click URL "https://github.com/mitthui2k5/cobalt/blob/main/api/src/processing/url.js"
    click Helpers "https://github.com/mitthui2k5/cobalt/blob/main/api/src/processing/helpers/youtube-session.js"
    click ApiKeys "https://github.com/mitthui2k5/cobalt/blob/main/api/src/security/api-keys.js"
    click JWT "https://github.com/mitthui2k5/cobalt/blob/main/api/src/security/jwt.js"
    click Turnstile "https://github.com/mitthui2k5/cobalt/blob/main/api/src/security/turnstile.js"
    click Secrets "https://github.com/mitthui2k5/cobalt/blob/main/api/src/security/secrets.js"
    click BaseStore "https://github.com/mitthui2k5/cobalt/blob/main/api/src/store/base-store.js"
    click MemStore "https://github.com/mitthui2k5/cobalt/blob/main/api/src/store/memory-store.js"
    click RedisStore "https://github.com/mitthui2k5/cobalt/blob/main/api/src/store/redis-store.js"
    click RedisRL "https://github.com/mitthui2k5/cobalt/blob/main/api/src/store/redis-ratelimit.js"
    click InternalHLS "https://github.com/mitthui2k5/cobalt/blob/main/api/src/stream/internal-hls.js"
    click Internal "https://github.com/mitthui2k5/cobalt/blob/main/api/src/stream/internal.js"
    click Manage "https://github.com/mitthui2k5/cobalt/blob/main/api/src/stream/manage.js"
    click Stream "https://github.com/mitthui2k5/cobalt/blob/main/api/src/stream/stream.js"
    click SharedStream "https://github.com/mitthui2k5/cobalt/blob/main/api/src/stream/shared.js"
    click Monorepo "https://github.com/mitthui2k5/cobalt/tree/main/packages"
    click Docs "https://github.com/mitthui2k5/cobalt/tree/main/docs/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef api fill:#E6FFEA,stroke:#28A745,color:#28A745;
    classDef security fill:#FFF5B1,stroke:#DBAB09,color:#8A6E00;
    classDef store fill:#FFF5B1,stroke:#DBAB09,color:#8A6E00;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef storeExternal fill:#FFF1F0,stroke:#D73A49,color:#D73A49;
    classDef infra fill:#F6F8FA,stroke:#959DA5,color:#959DA5;
```
