# 0x0funky/audioghost-ai architecture

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

- Interactive diagram: https://gitdiagram.com/0x0funky/audioghost-ai
- Repository: https://github.com/0x0funky/audioghost-ai

## Overview

AudioGhost is a local-first, text-guided audio/video separation editor. Users upload media, request one or more sound tracks (optionally for selected time ranges), compare takes, adjust the mix, and export audio or video; batch runs reuse a project’s sounds and mix across files. The graph separates the editing UI, API/domain services, worker/inference, and persistent state. Relationships involving unsampled modules are included only where README or source-index references support them; a few UI-to-API and external-service links remain unverified.

Main entry points: [`backend/workers/tasks.py`](https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/tasks.py) (Job lifecycle), [`frontend/src/components/Workspace.tsx`](https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/Workspace.tsx) (Workspace), [`backend/main.py`](https://github.com/0x0funky/audioghost-ai/blob/main/backend/main.py) (HTTP application), [`backend/api/sessions.py`](https://github.com/0x0funky/audioghost-ai/blob/main/backend/api/sessions.py) (Session endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Editing interface"]
  node_workspace["Workspace<br/>[Workspace.tsx]"]
  node_timeline["Timeline editor<br/>[Timeline.tsx]"]
  node_separate_panel["Separation controls<br/>[SeparatePanel.tsx]"]
  node_batch_dialog["Batch workflow<br/>[BatchDialog.tsx]"]
  node_export_dialog["Export controls<br/>[ExportDialog.tsx]"]
  node_waveform["Waveform view<br/>[Waveform.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and workflows"]
  node_api_app["HTTP application<br/>[main.py]"]
  node_session_api["Session endpoints<br/>[sessions.py]"]
  node_legacy_api["Single-run endpoints<br/>[separate.py]"]
  node_batch_api["Batch endpoints<br/>[batches.py]"]
  node_task_api["Task results<br/>[tasks.py]"]
  node_license_api["Model access<br/>[auth.py]"]
end

subgraph group_worker["Separation runtime"]
  node_dispatch["Job dispatch<br/>[dispatch.py]"]
  node_worker_tasks["Job lifecycle<br/>[tasks.py]"]
  node_sam_engine["SAM-Audio inference<br/>[sam_lite.py]"]
  node_audio_io["Media decoding/export<br/>[audio_io.py]"]
  node_model_files["Model weights<br/>[model_files.py]"]
  node_celery["Celery worker app<br/>[celery_app.py]"]
end

subgraph group_state["Projects and state"]
  node_session_store[("Session projects<br/>[sessions.py]")]
  node_batch_logic["Batch orchestration<br/>[batches.py]"]
  node_queue_state[("Queue bookkeeping<br/>[queue_state.py]")]
  node_model_license[("License acceptance<br/>[model_license.py]")]
end

node_user(("User"))
node_model_host[("Model repository")]

node_user -->|"edits and exports"| node_workspace
node_workspace -->|"renders"| node_timeline
node_workspace -->|"renders"| node_separate_panel
node_workspace -->|"renders"| node_batch_dialog
node_workspace -->|"renders"| node_export_dialog
node_timeline -->|"renders"| node_waveform
node_batch_dialog -.->|"submits batch"| node_api_client
node_separate_panel -.->|"submits separation"| node_api_client
node_export_dialog -.->|"requests exports"| node_api_client
node_api_client -.->|"calls API"| node_api_app
node_api_app -->|"registers routes"| node_session_api
node_api_app -->|"registers routes"| node_batch_api
node_api_app -->|"registers routes"| node_legacy_api
node_api_app -->|"registers routes"| node_task_api
node_session_api -->|"reads and updates"| node_session_store
node_session_api -->|"dispatches jobs"| node_dispatch
node_session_api -->|"checks queue"| node_queue_state
node_legacy_api -->|"submits jobs"| node_dispatch
node_legacy_api -->|"tracks jobs"| node_queue_state
node_batch_api -->|"delegates batch"| node_batch_logic
node_batch_api -->|"dispatches jobs"| node_dispatch
node_batch_api -->|"reuses session flow"| node_session_api
node_task_api -->|"reads queue state"| node_queue_state
node_license_api -->|"checks acceptance"| node_model_license
node_license_api -->|"checks weights"| node_model_files
node_dispatch -->|"queues tasks"| node_celery
node_worker_tasks -->|"updates job state"| node_queue_state
node_worker_tasks -->|"updates projects"| node_session_store
node_worker_tasks -->|"runs inference"| node_sam_engine
node_worker_tasks -->|"decodes and writes"| node_audio_io
node_worker_tasks -->|"loads model files"| node_model_files
node_worker_tasks -->|"checks license"| node_model_license
node_sam_engine -->|"loads weights"| node_model_files
node_model_files -.->|"downloads weights"| node_model_host

click node_workspace "https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/Workspace.tsx"
click node_timeline "https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/Timeline.tsx"
click node_separate_panel "https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/SeparatePanel.tsx"
click node_batch_dialog "https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/BatchDialog.tsx"
click node_export_dialog "https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/ExportDialog.tsx"
click node_waveform "https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/Waveform.tsx"
click node_api_client "https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/lib/api.ts"
click node_api_app "https://github.com/0x0funky/audioghost-ai/blob/main/backend/main.py"
click node_session_api "https://github.com/0x0funky/audioghost-ai/blob/main/backend/api/sessions.py"
click node_legacy_api "https://github.com/0x0funky/audioghost-ai/blob/main/backend/api/separate.py"
click node_batch_api "https://github.com/0x0funky/audioghost-ai/blob/main/backend/api/batches.py"
click node_task_api "https://github.com/0x0funky/audioghost-ai/blob/main/backend/api/tasks.py"
click node_license_api "https://github.com/0x0funky/audioghost-ai/blob/main/backend/api/auth.py"
click node_session_store "https://github.com/0x0funky/audioghost-ai/blob/main/backend/sessions.py"
click node_batch_logic "https://github.com/0x0funky/audioghost-ai/blob/main/backend/batches.py"
click node_queue_state "https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/queue_state.py"
click node_model_license "https://github.com/0x0funky/audioghost-ai/blob/main/backend/model_license.py"
click node_dispatch "https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/dispatch.py"
click node_worker_tasks "https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/tasks.py"
click node_sam_engine "https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/sam_lite.py"
click node_audio_io "https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/audio_io.py"
click node_model_files "https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/model_files.py"
click node_celery "https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/celery_app.py"

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_workspace,node_timeline,node_separate_panel,node_batch_dialog,node_export_dialog,node_waveform,node_api_client,node_user toneBlue
class node_api_app,node_session_api,node_legacy_api,node_batch_api,node_task_api,node_license_api,node_model_host toneAmber
class node_dispatch,node_worker_tasks,node_sam_engine,node_audio_io,node_model_files,node_celery toneMint
class node_session_store,node_batch_logic,node_queue_state,node_model_license toneRose
```

## Components

### Editing interface

- [Workspace](https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/Workspace.tsx): `frontend/src/components/Workspace.tsx`
- [Timeline editor](https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/Timeline.tsx): `frontend/src/components/Timeline.tsx`
- [Separation controls](https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/SeparatePanel.tsx): `frontend/src/components/SeparatePanel.tsx`
- [Batch workflow](https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/BatchDialog.tsx): `frontend/src/components/BatchDialog.tsx`
- [Export controls](https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/ExportDialog.tsx): `frontend/src/components/ExportDialog.tsx`
- [Waveform view](https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/components/Waveform.tsx): `frontend/src/components/Waveform.tsx`
- [API client](https://github.com/0x0funky/audioghost-ai/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and workflows

- [HTTP application](https://github.com/0x0funky/audioghost-ai/blob/main/backend/main.py): `backend/main.py`
- [Session endpoints](https://github.com/0x0funky/audioghost-ai/blob/main/backend/api/sessions.py): `backend/api/sessions.py`
- [Single-run endpoints](https://github.com/0x0funky/audioghost-ai/blob/main/backend/api/separate.py): `backend/api/separate.py`
- [Batch endpoints](https://github.com/0x0funky/audioghost-ai/blob/main/backend/api/batches.py): `backend/api/batches.py`
- [Task results](https://github.com/0x0funky/audioghost-ai/blob/main/backend/api/tasks.py): `backend/api/tasks.py`
- [Model access](https://github.com/0x0funky/audioghost-ai/blob/main/backend/api/auth.py): `backend/api/auth.py`

### Separation runtime

- [Job dispatch](https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/dispatch.py): `backend/workers/dispatch.py`
- [Job lifecycle](https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/tasks.py): `backend/workers/tasks.py`
- [SAM-Audio inference](https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/sam_lite.py): `backend/workers/sam_lite.py`
- [Media decoding/export](https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/audio_io.py): `backend/workers/audio_io.py`
- [Model weights](https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/model_files.py): `backend/workers/model_files.py`
- [Celery worker app](https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/celery_app.py): `backend/workers/celery_app.py`

### Projects and state

- [Session projects](https://github.com/0x0funky/audioghost-ai/blob/main/backend/sessions.py): `backend/sessions.py`
- [Batch orchestration](https://github.com/0x0funky/audioghost-ai/blob/main/backend/batches.py): `backend/batches.py`
- [Queue bookkeeping](https://github.com/0x0funky/audioghost-ai/blob/main/backend/workers/queue_state.py): `backend/workers/queue_state.py`
- [License acceptance](https://github.com/0x0funky/audioghost-ai/blob/main/backend/model_license.py): `backend/model_license.py`

### Other components

- **User**
- **Model repository**

## Connections

- User → Workspace: edits and exports
- Workspace → Timeline editor: renders (evidence: `frontend/src/components/Workspace.tsx`)
- Workspace → Separation controls: renders (evidence: `frontend/src/components/Workspace.tsx`)
- Workspace → Batch workflow: renders (evidence: `frontend/src/components/Workspace.tsx`)
- Workspace → Export controls: renders (evidence: `frontend/src/components/Workspace.tsx`)
- Timeline editor → Waveform view: renders (evidence: `frontend/src/components/Timeline.tsx`)
- Batch workflow → API client: submits batch
- Separation controls → API client: submits separation
- Export controls → API client: requests exports
- API client → HTTP application: calls API
- HTTP application → Session endpoints: registers routes (evidence: `backend/main.py`)
- HTTP application → Batch endpoints: registers routes (evidence: `backend/main.py`)
- HTTP application → Single-run endpoints: registers routes (evidence: `backend/main.py`)
- HTTP application → Task results: registers routes (evidence: `backend/main.py`)
- Session endpoints → Session projects: reads and updates (evidence: `backend/api/sessions.py`)
- Session endpoints → Job dispatch: dispatches jobs (evidence: `backend/api/sessions.py`)
- Session endpoints → Queue bookkeeping: checks queue (evidence: `backend/api/sessions.py`)
- Single-run endpoints → Job dispatch: submits jobs (evidence: `backend/api/separate.py`)
- Single-run endpoints → Queue bookkeeping: tracks jobs (evidence: `backend/api/separate.py`)
- Batch endpoints → Batch orchestration: delegates batch (evidence: `backend/api/batches.py`)
- Batch endpoints → Job dispatch: dispatches jobs (evidence: `backend/api/batches.py`)
- Batch endpoints → Session endpoints: reuses session flow (evidence: `backend/api/batches.py`)
- Task results → Queue bookkeeping: reads queue state (evidence: `backend/api/tasks.py`)
- Model access → License acceptance: checks acceptance (evidence: `backend/api/auth.py`)
- Model access → Model weights: checks weights (evidence: `backend/api/auth.py`)
- Job dispatch → Celery worker app: queues tasks (evidence: `backend/workers/dispatch.py`)
- Job lifecycle → Queue bookkeeping: updates job state (evidence: `backend/workers/tasks.py`)
- Job lifecycle → Session projects: updates projects (evidence: `backend/workers/tasks.py`)
- Job lifecycle → SAM-Audio inference: runs inference (evidence: `backend/workers/tasks.py`)
- Job lifecycle → Media decoding/export: decodes and writes (evidence: `backend/workers/tasks.py`)
- Job lifecycle → Model weights: loads model files (evidence: `backend/workers/tasks.py`)
- Job lifecycle → License acceptance: checks license (evidence: `backend/workers/tasks.py`)
- SAM-Audio inference → Model weights: loads weights (evidence: `backend/workers/sam_lite.py`)
- Model weights → Model repository: downloads weights
