# fufu-noir/arcod architecture

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

- Interactive diagram: https://gitdiagram.com/fufu-noir/arcod
- Repository: https://github.com/fufu-noir/arcod

## Overview

ARCOD is a self-hosted Qobuz music search and high-resolution download application. Users search or paste a music link, choose options, then receive a temporary download link; downloads may be processed on the VPS or an optional home worker. The README documents the end-to-end stages and integrations. Source excerpts confirm selected frontend, server, and worker calls; other relationships below rely on README statements, and unsampled internals are represented only where documented.

Main entry points: [`server/src/services/processor.ts`](https://github.com/fufu-noir/arcod/blob/main/server/src/services/processor.ts) (Job processor), [`server/src/index.ts`](https://github.com/fufu-noir/arcod/blob/main/server/src/index.ts) (Fastify API), [`server/src/routes/downloads.ts`](https://github.com/fufu-noir/arcod/blob/main/server/src/routes/downloads.ts) (Download API), [`app/search-view.tsx`](https://github.com/fufu-noir/arcod/blob/main/app/search-view.tsx) (Search and results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web experience"]
  node_web["Search and results<br/>[search-view.tsx]"]
  node_auth["Authentication<br/>[auth-provider.tsx]"]
  node_history["Download history<br/>[page.tsx]"]
  node_admin["Admin controls<br/>[page.tsx]"]
end

subgraph group_catalog["Music catalog"]
  node_catalogapi["Catalog API<br/>[catalog.ts]"]
  node_qobuzclient["Qobuz client<br/>[qobuz-dl.tsx]"]
  node_serverqobuz["Server Qobuz client"]
end

subgraph group_jobs["Download processing"]
  node_downloadapi["Download API<br/>[downloads.ts]"]
  node_processor["Job processor<br/>[processor.ts]"]
  node_scheduler["Job scheduler<br/>[scheduler.ts]"]
  node_worker["Home worker<br/>[index.ts]"]
  node_workerprocessor["Worker processing<br/>[processor.ts]"]
  node_lyrics["Lyrics metadata<br/>[lyrics.ts]"]
end

subgraph group_platform["Backend platform"]
  node_database[("SQLite jobs<br/>[client.ts]")]
  node_server["Fastify API<br/>[index.ts]"]
  node_adminroutes["Admin and security<br/>[admin.ts]"]
  node_workerroutes["Worker API<br/>[workers.ts]"]
end

subgraph group_integrations["External services"]
  node_qobuz["Qobuz service"]
  node_supabase["Supabase auth"]
  node_lambda["AWS Lambda proxy"]
  node_r2[("Cloudflare R2<br/>[r2.ts]")]
end

node_user(("Music user"))
node_downloadlink["Temporary download"]

node_user -->|"searches or pastes"| node_web
node_web -->|"requests catalog"| node_catalogapi
node_catalogapi -->|"queries catalog"| node_qobuz
node_qobuzclient -.->|"queries"| node_qobuz
node_web -->|"uses search"| node_qobuzclient
node_user -->|"signs in"| node_auth
node_auth -->|"authenticates"| node_supabase
node_web -->|"requests download"| node_downloadapi
node_downloadapi -->|"creates job"| node_database
node_server -->|"registers routes"| node_downloadapi
node_server -->|"registers routes"| node_adminroutes
node_server -->|"registers routes"| node_workerroutes
node_server -->|"starts processing"| node_processor
node_server -->|"starts tasks"| node_scheduler
node_scheduler -->|"loads pending jobs"| node_database
node_processor -.->|"reads job state"| node_database
node_processor -->|"downloads tracks"| node_qobuz
node_processor -->|"proxies requests"| node_lambda
node_processor -.->|"adds lyrics"| node_lyrics
node_processor -->|"uploads result"| node_r2
node_worker -->|"claims and updates"| node_workerroutes
node_worker -->|"processes jobs"| node_workerprocessor
node_workerprocessor -->|"downloads tracks"| node_qobuz
node_workerprocessor -->|"uploads result"| node_r2
node_downloadapi -.->|"queues job"| node_processor
node_r2 -->|"hosts temporary file"| node_downloadlink
node_user -->|"receives link"| node_downloadlink
node_history -->|"manages downloads"| node_downloadapi
node_admin -.->|"manages jobs"| node_adminroutes
node_adminroutes -.->|"manages routing and blocks"| node_database

click node_web "https://github.com/fufu-noir/arcod/blob/main/app/search-view.tsx"
click node_auth "https://github.com/fufu-noir/arcod/blob/main/components/auth-provider.tsx"
click node_history "https://github.com/fufu-noir/arcod/blob/main/app/history/page.tsx"
click node_admin "https://github.com/fufu-noir/arcod/blob/main/app/admin/page.tsx"
click node_catalogapi "https://github.com/fufu-noir/arcod/blob/main/server/src/routes/catalog.ts"
click node_qobuzclient "https://github.com/fufu-noir/arcod/blob/main/lib/qobuz-dl.tsx"
click node_serverqobuz "https://github.com/fufu-noir/arcod/blob/main/lib/qobuz-dl-server.tsx"
click node_downloadapi "https://github.com/fufu-noir/arcod/blob/main/server/src/routes/downloads.ts"
click node_processor "https://github.com/fufu-noir/arcod/blob/main/server/src/services/processor.ts"
click node_scheduler "https://github.com/fufu-noir/arcod/blob/main/server/src/services/scheduler.ts"
click node_worker "https://github.com/fufu-noir/arcod/blob/main/home-worker/src/index.ts"
click node_workerprocessor "https://github.com/fufu-noir/arcod/blob/main/home-worker/src/processor.ts"
click node_database "https://github.com/fufu-noir/arcod/blob/main/server/src/db/client.ts"
click node_server "https://github.com/fufu-noir/arcod/blob/main/server/src/index.ts"
click node_adminroutes "https://github.com/fufu-noir/arcod/blob/main/server/src/routes/admin.ts"
click node_workerroutes "https://github.com/fufu-noir/arcod/blob/main/server/src/routes/workers.ts"
click node_lyrics "https://github.com/fufu-noir/arcod/blob/main/home-worker/src/lyrics.ts"
click node_r2 "https://github.com/fufu-noir/arcod/blob/main/server/src/storage/r2.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_web,node_auth,node_history,node_admin,node_user toneBlue
class node_catalogapi,node_qobuzclient,node_serverqobuz toneAmber
class node_downloadapi,node_processor,node_scheduler,node_worker,node_workerprocessor,node_lyrics toneMint
class node_database,node_server,node_adminroutes,node_workerroutes toneRose
class node_qobuz,node_supabase,node_lambda,node_r2,node_downloadlink toneIndigo
```

## Components

### Web experience

- [Search and results](https://github.com/fufu-noir/arcod/blob/main/app/search-view.tsx): `app/search-view.tsx`
- [Authentication](https://github.com/fufu-noir/arcod/blob/main/components/auth-provider.tsx): `components/auth-provider.tsx`
- [Download history](https://github.com/fufu-noir/arcod/blob/main/app/history/page.tsx): `app/history/page.tsx`
- [Admin controls](https://github.com/fufu-noir/arcod/blob/main/app/admin/page.tsx): `app/admin/page.tsx`

### Music catalog

- [Catalog API](https://github.com/fufu-noir/arcod/blob/main/server/src/routes/catalog.ts): `server/src/routes/catalog.ts`
- [Qobuz client](https://github.com/fufu-noir/arcod/blob/main/lib/qobuz-dl.tsx): `lib/qobuz-dl.tsx`
- [Server Qobuz client](https://github.com/fufu-noir/arcod/blob/main/lib/qobuz-dl-server.tsx): `lib/qobuz-dl-server.tsx`

### Download processing

- [Download API](https://github.com/fufu-noir/arcod/blob/main/server/src/routes/downloads.ts): `server/src/routes/downloads.ts`
- [Job processor](https://github.com/fufu-noir/arcod/blob/main/server/src/services/processor.ts): `server/src/services/processor.ts`
- [Job scheduler](https://github.com/fufu-noir/arcod/blob/main/server/src/services/scheduler.ts): `server/src/services/scheduler.ts`
- [Home worker](https://github.com/fufu-noir/arcod/blob/main/home-worker/src/index.ts): `home-worker/src/index.ts`
- [Worker processing](https://github.com/fufu-noir/arcod/blob/main/home-worker/src/processor.ts): `home-worker/src/processor.ts`
- [Lyrics metadata](https://github.com/fufu-noir/arcod/blob/main/home-worker/src/lyrics.ts): `home-worker/src/lyrics.ts`

### Backend platform

- [SQLite jobs](https://github.com/fufu-noir/arcod/blob/main/server/src/db/client.ts): `server/src/db/client.ts`
- [Fastify API](https://github.com/fufu-noir/arcod/blob/main/server/src/index.ts): `server/src/index.ts`
- [Admin and security](https://github.com/fufu-noir/arcod/blob/main/server/src/routes/admin.ts): `server/src/routes/admin.ts`
- [Worker API](https://github.com/fufu-noir/arcod/blob/main/server/src/routes/workers.ts): `server/src/routes/workers.ts`

### External services

- **Qobuz service**
- **Supabase auth**
- **AWS Lambda proxy**
- [Cloudflare R2](https://github.com/fufu-noir/arcod/blob/main/server/src/storage/r2.ts): `server/src/storage/r2.ts`

### Other components

- **Music user**
- **Temporary download**

## Connections

- Music user → Search and results: searches or pastes
- Search and results → Catalog API: requests catalog
- Catalog API → Qobuz service: queries catalog
- Qobuz client → Qobuz service: queries
- Search and results → Qobuz client: uses search (evidence: `app/search-view.tsx`)
- Music user → Authentication: signs in (evidence: `components/auth-provider.tsx`)
- Authentication → Supabase auth: authenticates (evidence: `components/auth-provider.tsx`)
- Search and results → Download API: requests download
- Download API → SQLite jobs: creates job
- Fastify API → Download API: registers routes (evidence: `server/src/index.ts`)
- Fastify API → Admin and security: registers routes (evidence: `server/src/index.ts`)
- Fastify API → Worker API: registers routes (evidence: `server/src/index.ts`)
- Fastify API → Job processor: starts processing (evidence: `server/src/index.ts`)
- Fastify API → Job scheduler: starts tasks (evidence: `server/src/index.ts`)
- Job scheduler → SQLite jobs: loads pending jobs (evidence: `server/src/index.ts`)
- Job processor → SQLite jobs: reads job state
- Job processor → Qobuz service: downloads tracks
- Job processor → AWS Lambda proxy: proxies requests
- Job processor → Lyrics metadata: adds lyrics
- Job processor → Cloudflare R2: uploads result
- Home worker → Worker API: claims and updates
- Home worker → Worker processing: processes jobs (evidence: `home-worker/src/index.ts`)
- Worker processing → Qobuz service: downloads tracks
- Worker processing → Cloudflare R2: uploads result
- Download API → Job processor: queues job
- Cloudflare R2 → Temporary download: hosts temporary file
- Music user → Temporary download: receives link
- Download history → Download API: manages downloads (evidence: `app/history/page.tsx`)
- Admin controls → Admin and security: manages jobs
- Admin and security → SQLite jobs: manages routing and blocks
