# danoo-c/3d-immersive architecture

> Architecture diagram of the GitHub repository danoo-c/3d-immersive, 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/danoo-c/3d-immersive
- Repository: https://github.com/danoo-c/3d-immersive

## Overview

Immersive is an early-stage desktop 3D sound-creation application. Its intended workflow is to import audio, arrange clips on timeline channels, position and animate sources, then produce binaural stereo; today, project editing, media browsing, audition, and themes work, while spatial playback and rendering are not yet integrated. The graph distinguishes the documented product stages from sampled implementation links; dashed, uncited links mark planned or unverified relationships rather than confirmed calls.

Main entry points: [`src/immersive/ui/main_window.py`](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/main_window.py) (Main window), [`src/immersive/core/document.py`](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/document.py) (Open project), [`src/immersive/ui/explorer/media_pool.py`](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/explorer/media_pool.py) (Media pool), [`src/immersive/audio/engine.py`](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/audio/engine.py) (Audio engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["Application and UI"]
  node_app["App startup<br/>[app.py]"]
  node_window["Main window<br/>[main_window.py]"]
  node_timeline["Timeline<br/>[view.py]"]
  node_parameters["Parameter views<br/>[views.py]"]
  node_theme["Theme system<br/>[theme.py]"]
  node_spatial_ui["Spatial workspace"]
end

subgraph group_project["Project editing"]
  node_document["Open project<br/>[document.py]"]
  node_model["Project model<br/>[model.py]"]
  node_edits["Edits and undo<br/>[edits.py]"]
  node_project_io["Project files<br/>[project_io.py]"]
  node_time["Time and snapping<br/>[time.py]"]
end

subgraph group_media["Media and assets"]
  node_media_pool["Media pool<br/>[media_pool.py]"]
  node_media_decode["Audio import<br/>[media.py]"]
  node_media_store[("Media store<br/>[media_store.py]")]
  node_peaks["Waveform peaks<br/>[peaks.py]"]
end

subgraph group_audio["Audio processing"]
  node_player["Audition player<br/>[player.py]"]
  node_engine["Audio engine<br/>[engine.py]"]
  node_scheduler["Playback scheduler<br/>[scheduler.py]"]
  node_spatial["Spatial processing<br/>[spatial.py]"]
  node_hrtf["HRTF bank<br/>[bank.py]"]
  node_render["Binaural render"]
end

node_user(("Producer"))
node_wav["Stereo WAV"]

node_user -->|"launches"| node_app
node_app -->|"shows"| node_window
node_app -->|"applies"| node_theme
node_user -.->|"composes in"| node_window
node_window -->|"edits project"| node_document
node_window -->|"hosts"| node_timeline
node_window -->|"hosts"| node_media_pool
node_window -->|"hosts"| node_parameters
node_window -->|"uses"| node_player
node_window -->|"prepares"| node_hrtf
node_window -.->|"provides"| node_spatial_ui
node_document -->|"holds"| node_model
node_document -->|"loads and saves"| node_project_io
node_document -->|"tracks commands"| node_edits
node_timeline -->|"dispatches edits"| node_edits
node_timeline -->|"uses grid"| node_time
node_parameters -->|"commits changes"| node_document
node_media_pool -->|"reads project"| node_document
node_media_pool -->|"reads assets"| node_media_store
node_media_pool -->|"shows waveforms"| node_peaks
node_user -.->|"imports audio"| node_media_pool
node_media_decode -->|"creates media entries"| node_model
node_window -->|"imports files"| node_media_decode
node_window -->|"manages assets"| node_media_store
node_engine -->|"uses scheduling"| node_scheduler
node_engine -->|"processes sources"| node_spatial
node_spatial -->|"uses filters"| node_hrtf
node_hrtf -->|"loads dataset audio"| node_media_decode
node_player -.->|"feeds playback"| node_engine
node_user -.->|"positions sources"| node_spatial_ui
node_spatial_ui -.->|"edits positions"| node_model
node_user -.->|"requests render"| node_render
node_render -.->|"renders offline"| node_engine
node_render -.->|"writes stereo"| node_wav

click node_app "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/app.py"
click node_window "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/main_window.py"
click node_timeline "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/timeline/view.py"
click node_parameters "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/parameters/views.py"
click node_theme "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/theme.py"
click node_spatial_ui "https://github.com/danoo-c/3d-immersive/tree/main/src/immersive/ui/spatial"
click node_document "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/document.py"
click node_model "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/model.py"
click node_edits "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/edits.py"
click node_project_io "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/io/project_io.py"
click node_time "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/time.py"
click node_media_pool "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/explorer/media_pool.py"
click node_media_decode "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/io/media.py"
click node_media_store "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/media_store.py"
click node_peaks "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/io/peaks.py"
click node_player "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/audio/player.py"
click node_engine "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/audio/engine.py"
click node_scheduler "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/audio/scheduler.py"
click node_spatial "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/audio/spatial.py"
click node_hrtf "https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/audio/hrtf/bank.py"
click node_render "https://github.com/danoo-c/3d-immersive/tree/main/src/immersive/audio"

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_app,node_window,node_timeline,node_parameters,node_theme,node_spatial_ui toneBlue
class node_document,node_model,node_edits,node_project_io,node_time toneAmber
class node_media_pool,node_media_decode,node_media_store,node_peaks toneMint
class node_player,node_engine,node_scheduler,node_spatial,node_hrtf,node_render toneRose
class node_user,node_wav toneIndigo
```

## Components

### Application and UI

- [App startup](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/app.py): `src/immersive/app.py`
- [Main window](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/main_window.py): `src/immersive/ui/main_window.py`
- [Timeline](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/timeline/view.py): `src/immersive/ui/timeline/view.py`
- [Parameter views](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/parameters/views.py): `src/immersive/ui/parameters/views.py`
- [Theme system](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/theme.py): `src/immersive/ui/theme.py`
- [Spatial workspace](https://github.com/danoo-c/3d-immersive/tree/main/src/immersive/ui/spatial): `src/immersive/ui/spatial`

### Project editing

- [Open project](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/document.py): `src/immersive/core/document.py`
- [Project model](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/model.py): `src/immersive/core/model.py`
- [Edits and undo](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/edits.py): `src/immersive/core/edits.py`
- [Project files](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/io/project_io.py): `src/immersive/core/io/project_io.py`
- [Time and snapping](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/time.py): `src/immersive/core/time.py`

### Media and assets

- [Media pool](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/ui/explorer/media_pool.py): `src/immersive/ui/explorer/media_pool.py`
- [Audio import](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/io/media.py): `src/immersive/core/io/media.py`
- [Media store](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/media_store.py): `src/immersive/core/media_store.py`
- [Waveform peaks](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/core/io/peaks.py): `src/immersive/core/io/peaks.py`

### Audio processing

- [Audition player](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/audio/player.py): `src/immersive/audio/player.py`
- [Audio engine](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/audio/engine.py): `src/immersive/audio/engine.py`
- [Playback scheduler](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/audio/scheduler.py): `src/immersive/audio/scheduler.py`
- [Spatial processing](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/audio/spatial.py): `src/immersive/audio/spatial.py`
- [HRTF bank](https://github.com/danoo-c/3d-immersive/blob/main/src/immersive/audio/hrtf/bank.py): `src/immersive/audio/hrtf/bank.py`
- [Binaural render](https://github.com/danoo-c/3d-immersive/tree/main/src/immersive/audio): `src/immersive/audio`

### Other components

- **Producer**
- **Stereo WAV**

## Connections

- Producer → App startup: launches (evidence: `src/immersive/app.py`)
- App startup → Main window: shows (evidence: `src/immersive/app.py`)
- App startup → Theme system: applies (evidence: `src/immersive/app.py`)
- Producer → Main window: composes in (evidence: `README.md`)
- Main window → Open project: edits project (evidence: `src/immersive/ui/main_window.py`)
- Main window → Timeline: hosts (evidence: `src/immersive/ui/main_window.py`)
- Main window → Media pool: hosts (evidence: `src/immersive/ui/main_window.py`)
- Main window → Parameter views: hosts (evidence: `src/immersive/ui/main_window.py`)
- Main window → Audition player: uses (evidence: `src/immersive/ui/main_window.py`)
- Main window → HRTF bank: prepares (evidence: `src/immersive/ui/main_window.py`)
- Main window → Spatial workspace: provides (evidence: `README.md`)
- Open project → Project model: holds (evidence: `src/immersive/core/document.py`)
- Open project → Project files: loads and saves (evidence: `src/immersive/core/document.py`)
- Open project → Edits and undo: tracks commands (evidence: `src/immersive/core/document.py`)
- Timeline → Edits and undo: dispatches edits (evidence: `src/immersive/ui/timeline/view.py`)
- Timeline → Time and snapping: uses grid
- Parameter views → Open project: commits changes (evidence: `src/immersive/ui/parameters/views.py`)
- Media pool → Open project: reads project (evidence: `src/immersive/ui/explorer/media_pool.py`)
- Media pool → Media store: reads assets (evidence: `src/immersive/ui/explorer/media_pool.py`)
- Media pool → Waveform peaks: shows waveforms (evidence: `src/immersive/ui/explorer/media_pool.py`)
- Producer → Media pool: imports audio (evidence: `README.md`)
- Audio import → Project model: creates media entries (evidence: `src/immersive/core/io/media.py`)
- Main window → Audio import: imports files (evidence: `src/immersive/ui/main_window.py`)
- Main window → Media store: manages assets (evidence: `src/immersive/ui/main_window.py`)
- Audio engine → Playback scheduler: uses scheduling (evidence: `src/immersive/audio/engine.py`)
- Audio engine → Spatial processing: processes sources (evidence: `src/immersive/audio/engine.py`)
- Spatial processing → HRTF bank: uses filters (evidence: `src/immersive/audio/spatial.py`)
- HRTF bank → Audio import: loads dataset audio (evidence: `src/immersive/audio/hrtf/bank.py`)
- Audition player → Audio engine: feeds playback
- Producer → Spatial workspace: positions sources (evidence: `README.md`)
- Spatial workspace → Project model: edits positions (evidence: `README.md`)
- Producer → Binaural render: requests render (evidence: `README.md`)
- Binaural render → Audio engine: renders offline (evidence: `src/immersive/audio/engine.py`)
- Binaural render → Stereo WAV: writes stereo (evidence: `README.md`)