# kemoshumai/souon-editor architecture

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

- Interactive diagram: https://gitdiagram.com/kemoshumai/souon-editor
- Repository: https://github.com/kemoshumai/souon-editor

## Overview

1. **Overall shape**
   - This is a **Tauri + React + TypeScript** application with a **Rust backend**.  
   - The product appears to be a **music/chart editor** for audio labeling and sequential note/event editing, rather than a general-purpose web app.

2. **Frontend shell**
   - The UI lives under `src/` and is built with **Vite** and React.
   - `src/main.tsx` and `src/App.tsx` likely bootstrap the app, while `src/global.css` and the `src/components/ui/` set provide the visual system and reusable controls.

3. **Primary workspace layout**
   - `src/SequentialEditor.tsx` is the main editing surface.
   - It is decomposed into tracks and timeline-specific views:
     - `TempoTrack`
     - `MusicTrack`
     - `StemTrack`
     - `ChartTrack`
     - `PlayingBarContainer`
     - `TrackHeader`
   - This suggests a multi-lane timeline editor with synchronized audio, tempo, and note/event layers.

4. **Chart editing domain**
   - The `src/SequentialEditor/ChartTrack/` subtree contains the core chart interaction model:
     - note rendering (`Note/SingleNote.tsx`, `Note/LongNote.tsx`)
     - event overlays (`EventsView/SpeedChangeEventView.tsx`)
     - previewing (`ChartTrackPreview/PreviewCanvas.tsx`)
     - track background and menus
   - The store layer under `src/store/` holds the domain objects for charts, notes, tempo, lanes, temporal position, and speed-change events.

5. **Global state and data model**
   - `src/store/store.ts` is the central state container.
   - Domain stores are split by concern:
     - `project.ts`
     - `chart.ts`
     - `lane.ts`
     - `tempoEvent.ts`
     - `noteEvent.ts`
     - `speedChangeEvent.tsx`
     - `userSettings.ts`
   - This indicates the editor is state-heavy, with shared project state driving all timeline views.

6. **Audio and waveform pipeline**
   - `src/AudioSystem.tsx` and `src/AudioSystem/Stem.tsx` indicate an audio subsystem for playback and stem management.
   - `src/utils/waveformRenderer.ts` suggests waveform generation/rendering is part of the UI.
   - `public/moca/voice/` implies bundled local audio assets or sample voice material.

7. **Project/file operations**
   - `src/SaveSystem.tsx` handles persistence and probably serialization of project/chart data.
   - `src/HeaderController/` contains file and project commands:
     - file menu
     - metadata window
     - settings
     - update check
     - “plus” menu actions like generating a new chart
   - The architecture suggests these are user-facing command entry points into the same underlying project state.

8. **Floating panels and interaction primitives**
   - `src/components/DraggableWindow.tsx` plus the `HeaderController/*` windows show a desktop-style UI with movable dialogs/panels.
   - `src/components/ui/` provides a reusable component toolkit for form controls, drawers, dialogs, sliders, tooltips, toasters, and color mode.

9. **Event and communication layer**
   - `src/eventBus.tsx` indicates an in-app event bus for cross-component coordination.
   - This is likely used for editor actions that need to notify multiple panels without direct parent-child coupling.

10. **Rust/Tauri backend**
   - `src-tauri/src/` contains the native side of the app:
     - `audio_labeling.rs`
     - `export_meta.rs`
     - `language_model.rs`
     - `python_env.rs`
     - `stem.rs`
     - `lib.rs`, `main.rs`
   - This is the boundary where the frontend calls into native commands for heavier work such as audio analysis, metadata export, model-backed operations, Python integration, and stem processing.

11. **Platform and packaging boundaries**
   - `src-tauri/tauri.conf.json`, `capabilities/`, and `icons/` define Tauri app configuration and permissions.
   - `src-tauri/gen/android/` shows an **Android target is generated and maintained**, so the app is not desktop-only.
   - `src-tauri/nsis/installer.nsi` indicates a Windows installer packaging path.

12. **Build and developer tooling**
   - The frontend uses **TypeScript + Vite**.
   - The backend uses **Rust/Cargo**.
   - `bun.lockb` suggests Bun is used for dependency management or scripting on the JS side.
   - `.github/workflows/main.yml` provides CI automation for building/testing/releasing.

13. **Likely runtime flow**
   - User actions start in the React UI.
   - State updates happen in the store and event bus.
   - Timeline widgets render against the shared project/chart state.
   - File/audio/export actions cross the Tauri bridge into Rust for native processing and integration with platform capabilities.

