# imputnet/cobalt architecture

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

- Interactive diagram: https://gitdiagram.com/imputnet/cobalt
- Repository: https://github.com/imputnet/cobalt
- Video tour (about a minute): https://gitdiagram.com/imputnet/cobalt/video

## Overview

Cobalt is a browser-based downloader backed by an API that resolves public media links and provides download or streaming responses; it also supports client-side processing. The principal user flow is link submission, API request, then download, selection, or local processing. The web task manager coordinates fetch and FFmpeg workers, while settings and file storage support configurable and local workflows. The README describes the API as a non-caching proxy. Some internal API wiring is unsampled, so those call relationships are intentionally omitted.

Main entry points: [`web/src/lib/api/saving-handler.ts`](https://github.com/imputnet/cobalt/blob/main/web/src/lib/api/saving-handler.ts) (Save handler), [`api/src/core/api.js`](https://github.com/imputnet/cobalt/blob/main/api/src/core/api.js) (API routing), [`web/src/lib/api/api.ts`](https://github.com/imputnet/cobalt/blob/main/web/src/lib/api/api.ts) (API client), [`web/src/lib/task-manager/run-worker.ts`](https://github.com/imputnet/cobalt/blob/main/web/src/lib/task-manager/run-worker.ts) (Worker dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_saveui["Link entry<br/>[Omnibox.svelte]"]
  node_savehandler["Save handler<br/>[saving-handler.ts]"]
  node_webapi["API client<br/>[api.ts]"]
  node_download["Download handling<br/>[download.ts]"]
  node_serviceinfo["Supported services"]
  node_serverinfo["Server information<br/>[server-info.ts]"]
end

subgraph group_api["API and services"]
  node_apientry["API entry<br/>[cobalt.js]"]
  node_api_core["API routing<br/>[api.js]"]
  node_request["Media request<br/>[request.js]"]
  node_urlmatch["URL matching<br/>[match.js]"]
  node_services["Service adapters"]
  node_stream["Streaming proxy<br/>[stream.js]"]
  node_streammanage["Stream management<br/>[manage.js]"]
  node_security["Request security"]
  node_api_store[("API storage<br/>[store.js]")]
end

subgraph group_workers["Local processing"]
  node_pipeline["Task pipeline<br/>[queue.ts]"]
  node_runner["Worker dispatch<br/>[run-worker.ts]"]
  node_fetchworker["Fetch worker<br/>[fetch.ts]"]
  node_ffmpegworker["FFmpeg worker<br/>[ffmpeg.ts]"]
end

subgraph group_state["Client state"]
  node_settings["Download settings<br/>[settings.ts]"]
  node_file_storage[("Local file storage<br/>[index.ts]")]
end

node_user(("User"))

node_user -->|"enters link"| node_saveui
node_saveui -->|"submits request"| node_savehandler
node_savehandler -->|"sends request"| node_webapi
node_savehandler -->|"reads options"| node_settings
node_webapi -->|"calls API"| node_api_core
node_savehandler -->|"starts download"| node_download
node_savehandler -->|"starts local job"| node_pipeline
node_pipeline -->|"dispatches tasks"| node_runner
node_runner -->|"runs fetch"| node_fetchworker
node_runner -->|"runs conversion"| node_ffmpegworker
node_user -->|"views services"| node_serviceinfo
node_serviceinfo -->|"loads service list"| node_serverinfo
node_webapi -->|"sends API request"| node_apientry
node_apientry -->|"routes request"| node_api_core
node_api_core -->|"checks access"| node_security
node_api_core -->|"handles media request"| node_request
node_request -->|"matches link"| node_urlmatch
node_urlmatch -->|"selects service"| node_services
node_api_core -->|"manages stream"| node_streammanage
node_streammanage -->|"dispatches stream"| node_stream
node_api_core -.->|"uses storage"| node_api_store
node_savehandler -->|"local processing files"| node_file_storage

click node_saveui "https://github.com/imputnet/cobalt/blob/main/web/src/components/save/Omnibox.svelte"
click node_savehandler "https://github.com/imputnet/cobalt/blob/main/web/src/lib/api/saving-handler.ts"
click node_webapi "https://github.com/imputnet/cobalt/blob/main/web/src/lib/api/api.ts"
click node_download "https://github.com/imputnet/cobalt/blob/main/web/src/lib/download.ts"
click node_apientry "https://github.com/imputnet/cobalt/blob/main/api/src/cobalt.js"
click node_api_core "https://github.com/imputnet/cobalt/blob/main/api/src/core/api.js"
click node_request "https://github.com/imputnet/cobalt/blob/main/api/src/processing/request.js"
click node_urlmatch "https://github.com/imputnet/cobalt/blob/main/api/src/processing/match.js"
click node_services "https://github.com/imputnet/cobalt/tree/main/api/src/processing/services"
click node_stream "https://github.com/imputnet/cobalt/blob/main/api/src/stream/stream.js"
click node_streammanage "https://github.com/imputnet/cobalt/blob/main/api/src/stream/manage.js"
click node_security "https://github.com/imputnet/cobalt/tree/main/api/src/security"
click node_api_store "https://github.com/imputnet/cobalt/blob/main/api/src/store/store.js"
click node_pipeline "https://github.com/imputnet/cobalt/blob/main/web/src/lib/task-manager/queue.ts"
click node_runner "https://github.com/imputnet/cobalt/blob/main/web/src/lib/task-manager/run-worker.ts"
click node_fetchworker "https://github.com/imputnet/cobalt/blob/main/web/src/lib/task-manager/runners/fetch.ts"
click node_ffmpegworker "https://github.com/imputnet/cobalt/blob/main/web/src/lib/task-manager/runners/ffmpeg.ts"
click node_settings "https://github.com/imputnet/cobalt/blob/main/web/src/lib/state/settings.ts"
click node_file_storage "https://github.com/imputnet/cobalt/blob/main/web/src/lib/storage/index.ts"
click node_serviceinfo "https://github.com/imputnet/cobalt/blob/main/web/src/components/save/SupportedServices.svelte"
click node_serverinfo "https://github.com/imputnet/cobalt/blob/main/web/src/lib/api/server-info.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_saveui,node_savehandler,node_webapi,node_download,node_serviceinfo,node_serverinfo,node_user toneBlue
class node_apientry,node_api_core,node_request,node_urlmatch,node_services,node_stream,node_streammanage,node_security,node_api_store toneAmber
class node_pipeline,node_runner,node_fetchworker,node_ffmpegworker toneMint
class node_settings,node_file_storage toneRose
```

## Components

### Web application

- [Link entry](https://github.com/imputnet/cobalt/blob/main/web/src/components/save/Omnibox.svelte): `web/src/components/save/Omnibox.svelte`
- [Save handler](https://github.com/imputnet/cobalt/blob/main/web/src/lib/api/saving-handler.ts): `web/src/lib/api/saving-handler.ts`
- [API client](https://github.com/imputnet/cobalt/blob/main/web/src/lib/api/api.ts): `web/src/lib/api/api.ts`
- [Download handling](https://github.com/imputnet/cobalt/blob/main/web/src/lib/download.ts): `web/src/lib/download.ts`
- [Supported services](https://github.com/imputnet/cobalt/blob/main/web/src/components/save/SupportedServices.svelte): `web/src/components/save/SupportedServices.svelte`
- [Server information](https://github.com/imputnet/cobalt/blob/main/web/src/lib/api/server-info.ts): `web/src/lib/api/server-info.ts`

### API and services

- [API entry](https://github.com/imputnet/cobalt/blob/main/api/src/cobalt.js): `api/src/cobalt.js`
- [API routing](https://github.com/imputnet/cobalt/blob/main/api/src/core/api.js): `api/src/core/api.js`
- [Media request](https://github.com/imputnet/cobalt/blob/main/api/src/processing/request.js): `api/src/processing/request.js`
- [URL matching](https://github.com/imputnet/cobalt/blob/main/api/src/processing/match.js): `api/src/processing/match.js`
- [Service adapters](https://github.com/imputnet/cobalt/tree/main/api/src/processing/services): `api/src/processing/services`
- [Streaming proxy](https://github.com/imputnet/cobalt/blob/main/api/src/stream/stream.js): `api/src/stream/stream.js`
- [Stream management](https://github.com/imputnet/cobalt/blob/main/api/src/stream/manage.js): `api/src/stream/manage.js`
- [Request security](https://github.com/imputnet/cobalt/tree/main/api/src/security): `api/src/security`
- [API storage](https://github.com/imputnet/cobalt/blob/main/api/src/store/store.js): `api/src/store/store.js`

### Local processing

- [Task pipeline](https://github.com/imputnet/cobalt/blob/main/web/src/lib/task-manager/queue.ts): `web/src/lib/task-manager/queue.ts`
- [Worker dispatch](https://github.com/imputnet/cobalt/blob/main/web/src/lib/task-manager/run-worker.ts): `web/src/lib/task-manager/run-worker.ts`
- [Fetch worker](https://github.com/imputnet/cobalt/blob/main/web/src/lib/task-manager/runners/fetch.ts): `web/src/lib/task-manager/runners/fetch.ts`
- [FFmpeg worker](https://github.com/imputnet/cobalt/blob/main/web/src/lib/task-manager/runners/ffmpeg.ts): `web/src/lib/task-manager/runners/ffmpeg.ts`

### Client state

- [Download settings](https://github.com/imputnet/cobalt/blob/main/web/src/lib/state/settings.ts): `web/src/lib/state/settings.ts`
- [Local file storage](https://github.com/imputnet/cobalt/blob/main/web/src/lib/storage/index.ts): `web/src/lib/storage/index.ts`

### Other components

- **User**

## Connections

- User → Link entry: enters link
- Link entry → Save handler: submits request
- Save handler → API client: sends request
- Save handler → Download settings: reads options
- API client → API routing: calls API
- Save handler → Download handling: starts download
- Save handler → Task pipeline: starts local job
- Task pipeline → Worker dispatch: dispatches tasks
- Worker dispatch → Fetch worker: runs fetch
- Worker dispatch → FFmpeg worker: runs conversion
- User → Supported services: views services
- Supported services → Server information: loads service list
- API client → API entry: sends API request
- API entry → API routing: routes request
- API routing → Request security: checks access
- API routing → Media request: handles media request
- Media request → URL matching: matches link
- URL matching → Service adapters: selects service
- API routing → Stream management: manages stream
- Stream management → Streaming proxy: dispatches stream
- API routing → API storage: uses storage
- Save handler → Local file storage: local processing files
