# mnm967/qamba-studio-oss architecture

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

- Interactive diagram: https://gitdiagram.com/mnm967/qamba-studio-oss
- Repository: https://github.com/mnm967/qamba-studio-oss

## Overview

Qamba Studio is a local-first desktop studio for planning, generating, and editing AI video. The main workflow moves from a user’s story brief through staged planning and story-bible references into queued renders, then into timeline editing and final assembly. The README documents the local project-file/PostgREST bridge and the Python job pipeline; the tree identifies the major UI and runtime modules. Some subsystem links are documented rather than verified from sampled implementation, so uncertain internal calls are omitted.

Main entry points: [`src/routes/Workspace.tsx`](https://github.com/mnm967/qamba-studio-oss/blob/main/src/routes/Workspace.tsx) (Workspace UI), [`src/components/timeline/Timeline.tsx`](https://github.com/mnm967/qamba-studio-oss/blob/main/src/components/timeline/Timeline.tsx) (Timeline editor), [`worker/handlers`](https://github.com/mnm967/qamba-studio-oss/tree/main/worker/handlers) (Job handlers), [`worker/planner.py`](https://github.com/mnm967/qamba-studio-oss/blob/main/worker/planner.py) (Story planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Studio experience"]
  node_workspace["Workspace UI<br/>[Workspace.tsx]"]
  node_storyboard["Storyboard view<br/>[StoryboardView.tsx]"]
  node_timeline["Timeline editor<br/>[Timeline.tsx]"]
  node_director_chat["Director chat<br/>[ChatPage.tsx]"]
end

subgraph group_story["Story development"]
  node_planning["Story planning<br/>[planner.py]"]
  node_story_bible["Story bible<br/>[lore.ts]"]
  node_director_tools["Director tools<br/>[director_tools.py]"]
end

subgraph group_generation["Generation pipeline"]
  node_job_handlers["Job handlers"]
  node_voice_engines["Speech engines<br/>[voice_engines.py]"]
end

subgraph group_runtime["Local runtime"]
  node_project_store[("Project file store<br/>[localStore.ts]")]
  node_query_refresh["Live query refresh<br/>[useLiveQuery.ts]"]
  node_job_queue["Generation queue<br/>[jobs.ts]"]
  node_local_bridge["PostgREST bridge<br/>[localRest.ts]"]
  node_native_shell["Desktop shell<br/>[lib.rs]"]
  node_engine_manager["Local engine manager<br/>[engine.rs]"]
end

subgraph group_editing["Editing and output"]
  node_timeline_data["Timeline data<br/>[timeline.ts]"]
  node_assembly["Take assembly<br/>[assembly.ts]"]
  node_post_chain["Finishing chain<br/>[postChain.ts]"]
end

node_user(("Creator"))
node_comfy["ComfyUI"]
node_model_providers["Model providers"]
node_media_output["Rendered media"]
node_ffmpeg["ffmpeg"]

node_user -->|"creates project"| node_workspace
node_workspace -->|"opens storyboard"| node_storyboard
node_workspace -->|"opens timeline"| node_timeline
node_workspace -->|"opens chat"| node_director_chat
node_workspace -->|"reads and writes"| node_project_store
node_project_store -->|"invalidates tables"| node_query_refresh
node_storyboard -->|"queues work"| node_job_queue
node_director_chat -->|"invokes project tools"| node_director_tools
node_director_tools -->|"changes project"| node_project_store
node_job_queue -->|"serves project data"| node_local_bridge
node_local_bridge -->|"provides PostgREST"| node_planning
node_local_bridge -->|"provides PostgREST"| node_job_handlers
node_planning -->|"uses references"| node_story_bible
node_planning -->|"records jobs"| node_job_queue
node_job_handlers -->|"selects local voice"| node_voice_engines
node_job_handlers -->|"submits local renders"| node_comfy
node_job_handlers -.->|"requests hosted models"| node_model_providers
node_workspace -->|"calls desktop bridge"| node_native_shell
node_native_shell -->|"manages engine"| node_engine_manager
node_engine_manager -->|"starts and checks"| node_comfy
node_timeline -->|"reads and edits"| node_timeline_data
node_timeline -->|"assembles takes"| node_assembly
node_timeline -->|"configures finishing"| node_post_chain
node_assembly -->|"renders assembly"| node_ffmpeg
node_post_chain -->|"applies effects"| node_ffmpeg
node_ffmpeg -->|"writes media"| node_media_output

click node_workspace "https://github.com/mnm967/qamba-studio-oss/blob/main/src/routes/Workspace.tsx"
click node_storyboard "https://github.com/mnm967/qamba-studio-oss/blob/main/src/components/shell/StoryboardView.tsx"
click node_timeline "https://github.com/mnm967/qamba-studio-oss/blob/main/src/components/timeline/Timeline.tsx"
click node_director_chat "https://github.com/mnm967/qamba-studio-oss/blob/main/src/routes/ChatPage.tsx"
click node_project_store "https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/localStore.ts"
click node_query_refresh "https://github.com/mnm967/qamba-studio-oss/blob/main/src/hooks/useLiveQuery.ts"
click node_job_queue "https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/db/jobs.ts"
click node_local_bridge "https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/localRest.ts"
click node_native_shell "https://github.com/mnm967/qamba-studio-oss/blob/main/src-tauri/src/lib.rs"
click node_engine_manager "https://github.com/mnm967/qamba-studio-oss/blob/main/src-tauri/src/engine.rs"
click node_planning "https://github.com/mnm967/qamba-studio-oss/blob/main/worker/planner.py"
click node_story_bible "https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/db/lore.ts"
click node_director_tools "https://github.com/mnm967/qamba-studio-oss/blob/main/worker/director_tools.py"
click node_job_handlers "https://github.com/mnm967/qamba-studio-oss/tree/main/worker/handlers"
click node_voice_engines "https://github.com/mnm967/qamba-studio-oss/blob/main/worker/voice_engines.py"
click node_timeline_data "https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/db/timeline.ts"
click node_assembly "https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/assembly.ts"
click node_post_chain "https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/postChain.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_workspace,node_storyboard,node_timeline,node_director_chat,node_comfy toneBlue
class node_planning,node_story_bible,node_director_tools toneAmber
class node_job_handlers,node_voice_engines toneMint
class node_project_store,node_query_refresh,node_job_queue,node_local_bridge,node_native_shell,node_engine_manager toneRose
class node_timeline_data,node_assembly,node_post_chain,node_user,node_model_providers,node_media_output,node_ffmpeg toneIndigo
```

## Components

### Studio experience

- [Workspace UI](https://github.com/mnm967/qamba-studio-oss/blob/main/src/routes/Workspace.tsx): `src/routes/Workspace.tsx`
- [Storyboard view](https://github.com/mnm967/qamba-studio-oss/blob/main/src/components/shell/StoryboardView.tsx): `src/components/shell/StoryboardView.tsx`
- [Timeline editor](https://github.com/mnm967/qamba-studio-oss/blob/main/src/components/timeline/Timeline.tsx): `src/components/timeline/Timeline.tsx`
- [Director chat](https://github.com/mnm967/qamba-studio-oss/blob/main/src/routes/ChatPage.tsx): `src/routes/ChatPage.tsx`

### Story development

- [Story planning](https://github.com/mnm967/qamba-studio-oss/blob/main/worker/planner.py): `worker/planner.py`
- [Story bible](https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/db/lore.ts): `src/lib/db/lore.ts`
- [Director tools](https://github.com/mnm967/qamba-studio-oss/blob/main/worker/director_tools.py): `worker/director_tools.py`

### Generation pipeline

- [Job handlers](https://github.com/mnm967/qamba-studio-oss/tree/main/worker/handlers): `worker/handlers`
- [Speech engines](https://github.com/mnm967/qamba-studio-oss/blob/main/worker/voice_engines.py): `worker/voice_engines.py`

### Local runtime

- [Project file store](https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/localStore.ts): `src/lib/localStore.ts`
- [Live query refresh](https://github.com/mnm967/qamba-studio-oss/blob/main/src/hooks/useLiveQuery.ts): `src/hooks/useLiveQuery.ts`
- [Generation queue](https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/db/jobs.ts): `src/lib/db/jobs.ts`
- [PostgREST bridge](https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/localRest.ts): `src/lib/localRest.ts`
- [Desktop shell](https://github.com/mnm967/qamba-studio-oss/blob/main/src-tauri/src/lib.rs): `src-tauri/src/lib.rs`
- [Local engine manager](https://github.com/mnm967/qamba-studio-oss/blob/main/src-tauri/src/engine.rs): `src-tauri/src/engine.rs`

### Editing and output

- [Timeline data](https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/db/timeline.ts): `src/lib/db/timeline.ts`
- [Take assembly](https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/assembly.ts): `src/lib/assembly.ts`
- [Finishing chain](https://github.com/mnm967/qamba-studio-oss/blob/main/src/lib/postChain.ts): `src/lib/postChain.ts`

### Other components

- **Creator**
- **ComfyUI**
- **Model providers**
- **Rendered media**
- **ffmpeg**

## Connections

- Creator → Workspace UI: creates project
- Workspace UI → Storyboard view: opens storyboard
- Workspace UI → Timeline editor: opens timeline
- Workspace UI → Director chat: opens chat
- Workspace UI → Project file store: reads and writes
- Project file store → Live query refresh: invalidates tables
- Storyboard view → Generation queue: queues work
- Director chat → Director tools: invokes project tools
- Director tools → Project file store: changes project
- Generation queue → PostgREST bridge: serves project data
- PostgREST bridge → Story planning: provides PostgREST
- PostgREST bridge → Job handlers: provides PostgREST
- Story planning → Story bible: uses references
- Story planning → Generation queue: records jobs
- Job handlers → Speech engines: selects local voice
- Job handlers → ComfyUI: submits local renders
- Job handlers → Model providers: requests hosted models
- Workspace UI → Desktop shell: calls desktop bridge
- Desktop shell → Local engine manager: manages engine
- Local engine manager → ComfyUI: starts and checks
- Timeline editor → Timeline data: reads and edits
- Timeline editor → Take assembly: assembles takes
- Timeline editor → Finishing chain: configures finishing
- Take assembly → ffmpeg: renders assembly
- Finishing chain → ffmpeg: applies effects
- ffmpeg → Rendered media: writes media