14. **What to diagram**
   - A good architecture diagram should center on:
     - the **React editor UI**
     - the **shared store/event bus**
     - the **audio/chart timeline subsystem**
     - the **Tauri Rust services**
     - the **platform packaging outputs** for desktop and Android
   - The key boundary is the **frontend ↔ native backend** split, with the editor’s state and rendering on one side and processing/export/integration on the other.

Main entry points: [`src-tauri/src/lib.rs`](https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/lib.rs) (Native core), [`src/SequentialEditor.tsx`](https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor.tsx) (Editor), [`src/App.tsx`](https://github.com/kemoshumai/souon-editor/blob/main/src/App.tsx) (Root app), [`src/HeaderController.tsx`](https://github.com/kemoshumai/souon-editor/blob/main/src/HeaderController.tsx) (Header)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_shell(("App shell<br/>react entry<br/>[main.tsx]"))
  node_app_root["Root app<br/>react shell<br/>[App.tsx]"]
  node_editor["Editor<br/>timeline workspace"]
  node_tempo_track["Tempo track<br/>timeline lane<br/>[TempoTrack.tsx]"]
  node_music_track["Music track<br/>timeline lane<br/>[MusicTrack.tsx]"]
  node_stem_track["Stem track<br/>timeline lane<br/>[StemTrack.tsx]"]
  node_chart_track["Chart track<br/>chart editor<br/>[ChartTrack.tsx]"]
  node_playing_bar["Playing bar<br/>playback overlay"]
  node_header["Header<br/>command bar"]
  node_windows["Dialogs<br/>floating panels"]
  node_ui_kit["UI kit<br/>component library"]
  node_audio["Audio system<br/>playback engine<br/>[AudioSystem.tsx]"]
  node_save["Save system<br/>persistence<br/>[SaveSystem.tsx]"]
  node_state[("Stores<br/>domain state<br/>[store.ts]")]
  node_bus(("Event bus<br/>coordination bus<br/>[eventBus.tsx]"))
  node_waveform["Waveform utils<br/>render helper"]
end

subgraph group_backend["Native backend"]
  node_native_entry(("Native entry<br/>tauri core<br/>[main.rs]"))
  node_native_lib["Native core<br/>tauri backend<br/>[lib.rs]"]
  node_audio_labeling["Audio labeling<br/>native command<br/>[audio_labeling.rs]"]
  node_export_meta["Meta export<br/>native command<br/>[export_meta.rs]"]
  node_language_model["Language model<br/>native service<br/>[language_model.rs]"]
  node_python_env["Python env<br/>native integration<br/>[python_env.rs]"]
  node_stem_native["Stem processing<br/>native service<br/>[stem.rs]"]
end

subgraph group_platform["Platform"]
  node_tauri_conf["Tauri config<br/>app config<br/>[tauri.conf.json]"]
  node_android_gen["Android target<br/>generated app"]
  node_installer["Installer<br/>packaging<br/>[installer.nsi]"]
end

node_app_shell -->|"mounts"| node_app_root
node_app_root -->|"opens"| node_editor
node_app_root -->|"hosts"| node_header
node_app_root -->|"wires"| node_audio
node_editor -->|"renders"| node_tempo_track
node_editor -->|"renders"| node_music_track
node_editor -->|"renders"| node_stem_track
node_editor -->|"renders"| node_chart_track
node_editor -->|"overlays"| node_playing_bar
node_chart_track -->|"reads/writes"| node_state
node_tempo_track -->|"reads/writes"| node_state
node_music_track -->|"syncs"| node_audio
node_stem_track -->|"controls"| node_audio
node_header -->|"invokes"| node_save
node_header -->|"opens"| node_windows
node_windows -->|"uses"| node_ui_kit
node_chart_track -->|"publishes"| node_bus
node_header -->|"publishes"| node_bus
node_state -->|"coordinates"| node_bus
node_audio -->|"uses"| node_waveform
node_save -->|"calls"| node_native_lib
node_audio_labeling -->|"exposed by"| node_native_lib
node_export_meta -->|"exposed by"| node_native_lib
node_language_model -->|"exposed by"| node_native_lib
node_python_env -->|"exposed by"| node_native_lib
node_stem_native -->|"exposed by"| node_native_lib
node_native_entry -->|"configured by"| node_tauri_conf
node_tauri_conf -->|"generates"| node_android_gen
node_tauri_conf -->|"packages"| node_installer
node_native_lib -->|"targets"| node_android_gen

click node_app_shell "https://github.com/kemoshumai/souon-editor/blob/main/src/main.tsx"
click node_app_root "https://github.com/kemoshumai/souon-editor/blob/main/src/App.tsx"
click node_editor "https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor.tsx"
click node_tempo_track "https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor/TempoTrack.tsx"
click node_music_track "https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor/MusicTrack.tsx"
click node_stem_track "https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor/StemTrack.tsx"
click node_chart_track "https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor/ChartTrack.tsx"
click node_playing_bar "https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor/PlayingBarContainer.tsx"
click node_header "https://github.com/kemoshumai/souon-editor/blob/main/src/HeaderController.tsx"
click node_windows "https://github.com/kemoshumai/souon-editor/blob/main/src/components/DraggableWindow.tsx"
click node_ui_kit "https://github.com/kemoshumai/souon-editor/tree/main/src/components/ui"
click node_audio "https://github.com/kemoshumai/souon-editor/blob/main/src/AudioSystem.tsx"
click node_save "https://github.com/kemoshumai/souon-editor/blob/main/src/SaveSystem.tsx"
click node_state "https://github.com/kemoshumai/souon-editor/blob/main/src/store/store.ts"
click node_bus "https://github.com/kemoshumai/souon-editor/blob/main/src/eventBus.tsx"
click node_waveform "https://github.com/kemoshumai/souon-editor/blob/main/src/utils/waveformRenderer.ts"
click node_native_entry "https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/main.rs"
click node_native_lib "https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/lib.rs"
click node_audio_labeling "https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/audio_labeling.rs"
click node_export_meta "https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/export_meta.rs"
click node_language_model "https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/language_model.rs"
click node_python_env "https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/python_env.rs"
click node_stem_native "https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/stem.rs"
click node_tauri_conf "https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/tauri.conf.json"
click node_android_gen "https://github.com/kemoshumai/souon-editor/tree/main/src-tauri/gen/android"
click node_installer "https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/nsis/installer.nsi"

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_shell,node_app_root,node_editor,node_tempo_track,node_music_track,node_stem_track,node_chart_track,node_playing_bar,node_header,node_windows,node_ui_kit,node_audio,node_save,node_state,node_bus,node_waveform toneBlue
class node_native_entry,node_native_lib,node_audio_labeling,node_export_meta,node_language_model,node_python_env,node_stem_native toneAmber
class node_tauri_conf,node_android_gen,node_installer toneMint
```

## Components

### Frontend

React/Vite editor UI and shared client-side state

- [App shell](https://github.com/kemoshumai/souon-editor/blob/main/src/main.tsx): react entry · Bootstraps the application UI · `src/main.tsx`
- [Root app](https://github.com/kemoshumai/souon-editor/blob/main/src/App.tsx): react shell · Top-level app composition and routing · `src/App.tsx`
- [Editor](https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor.tsx): timeline workspace · Main sequential chart editing surface · `src/SequentialEditor.tsx`
- [Tempo track](https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor/TempoTrack.tsx): timeline lane · Tempo markers and timing lane · `src/SequentialEditor/TempoTrack.tsx`
- [Music track](https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor/MusicTrack.tsx): timeline lane · Music/audio lane in the editor · `src/SequentialEditor/MusicTrack.tsx`
- [Stem track](https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor/StemTrack.tsx): timeline lane · Stem-aware audio lane · `src/SequentialEditor/StemTrack.tsx`
- [Chart track](https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor/ChartTrack.tsx): chart editor · Note and event editing surface · `src/SequentialEditor/ChartTrack.tsx`
- [Playing bar](https://github.com/kemoshumai/souon-editor/blob/main/src/SequentialEditor/PlayingBarContainer.tsx): playback overlay · Current playback position overlay · `src/SequentialEditor/PlayingBarContainer.tsx`
- [Header](https://github.com/kemoshumai/souon-editor/blob/main/src/HeaderController.tsx): command bar · Project and editor commands · `src/HeaderController.tsx`
- [Dialogs](https://github.com/kemoshumai/souon-editor/blob/main/src/components/DraggableWindow.tsx): floating panels · Draggable editor windows and popovers · `src/components/DraggableWindow.tsx`
- [UI kit](https://github.com/kemoshumai/souon-editor/tree/main/src/components/ui): component library · Reusable controls and overlays · `src/components/ui`
- [Audio system](https://github.com/kemoshumai/souon-editor/blob/main/src/AudioSystem.tsx): playback engine · Playback, stem handling, and waveform rendering · `src/AudioSystem.tsx`
- [Save system](https://github.com/kemoshumai/souon-editor/blob/main/src/SaveSystem.tsx): persistence · Project serialization and file persistence · `src/SaveSystem.tsx`
- [Stores](https://github.com/kemoshumai/souon-editor/blob/main/src/store/store.ts): domain state · Shared chart, project, tempo, lane, and settings state · `src/store/store.ts`
- [Event bus](https://github.com/kemoshumai/souon-editor/blob/main/src/eventBus.tsx): coordination bus · Cross-component editor notifications · `src/eventBus.tsx`
- [Waveform utils](https://github.com/kemoshumai/souon-editor/blob/main/src/utils/waveformRenderer.ts): render helper · Waveform generation and drawing helpers · `src/utils/waveformRenderer.ts`

### Native backend

Rust/Tauri commands and platform integrations

- [Native entry](https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/main.rs): tauri core · Rust application entry and command wiring · `src-tauri/src/main.rs`
- [Native core](https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/lib.rs): tauri backend · Backend command definitions and shared native logic · `src-tauri/src/lib.rs`
- [Audio labeling](https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/audio_labeling.rs): native command · Audio labeling and analysis routines · `src-tauri/src/audio_labeling.rs`
- [Meta export](https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/export_meta.rs): native command · Metadata and export generation · `src-tauri/src/export_meta.rs`
- [Language model](https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/language_model.rs): native service · Model-backed native functionality · `src-tauri/src/language_model.rs`
- [Python env](https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/python_env.rs): native integration · Python environment setup and access · `src-tauri/src/python_env.rs`
- [Stem processing](https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/src/stem.rs): native service · Stem-related native processing · `src-tauri/src/stem.rs`

### Platform

Packaging, permissions, and generated targets

- [Tauri config](https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/tauri.conf.json): app config · Capabilities and app configuration · `src-tauri/tauri.conf.json`
- [Android target](https://github.com/kemoshumai/souon-editor/tree/main/src-tauri/gen/android): generated app · Generated Android project and wrappers · `src-tauri/gen/android`
- [Installer](https://github.com/kemoshumai/souon-editor/blob/main/src-tauri/nsis/installer.nsi): packaging · Windows installer packaging definition · `src-tauri/nsis/installer.nsi`

## Connections

- App shell → Root app: mounts · Entry point mounts the root app
- Root app → Editor: opens · Main application presents the editor workspace
- Root app → Header: hosts · Root app includes top-level commands and header
- Root app → Audio system: wires · Root app wires audio playback into UI
- Editor → Tempo track: renders · Editor composes the tempo lane
- Editor → Music track: renders · Editor composes the music lane
- Editor → Stem track: renders · Editor composes the stem lane
- Editor → Chart track: renders · Editor composes the chart editing lane
- Editor → Playing bar: overlays · Editor shows current playback position
- Chart track → Stores: reads/writes · Chart interactions mutate shared chart state
- Tempo track → Stores: reads/writes · Tempo lane uses shared timing state
- Music track → Audio system: syncs · Music lane stays synchronized with playback
- Stem track → Audio system: controls · Stem lane controls stem playback
- Header → Save system: invokes · Header commands trigger persistence actions
- Header → Dialogs: opens · Header launches dialogs and panels
- Dialogs → UI kit: uses · Floating panels use shared UI primitives
- Chart track → Event bus: publishes · Chart interactions broadcast editor events
- Header → Event bus: publishes · Commands notify the rest of the UI
- Stores → Event bus: coordinates · Shared state and events coordinate editor subsystems
- Audio system → Waveform utils: uses · Audio UI relies on waveform rendering helpers
- Save system → Native core: calls · Persistence bridges to native commands when needed
- Audio labeling → Native core: exposed by · Audio labeling is exposed through the native core
- Meta export → Native core: exposed by · Export routines are exposed through the native core
- Language model → Native core: exposed by · Model integration is exposed through the native core
- Python env → Native core: exposed by · Python integration is exposed through the native core
- Stem processing → Native core: exposed by · Stem processing is exposed through the native core
- Native entry → Tauri config: configured by · Native runtime follows Tauri app configuration
- Tauri config → Android target: generates · Configuration includes generated Android target
- Tauri config → Installer: packages · Configuration includes desktop installer packaging
- Native core → Android target: targets · Native backend is shared with Android packaging
