# sikkgit/cobalt-tools architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, monorepo media-downloading application (“cobalt”) comprised of:
- A Node.js-based backend API (`/api`) that accepts URLs, matches them to service handlers, and proxies or streams media data.
- A SvelteKit-based frontend (`/web`) that provides a browser UI for pasting URLs, selecting options, and downloading media.
- Two shared packages (`/packages/api-client` and `/packages/version-info`) consumed by the frontend (and potentially other clients).
- Documentation and deployment resources (Dockerfile, GitHub workflows, docs).

##### File structure
- Top-level:
- Configuration—`.deepsource.toml`, `.dockerignore`, Dockerfile, GitHub workflows.
- `/api`—the service core:
– Entrypoints: `api/src/core/api.js`, `api/src/cobalt.js`
– Processing pipeline: `api/src/processing/...` with per-service adapters (`youtube.js`, `twitter.js`, etc.)
– Security: JWT, API keys, Cloudflare Turnstile.
– Stores: in-memory, Redis for rate-limiting.
– Streaming module: HLS/internal streams.
- `/web`—the frontend:
– SvelteKit routes (`web/src/routes`)
– Components (`web/src/components`) and UI logic.
– API calls via the shared `api-client` package under `web/src/lib/api`.
– Configuration: Vite, TypeScript, i18n, static assets.
- `/packages`—common libraries.
- `/docs`—user and developer documentation.

##### Key insights from the README
- “Works like a fancy proxy”—API never caches, just streams.
- Fully open-source, Docker-ready, uses AGPL-3.0.
- Encourages self-hosting with rate-limiting / protection guidelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser["Client Browser"]:::ui
        UI_Routes["SvelteKit Routes"]:::ui
        UI_Components["UI Components"]:::ui
    end

    %% Shared Packages
    subgraph "Shared Packages"
        API_Client["api-client"]:::shared
        Version_Info["version-info"]:::shared
    end

    %% API Layer
    subgraph "API Layer"
        APICore["API Core (api/src/core/api.js)"]:::api
        CobaltCore["Cobalt Entrypoint (api/src/cobalt.js)"]:::api
    end

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

    %% Store Layer
    subgraph "Store Layer"
        MemoryStore["memory-store.js"]:::persistence
        RedisStore["redis-store.js"]:::persistence
        RedisRL["redis-ratelimit.js"]:::persistence
        StoreCore["store.js"]:::persistence
    end

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        Match["match.js"]:::api
        MatchAction["match-action.js"]:::api
        RequestProc["request.js"]:::api
        subgraph "Service Adapters"
            Services["services/*.js"]:::api
        end
    end

    %% Stream Manager
    subgraph "Stream Manager"
        HLS["internal-hls.js"]:::api
        InternalStream["internal.js"]:::api
        StreamManage["manage.js"]:::api
        StreamCore["stream.js"]:::api
        SharedStream["shared.js"]:::api
    end

    %% External Services
    ExternalServices["External Media Services"]:::external

    %% Infrastructure
    subgraph "Infrastructure"
        Docker["Dockerfile"]:::infra
        GitHubActions[".github/workflows"]:::infra
        DockerIgnore[".dockerignore"]:::infra
    end

    %% Connections
    Browser -->|uses| UI_Routes
    UI_Routes -->|renders| UI_Components
    UI_Components -->|calls| API_Client
    API_Client -->|REST/JSON| APICore
    APICore -->|initializes| CobaltCore
    APICore -->|auth calls| JWT
    APICore -->|auth calls| APIKeys
    APICore -->|auth calls| Turnstile
    APICore -->|loads secrets| Secrets
    APICore -->|reads/writes| MemoryStore
    APICore -->|reads/writes| RedisStore
    APICore -->|rate-limit| RedisRL
    APICore -->|delegates| Match
    Match --> MatchAction
    MatchAction --> RequestProc
    RequestProc --> Services
    Services -->|fetch media| ExternalServices
    APICore -->|streams via| HLS
    APICore -->|streams via| InternalStream
    APICore -->|manages| StreamManage
    StreamManage --> StreamCore
    StreamCore --> SharedStream
    StreamCore -->|HLS chunks| Browser
    Version_Info -.->|version metadata| Browser
    Version_Info -.->|version metadata| APICore
    Docker -->|build| APICore
    Docker -->|build| Browser
    GitHubActions -->|CI/CD| Docker
    DockerIgnore -->|exclude| Docker

    %% Click Events
    click UI_Routes "https://github.com/sikkgit/cobalt-tools/tree/current/web/src/routes"
    click UI_Components "https://github.com/sikkgit/cobalt-tools/tree/current/web/src/components"
    click APICore "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/core/api.js"
    click CobaltCore "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/cobalt.js"
    click Match "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/processing/match.js"
    click MatchAction "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/processing/match-action.js"
    click RequestProc "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/processing/request.js"
    click Services "https://github.com/sikkgit/cobalt-tools/tree/current/api/src/processing"
    click HLS "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/stream/internal-hls.js"
    click InternalStream "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/stream/internal.js"
    click StreamManage "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/stream/manage.js"
    click StreamCore "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/stream/stream.js"
    click SharedStream "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/stream/shared.js"
    click MemoryStore "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/store/memory-store.js"
    click RedisStore "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/store/redis-store.js"
    click RedisRL "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/store/redis-ratelimit.js"
    click StoreCore "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/store/store.js"
    click JWT "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/security/jwt.js"
    click APIKeys "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/security/api-keys.js"
    click Turnstile "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/security/turnstile.js"
    click Secrets "https://github.com/sikkgit/cobalt-tools/blob/current/api/src/security/secrets.js"
    click API_Client "https://github.com/sikkgit/cobalt-tools/blob/current/packages/api-client/package.json"
    click Version_Info "https://github.com/sikkgit/cobalt-tools/blob/current/packages/version-info/index.js"
    click Docker "https://github.com/sikkgit/cobalt-tools/tree/current/Dockerfile"
    click GitHubActions "https://github.com/sikkgit/cobalt-tools/tree/current/.github/workflows"
    click DockerIgnore "https://github.com/sikkgit/cobalt-tools/blob/current/.dockerignore"

    %% Styles
    classDef ui fill:#cceeff,stroke:#0066cc
    classDef api fill:#ccffcc,stroke:#339933
    classDef persistence fill:#ffe6cc,stroke:#ff8000
    classDef external fill:#e0e0e0,stroke:#666666
    classDef infra fill:#f2f2f2,stroke:#999999
    classDef shared fill:#e6ccff,stroke:#8000ff
```
