# koda-dernet/side-step architecture

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

- Interactive diagram: https://gitdiagram.com/koda-dernet/side-step
- Repository: https://github.com/koda-dernet/side-step

## Overview

Side-Step is a standalone ACE-Step audio-model adapter fine-tuning toolkit. Users prepare audio datasets and sidecar metadata, optionally enrich or analyze them, preprocess audio into training tensors, configure and run adapter training, then inspect runs or export compatible adapters. The GUI, CLI/wizard, and TUI are alternate entry points into these capabilities. The graph combines README-documented product stages with sampled call sites; wiring for unsampled subsystems is omitted where it cannot be established.

Main entry points: [`sidestep_engine/core/trainer.py`](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/core/trainer.py) (Adapter trainer), [`sidestep_engine/gui/task_manager.py`](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/gui/task_manager.py) (GUI task manager), [`sidestep_engine/gui/server.py`](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/gui/server.py) (GUI API server), [`train.py`](https://github.com/koda-dernet/side-step/blob/main/train.py) (CLI entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_gui["Desktop GUI"]
  node_api["GUI API server<br/>[server.py]"]
  node_wizard["Interactive wizard<br/>[wizard.py]"]
  node_cli["CLI entry point<br/>[train.py]"]
  node_tui["Terminal interface<br/>[app.py]"]
end

subgraph group_data["Dataset preparation"]
  node_builder["Dataset builder<br/>[dataset_builder.py]"]
  node_enrichment["Sidecar enrichment"]
  node_audioanalysis["Offline audio analysis<br/>[audio_analysis.py]"]
  node_preprocess["Audio preprocessing<br/>[preprocess.py]"]
  node_dataset["Dataset manifest"]
end

subgraph group_training["Analysis and training"]
  node_fisher["Fisher PP++ analysis"]
  node_models["Model loading<br/>[loader.py]"]
  node_trainer["Adapter trainer<br/>[trainer.py]"]
  node_adapter["Trained adapter"]
  node_export["ComfyUI export<br/>[comfyui_export.py]"]
end

subgraph group_operations["Run operations"]
  node_tasks["GUI task manager<br/>[task_manager.py]"]
  node_history["Run history and files<br/>[file_ops.py]"]
  node_telemetry["Training monitor<br/>[training.js]"]
end

node_user(("User"))
node_audio["Audio files"]
node_provider{{"Caption and lyrics providers"}}
node_checkpoint[("Model checkpoints")]

node_user -->|"uses"| node_gui
node_user -->|"uses"| node_wizard
node_user -->|"runs"| node_cli
node_user -->|"uses"| node_tui
node_gui -->|"requests"| node_api
node_api -->|"dispatches tasks"| node_tasks
node_tasks -->|"runs preprocessing"| node_preprocess
node_tasks -->|"spawns training"| node_cli
node_cli -->|"starts training"| node_trainer
node_wizard -->|"exports command"| node_cli
node_audio -->|"provides files"| node_builder
node_builder -->|"writes manifest"| node_dataset
node_audio -->|"provides files"| node_enrichment
node_provider -.->|"supplies metadata"| node_enrichment
node_audio -->|"analyzes"| node_audioanalysis
node_dataset -->|"guides preprocessing"| node_preprocess
node_preprocess -->|"prepares tensors"| node_trainer
node_checkpoint -->|"loads weights"| node_models
node_models -->|"provides model"| node_trainer
node_dataset -->|"supports analysis"| node_fisher
node_fisher -->|"provides rank map"| node_trainer
node_trainer -->|"saves adapter"| node_adapter
node_adapter -->|"converts PEFT adapter"| node_export
node_api -->|"requests run history"| node_history
node_tasks -->|"streams progress"| node_telemetry
node_telemetry -->|"receives updates"| node_api

click node_gui "https://github.com/koda-dernet/side-step/tree/main/frontend/js"
click node_api "https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/gui/server.py"
click node_tasks "https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/gui/task_manager.py"
click node_wizard "https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/ui/wizard.py"
click node_cli "https://github.com/koda-dernet/side-step/blob/main/train.py"
click node_tui "https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/tui/app.py"
click node_builder "https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/data/dataset_builder.py"
click node_enrichment "https://github.com/koda-dernet/side-step/tree/main/sidestep_engine/data"
click node_audioanalysis "https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/analysis/audio_analysis.py"
click node_preprocess "https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/data/preprocess.py"
click node_fisher "https://github.com/koda-dernet/side-step/tree/main/sidestep_engine/analysis/fisher"
click node_models "https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/models/loader.py"
click node_trainer "https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/core/trainer.py"
click node_export "https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/core/comfyui_export.py"
click node_history "https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/gui/file_ops.py"
click node_telemetry "https://github.com/koda-dernet/side-step/blob/main/frontend/js/training.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_gui,node_api,node_wizard,node_cli,node_tui,node_user toneBlue
class node_builder,node_enrichment,node_audioanalysis,node_preprocess,node_dataset,node_checkpoint toneAmber
class node_fisher,node_models,node_trainer,node_adapter,node_export toneMint
class node_tasks,node_history,node_telemetry toneRose
class node_audio,node_provider toneIndigo
```

## Components

### User interfaces

- [Desktop GUI](https://github.com/koda-dernet/side-step/tree/main/frontend/js): `frontend/js`
- [GUI API server](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/gui/server.py): `sidestep_engine/gui/server.py`
- [Interactive wizard](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/ui/wizard.py): `sidestep_engine/ui/wizard.py`
- [CLI entry point](https://github.com/koda-dernet/side-step/blob/main/train.py): `train.py`
- [Terminal interface](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/tui/app.py): `sidestep_engine/tui/app.py`

### Dataset preparation

- [Dataset builder](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/data/dataset_builder.py): `sidestep_engine/data/dataset_builder.py`
- [Sidecar enrichment](https://github.com/koda-dernet/side-step/tree/main/sidestep_engine/data): `sidestep_engine/data`
- [Offline audio analysis](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/analysis/audio_analysis.py): `sidestep_engine/analysis/audio_analysis.py`
- [Audio preprocessing](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/data/preprocess.py): `sidestep_engine/data/preprocess.py`
- **Dataset manifest**

### Analysis and training

- [Fisher PP++ analysis](https://github.com/koda-dernet/side-step/tree/main/sidestep_engine/analysis/fisher): `sidestep_engine/analysis/fisher`
- [Model loading](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/models/loader.py): `sidestep_engine/models/loader.py`
- [Adapter trainer](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/core/trainer.py): `sidestep_engine/core/trainer.py`
- **Trained adapter**
- [ComfyUI export](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/core/comfyui_export.py): `sidestep_engine/core/comfyui_export.py`

### Run operations

- [GUI task manager](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/gui/task_manager.py): `sidestep_engine/gui/task_manager.py`
- [Run history and files](https://github.com/koda-dernet/side-step/blob/main/sidestep_engine/gui/file_ops.py): `sidestep_engine/gui/file_ops.py`
- [Training monitor](https://github.com/koda-dernet/side-step/blob/main/frontend/js/training.js): `frontend/js/training.js`

### Other components

- **User**
- **Audio files**
- **Caption and lyrics providers**
- **Model checkpoints**

## Connections

- User → Desktop GUI: uses
- User → Interactive wizard: uses
- User → CLI entry point: runs
- User → Terminal interface: uses
- Desktop GUI → GUI API server: requests
- GUI API server → GUI task manager: dispatches tasks
- GUI task manager → Audio preprocessing: runs preprocessing
- GUI task manager → CLI entry point: spawns training
- CLI entry point → Adapter trainer: starts training
- Interactive wizard → CLI entry point: exports command
- Audio files → Dataset builder: provides files
- Dataset builder → Dataset manifest: writes manifest
- Audio files → Sidecar enrichment: provides files
- Caption and lyrics providers → Sidecar enrichment: supplies metadata
- Audio files → Offline audio analysis: analyzes
- Dataset manifest → Audio preprocessing: guides preprocessing
- Audio preprocessing → Adapter trainer: prepares tensors
- Model checkpoints → Model loading: loads weights
- Model loading → Adapter trainer: provides model
- Dataset manifest → Fisher PP++ analysis: supports analysis
- Fisher PP++ analysis → Adapter trainer: provides rank map
- Adapter trainer → Trained adapter: saves adapter
- Trained adapter → ComfyUI export: converts PEFT adapter
- GUI API server → Run history and files: requests run history
- GUI task manager → Training monitor: streams progress
- Training monitor → GUI API server: receives updates