# fluo6/chordpilot architecture

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

- Interactive diagram: https://gitdiagram.com/fluo6/chordpilot
- Repository: https://github.com/fluo6/chordpilot

## Overview

ChordPilot turns audio into an editable chord chart, then exports the cleaned result. Users can run that workflow in the Electron desktop app or through the LAN web runtime; both rely on a Python analysis/export backend. The graph preserves documented analysis modes, lyrics, audio processing, editing, session storage, and exports. Some internal wiring is based on the README or SOURCE INDEX references rather than complete excerpts, so uncertain connections are omitted or marked dashed.

Main entry points: [`backend/chordpilot_analysis.py`](https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_analysis.py) (Chart analysis), [`src/renderer/shell.js`](https://github.com/fluo6/chordpilot/blob/main/src/renderer/shell.js) (Chart workspace), [`backend/chordpilot_common.py`](https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_common.py) (Analysis utilities), [`src/web/app.js`](https://github.com/fluo6/chordpilot/blob/main/src/web/app.js) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_electron["Electron host<br/>[main.js]"]
  node_renderer["Chart workspace<br/>[shell.js]"]
  node_chart_edit["Chart editing<br/>[bars.js]"]
  node_timeline["Audio timeline<br/>[timeline.js]"]
  node_transpose["Transpose controls<br/>[transpose.js]"]
  node_stems_ui["Stem controls<br/>[stems.js]"]
  node_desktop_bridge["Web session bridge<br/>[web-bridge.js]"]
  node_web_dialog["Session dialog"]
end

subgraph group_web["LAN web runtime"]
  node_web_server["HTTP server<br/>[server.js]"]
  node_web_app["API routes<br/>[app.js]"]
  node_queue["Serial work queue<br/>[work-queue.js]"]
  node_storage[("Sessions and media<br/>[storage.js]")]
end

subgraph group_analysis["Audio analysis"]
  node_analysis["Chart analysis"]
  node_audio["Audio decoding"]
  node_chords["Chord estimation"]
  node_lyrics["Lyrics reference"]
  node_stems["Stem separation"]
end

subgraph group_backend["Backend services"]
  node_cache[("Analysis cache")]
  node_common["Analysis utilities"]
  node_cli["Backend commands<br/>[chordpilot_cli.py]"]
  node_export["Chart export"]
end

subgraph group_shared["Shared runtime"]
  node_services["Audio and process services"]
  node_build_info["Build metadata<br/>[build-info.js]"]
end

node_user(("Desktop user"))
node_browser(("LAN browser user"))
node_python["Python runtime"]
node_demucs["Demucs model"]

node_user -->|"opens app"| node_electron
node_electron -.->|"presents workflow"| node_renderer
node_user -->|"edits chart"| node_renderer
node_renderer -->|"edits bars"| node_chart_edit
node_renderer -->|"previews audio"| node_timeline
node_renderer -->|"changes key"| node_transpose
node_renderer -->|"selects stem mode"| node_stems_ui
node_renderer -.->|"connects sessions"| node_desktop_bridge
node_desktop_bridge -.->|"opens session dialog"| node_web_dialog
node_electron -->|"creates services"| node_services
node_services -->|"runs backend"| node_python
node_python -->|"runs commands"| node_cli
node_cli -->|"dispatches analysis"| node_analysis
node_cli -->|"dispatches export"| node_export
node_analysis -->|"loads audio"| node_audio
node_analysis -->|"estimates chords"| node_chords
node_analysis -->|"reads and writes"| node_cache
node_analysis -->|"generates lyrics"| node_lyrics
node_analysis -->|"separates stems"| node_stems
node_stems -->|"runs separation"| node_demucs
node_analysis -->|"uses utilities"| node_common
node_chords -->|"uses utilities"| node_common
node_audio -->|"uses utilities"| node_common
node_cache -->|"uses utilities"| node_common
node_stems -->|"loads audio"| node_audio
node_stems -->|"uses stem cache"| node_cache
node_lyrics -->|"uses utilities"| node_common
node_export -->|"uses utilities"| node_common
node_browser -->|"opens workflow"| node_web_server
node_web_server -->|"creates API"| node_web_app
node_web_server -->|"initializes storage"| node_storage
node_web_server -->|"creates queue"| node_queue
node_web_app -->|"stores sessions and media"| node_storage
node_web_app -->|"enqueues work"| node_queue
node_web_app -->|"processes audio"| node_services
node_web_app -->|"serves version"| node_build_info

click node_electron "https://github.com/fluo6/chordpilot/blob/main/src/main/main.js"
click node_renderer "https://github.com/fluo6/chordpilot/blob/main/src/renderer/shell.js"
click node_chart_edit "https://github.com/fluo6/chordpilot/blob/main/src/renderer/bars.js"
click node_timeline "https://github.com/fluo6/chordpilot/blob/main/src/renderer/timeline.js"
click node_transpose "https://github.com/fluo6/chordpilot/blob/main/src/renderer/transpose.js"
click node_stems_ui "https://github.com/fluo6/chordpilot/blob/main/src/renderer/stems.js"
click node_desktop_bridge "https://github.com/fluo6/chordpilot/blob/main/src/renderer/web-bridge.js"
click node_web_dialog "https://github.com/fluo6/chordpilot/blob/main/src/renderer/web-session-dialog.js"
click node_web_server "https://github.com/fluo6/chordpilot/blob/main/src/web/server.js"
click node_web_app "https://github.com/fluo6/chordpilot/blob/main/src/web/app.js"
click node_queue "https://github.com/fluo6/chordpilot/blob/main/src/web/work-queue.js"
click node_storage "https://github.com/fluo6/chordpilot/blob/main/src/web/storage.js"
click node_analysis "https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_analysis.py"
click node_audio "https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_audio.py"
click node_chords "https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_chords.py"
click node_lyrics "https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_lyrics.py"
click node_stems "https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_stems.py"
click node_cache "https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_cache.py"
click node_common "https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_common.py"
click node_cli "https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_cli.py"
click node_export "https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_export.py"
click node_services "https://github.com/fluo6/chordpilot/blob/main/src/runtime/chordpilot-services.js"
click node_build_info "https://github.com/fluo6/chordpilot/blob/main/src/runtime/build-info.js"

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_electron,node_renderer,node_chart_edit,node_timeline,node_transpose,node_stems_ui,node_desktop_bridge,node_web_dialog,node_user,node_browser toneBlue
class node_web_server,node_web_app,node_queue,node_storage toneAmber
class node_analysis,node_audio,node_chords,node_lyrics,node_stems toneMint
class node_cache,node_common,node_cli,node_export toneRose
class node_services,node_build_info,node_python,node_demucs toneIndigo
```

## Components

### Desktop experience

- [Electron host](https://github.com/fluo6/chordpilot/blob/main/src/main/main.js): `src/main/main.js`
- [Chart workspace](https://github.com/fluo6/chordpilot/blob/main/src/renderer/shell.js): `src/renderer/shell.js`
- [Chart editing](https://github.com/fluo6/chordpilot/blob/main/src/renderer/bars.js): `src/renderer/bars.js`
- [Audio timeline](https://github.com/fluo6/chordpilot/blob/main/src/renderer/timeline.js): `src/renderer/timeline.js`
- [Transpose controls](https://github.com/fluo6/chordpilot/blob/main/src/renderer/transpose.js): `src/renderer/transpose.js`
- [Stem controls](https://github.com/fluo6/chordpilot/blob/main/src/renderer/stems.js): `src/renderer/stems.js`
- [Web session bridge](https://github.com/fluo6/chordpilot/blob/main/src/renderer/web-bridge.js): `src/renderer/web-bridge.js`
- [Session dialog](https://github.com/fluo6/chordpilot/blob/main/src/renderer/web-session-dialog.js): `src/renderer/web-session-dialog.js`

### LAN web runtime

- [HTTP server](https://github.com/fluo6/chordpilot/blob/main/src/web/server.js): `src/web/server.js`
- [API routes](https://github.com/fluo6/chordpilot/blob/main/src/web/app.js): `src/web/app.js`
- [Serial work queue](https://github.com/fluo6/chordpilot/blob/main/src/web/work-queue.js): `src/web/work-queue.js`
- [Sessions and media](https://github.com/fluo6/chordpilot/blob/main/src/web/storage.js): `src/web/storage.js`

### Audio analysis

- [Chart analysis](https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_analysis.py): `backend/chordpilot_analysis.py`
- [Audio decoding](https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_audio.py): `backend/chordpilot_audio.py`
- [Chord estimation](https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_chords.py): `backend/chordpilot_chords.py`
- [Lyrics reference](https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_lyrics.py): `backend/chordpilot_lyrics.py`
- [Stem separation](https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_stems.py): `backend/chordpilot_stems.py`

### Backend services

- [Analysis cache](https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_cache.py): `backend/chordpilot_cache.py`
- [Analysis utilities](https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_common.py): `backend/chordpilot_common.py`
- [Backend commands](https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_cli.py): `backend/chordpilot_cli.py`
- [Chart export](https://github.com/fluo6/chordpilot/blob/main/backend/chordpilot_export.py): `backend/chordpilot_export.py`

### Shared runtime

- [Audio and process services](https://github.com/fluo6/chordpilot/blob/main/src/runtime/chordpilot-services.js): `src/runtime/chordpilot-services.js`
- [Build metadata](https://github.com/fluo6/chordpilot/blob/main/src/runtime/build-info.js): `src/runtime/build-info.js`

### Other components

- **Desktop user**
- **LAN browser user**
- **Python runtime**
- **Demucs model**

## Connections

- Desktop user → Electron host: opens app (evidence: `README.md`)
- Electron host → Chart workspace: presents workflow
- Desktop user → Chart workspace: edits chart (evidence: `README.md`)
- Chart workspace → Chart editing: edits bars (evidence: `README.md`)
- Chart workspace → Audio timeline: previews audio (evidence: `README.md`)
- Chart workspace → Transpose controls: changes key (evidence: `README.md`)
- Chart workspace → Stem controls: selects stem mode (evidence: `README.md`)
- Chart workspace → Web session bridge: connects sessions
- Web session bridge → Session dialog: opens session dialog
- Electron host → Audio and process services: creates services (evidence: `src/main/main.js`)
- Audio and process services → Python runtime: runs backend (evidence: `README.md`)
- Python runtime → Backend commands: runs commands (evidence: `README.md`)
- Backend commands → Chart analysis: dispatches analysis (evidence: `backend/chordpilot_cli.py`)
- Backend commands → Chart export: dispatches export (evidence: `backend/chordpilot_cli.py`)
- Chart analysis → Audio decoding: loads audio (evidence: `backend/chordpilot_analysis.py`)
- Chart analysis → Chord estimation: estimates chords (evidence: `backend/chordpilot_analysis.py`)
- Chart analysis → Analysis cache: reads and writes (evidence: `backend/chordpilot_analysis.py`)
- Chart analysis → Lyrics reference: generates lyrics (evidence: `backend/chordpilot_analysis.py`)
- Chart analysis → Stem separation: separates stems (evidence: `backend/chordpilot_analysis.py`)
- Stem separation → Demucs model: runs separation (evidence: `README.md`)
- Chart analysis → Analysis utilities: uses utilities (evidence: `backend/chordpilot_analysis.py`)
- Chord estimation → Analysis utilities: uses utilities (evidence: `backend/chordpilot_chords.py`)
- Audio decoding → Analysis utilities: uses utilities (evidence: `backend/chordpilot_audio.py`)
- Analysis cache → Analysis utilities: uses utilities (evidence: `backend/chordpilot_cache.py`)
- Stem separation → Audio decoding: loads audio (evidence: `backend/chordpilot_stems.py`)
- Stem separation → Analysis cache: uses stem cache (evidence: `backend/chordpilot_stems.py`)
- Lyrics reference → Analysis utilities: uses utilities (evidence: `backend/chordpilot_lyrics.py`)
- Chart export → Analysis utilities: uses utilities (evidence: `backend/chordpilot_export.py`)
- LAN browser user → HTTP server: opens workflow (evidence: `README.md`)
- HTTP server → API routes: creates API (evidence: `src/web/server.js`)
- HTTP server → Sessions and media: initializes storage (evidence: `src/web/server.js`)
- HTTP server → Serial work queue: creates queue (evidence: `src/web/server.js`)
- API routes → Sessions and media: stores sessions and media (evidence: `src/web/app.js`)
- API routes → Serial work queue: enqueues work (evidence: `src/web/app.js`)
- API routes → Audio and process services: processes audio (evidence: `src/web/app.js`)
- API routes → Build metadata: serves version (evidence: `src/web/app.js`)
