# za-warka/itmoloops architecture

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

- Interactive diagram: https://gitdiagram.com/za-warka/itmoloops
- Repository: https://github.com/za-warka/itmoloops

## Overview

#### Purpose and Executables
ITMO Loops is a cross-platform C++ DSL renderer: it converts a textual music score into 44.1 kHz, 16-bit WAV audio. CMake defines the build, while CLI entry points are in `bin/main.cpp` and `bin/nmain.cpp`; executable wiring is in `bin/CMakeLists.txt`.

#### Compilation-to-Audio Pipeline
The main control flow is source file → preprocessing → tokenization/parsing → score model → audio generation → WAV export. The parser produces a time-oriented composition model rather than directly emitting samples, separating DSL interpretation from rendering. Key stages are `src/preprocessor/preprocessor.cpp`, `src/lexer/lexer.cpp`, and `src/parser/parser.cpp`.

#### Source Preparation and DSL Front End
Preprocessing handles source-file-level transformation and likely inclusion/text normalization boundaries before lexical analysis. The lexer exposes token abstractions consumed by the parser; parser failures are represented in the domain model. Core paths: `src/preprocessor/source_file.cpp`, `src/lexer/token.hpp`, `src/model/parser_error.hpp`.

#### Musical Score Model
The parsed representation organizes notes, reusable patterns, pattern invocations, and the aggregate score. This is the boundary between declarative composition semantics and sample-level synthesis. `src/model/score.hpp`, `src/model/pattern.hpp`, and `src/model/note.hpp` define this central intermediate model.

#### Instruments and Voice Synthesis
`Instrument` is the polymorphic synthesis abstraction. Concrete oscillators generate procedural waveforms, while `Sampler` reads/playbacks source audio with resampling, looping, and AR envelopes; `Noise` adds non-tonal synthesis. Runtime-selected instruments are created through a factory, allowing parser-facing names to remain decoupled from implementations. Paths: `src/model/instrument.hpp`, `src/model/factories/instrument_factory.cpp`, `src/model/instruments/sampler.cpp`.

#### DSP Effects Chain
Effects share a common abstraction and are instantiated through an effect factory. The renderer applies configured effects sequentially to synthesized signal data, supporting gain, echo, filtering, distortion/bit reduction, and modulation. Paths: `src/model/effect.hpp`, `src/model/factories/effect_factory.cpp`, `src/model/effects/echo.cpp`.

#### Rendering and Audio I/O
The sound generator traverses the score, schedules/mixes polyphonic voices, resolves note frequencies via the note table, and produces PCM samples. WAV input supports sampled instruments; WAV output writes the final binary container. Bundled WAV assets under `samples/` are runtime content dependencies for sampler-based scores. Paths: `src/generator/sound_generator.cpp`, `src/utils/note_table.cpp`, `src/wav/wav_reader.cpp`, `src/wav/wav_writer.cpp`.

#### Runtime and Delivery Boundaries
The project is a native C++17/20 CMake application with no indicated server, database, or cloud dependencies. Inputs are DSL text plus optional local WAV samples; output is a local WAV file. Example compositions are under `examples/`, and CI/CD is defined in `.github/workflows/cicd.yml`.

Main entry points: [`src/model/score.hpp`](https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/score.hpp) (Score model), [`src/generator/sound_generator.cpp`](https://github.com/za-warka/itmoloops/blob/deadline_0/src/generator/sound_generator.cpp) (Sound generator), [`src/parser/parser.cpp`](https://github.com/za-warka/itmoloops/blob/deadline_0/src/parser/parser.cpp) (Parser), [`src/model/factories/instrument_factory.cpp`](https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/factories/instrument_factory.cpp) (Instrument factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["DSL Front End"]
  node_dsl_source["DSL score source<br/>text input"]
  node_source_file["Source file handling<br/>preprocessing input<br/>[source_file.cpp]"]
  node_preprocessor["Preprocessor<br/>DSL transformation<br/>[preprocessor.cpp]"]
  node_lexer["Lexer<br/>tokenizer<br/>[lexer.cpp]"]
  node_token["Token abstraction<br/>DSL token model<br/>[token.hpp]"]
  node_parser["Parser<br/>[parser.cpp]"]
  node_parser_error["Parser errors<br/>domain error model<br/>[parser_error.hpp]"]
end

subgraph group_model["Score &amp; Synthesis"]
  node_score["Score model<br/>composition IR<br/>[score.hpp]"]
  node_patterns_notes["Patterns and notes<br/>composition primitives<br/>[pattern.hpp]"]
  node_instrument["Instrument abstraction<br/>polymorphic synthesis<br/>[instrument.hpp]"]
  node_instrument_factory["Instrument factory<br/>runtime selection"]
  node_sampler["Sampler instrument<br/>sample playback<br/>[sampler.cpp]"]
  node_effect["Effect abstraction<br/>DSP effect<br/>[effect.hpp]"]
  node_effect_factory["Effect factory<br/>DSP selection<br/>[effect_factory.cpp]"]
  node_echo["Echo effect<br/>DSP implementation<br/>[echo.cpp]"]
end

subgraph group_audio["Audio Rendering &amp; I/O"]
  node_sound_generator["Sound generator<br/>score renderer"]
  node_note_table["Note table<br/>pitch lookup<br/>[note_table.cpp]"]
  node_wav_reader["WAV reader<br/>audio input<br/>[wav_reader.cpp]"]
  node_samples[("Bundled samples<br/>runtime WAV assets")]
  node_wav_writer["WAV writer<br/>audio export<br/>[wav_writer.cpp]"]
  node_wav_output["Output WAV<br/>local audio file"]
end

node_cli_main["Main CLI<br/>C++ executable<br/>[main.cpp]"]
node_cli_alt["Alternate CLI<br/>C++ executable<br/>[nmain.cpp]"]
node_build_wiring["Executable build wiring<br/>CMake<br/>[CMakeLists.txt]"]

node_build_wiring -->|"builds"| node_cli_main
node_build_wiring -->|"builds"| node_cli_alt
node_cli_main -->|"reads"| node_dsl_source
node_cli_alt -->|"reads"| node_dsl_source
node_dsl_source -->|"loads"| node_source_file
node_source_file -->|"prepares"| node_preprocessor
node_preprocessor -->|"transformed text"| node_lexer
node_lexer -->|"emits"| node_token
node_token -->|"consumed by"| node_parser
node_parser -.->|"reports failures"| node_parser_error
node_parser -->|"builds"| node_score
node_patterns_notes -->|"defines contents"| node_score
node_score -->|"selects instruments"| node_instrument_factory
node_instrument_factory -->|"creates"| node_instrument
node_instrument_factory -->|"selects"| node_sampler
node_samples -->|"source audio"| node_wav_reader
node_wav_reader -->|"decoded samples"| node_sampler
node_score -->|"configures effects"| node_effect_factory
node_effect_factory -->|"creates"| node_effect
node_effect_factory -->|"selects"| node_echo
node_score -->|"renders"| node_sound_generator
node_instrument -->|"synthesizes voices"| node_sound_generator
node_effect -->|"sequential processing"| node_sound_generator
node_note_table -->|"note frequencies"| node_sound_generator
node_sound_generator -->|"PCM samples"| node_wav_writer
node_wav_writer -->|"writes"| node_wav_output

click node_cli_main "https://github.com/za-warka/itmoloops/blob/deadline_0/bin/main.cpp"
click node_cli_alt "https://github.com/za-warka/itmoloops/blob/deadline_0/bin/nmain.cpp"
click node_build_wiring "https://github.com/za-warka/itmoloops/blob/deadline_0/bin/CMakeLists.txt"
click node_source_file "https://github.com/za-warka/itmoloops/blob/deadline_0/src/preprocessor/source_file.cpp"
click node_preprocessor "https://github.com/za-warka/itmoloops/blob/deadline_0/src/preprocessor/preprocessor.cpp"
click node_lexer "https://github.com/za-warka/itmoloops/blob/deadline_0/src/lexer/lexer.cpp"
click node_token "https://github.com/za-warka/itmoloops/blob/deadline_0/src/lexer/token.hpp"
click node_parser "https://github.com/za-warka/itmoloops/blob/deadline_0/src/parser/parser.cpp"
click node_parser_error "https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/parser_error.hpp"
click node_score "https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/score.hpp"
click node_patterns_notes "https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/pattern.hpp"
click node_instrument "https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/instrument.hpp"
click node_instrument_factory "https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/factories/instrument_factory.cpp"
click node_sampler "https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/instruments/sampler.cpp"
click node_effect "https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/effect.hpp"
click node_effect_factory "https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/factories/effect_factory.cpp"
click node_echo "https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/effects/echo.cpp"
click node_sound_generator "https://github.com/za-warka/itmoloops/blob/deadline_0/src/generator/sound_generator.cpp"
click node_note_table "https://github.com/za-warka/itmoloops/blob/deadline_0/src/utils/note_table.cpp"
click node_wav_reader "https://github.com/za-warka/itmoloops/blob/deadline_0/src/wav/wav_reader.cpp"
click node_wav_writer "https://github.com/za-warka/itmoloops/blob/deadline_0/src/wav/wav_writer.cpp"

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_dsl_source,node_source_file,node_preprocessor,node_lexer,node_token,node_parser,node_parser_error toneBlue
class node_score,node_patterns_notes,node_instrument,node_instrument_factory,node_sampler,node_effect,node_effect_factory,node_echo toneAmber
class node_sound_generator,node_note_table,node_wav_reader,node_samples,node_wav_writer,node_wav_output toneMint
class node_cli_main,node_cli_alt,node_build_wiring toneNeutral
```

## Components

### DSL Front End

- **DSL score source**: text input
- [Source file handling](https://github.com/za-warka/itmoloops/blob/deadline_0/src/preprocessor/source_file.cpp): preprocessing input · `src/preprocessor/source_file.cpp`
- [Preprocessor](https://github.com/za-warka/itmoloops/blob/deadline_0/src/preprocessor/preprocessor.cpp): DSL transformation · Normalizes source-level content before lexing. · `src/preprocessor/preprocessor.cpp`
- [Lexer](https://github.com/za-warka/itmoloops/blob/deadline_0/src/lexer/lexer.cpp): tokenizer · `src/lexer/lexer.cpp`
- [Token abstraction](https://github.com/za-warka/itmoloops/blob/deadline_0/src/lexer/token.hpp): DSL token model · `src/lexer/token.hpp`
- [Parser](https://github.com/za-warka/itmoloops/blob/deadline_0/src/parser/parser.cpp): DSL parser · `src/parser/parser.cpp`
- [Parser errors](https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/parser_error.hpp): domain error model · `src/model/parser_error.hpp`

### Score & Synthesis

- [Score model](https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/score.hpp): composition IR · Time-oriented boundary between DSL semantics and sample rendering. · `src/model/score.hpp`
- [Patterns and notes](https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/pattern.hpp): composition primitives · `src/model/pattern.hpp`
- [Instrument abstraction](https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/instrument.hpp): polymorphic synthesis · `src/model/instrument.hpp`
- [Instrument factory](https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/factories/instrument_factory.cpp): runtime selection · `src/model/factories/instrument_factory.cpp`
- [Sampler instrument](https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/instruments/sampler.cpp): sample playback · Reads WAV sources with resampling, looping, and envelopes. · `src/model/instruments/sampler.cpp`
- [Effect abstraction](https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/effect.hpp): DSP effect · `src/model/effect.hpp`
- [Effect factory](https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/factories/effect_factory.cpp): DSP selection · `src/model/factories/effect_factory.cpp`
- [Echo effect](https://github.com/za-warka/itmoloops/blob/deadline_0/src/model/effects/echo.cpp): DSP implementation · `src/model/effects/echo.cpp`

### Audio Rendering & I/O

- [Sound generator](https://github.com/za-warka/itmoloops/blob/deadline_0/src/generator/sound_generator.cpp): score renderer · Schedules and mixes polyphonic voices into PCM samples. · `src/generator/sound_generator.cpp`
- [Note table](https://github.com/za-warka/itmoloops/blob/deadline_0/src/utils/note_table.cpp): pitch lookup · `src/utils/note_table.cpp`
- [WAV reader](https://github.com/za-warka/itmoloops/blob/deadline_0/src/wav/wav_reader.cpp): audio input · `src/wav/wav_reader.cpp`
- **Bundled samples**: runtime WAV assets
- [WAV writer](https://github.com/za-warka/itmoloops/blob/deadline_0/src/wav/wav_writer.cpp): audio export · `src/wav/wav_writer.cpp`
- **Output WAV**: local audio file · 44.1 kHz, 16-bit PCM output.

### Other components

- [Main CLI](https://github.com/za-warka/itmoloops/blob/deadline_0/bin/main.cpp): C++ executable · `bin/main.cpp`
- [Alternate CLI](https://github.com/za-warka/itmoloops/blob/deadline_0/bin/nmain.cpp): C++ executable · `bin/nmain.cpp`
- [Executable build wiring](https://github.com/za-warka/itmoloops/blob/deadline_0/bin/CMakeLists.txt): CMake · `bin/CMakeLists.txt`

## Connections

- Executable build wiring → Main CLI: builds
- Executable build wiring → Alternate CLI: builds
- Main CLI → DSL score source: reads
- Alternate CLI → DSL score source: reads
- DSL score source → Source file handling: loads
- Source file handling → Preprocessor: prepares
- Preprocessor → Lexer: transformed text
- Lexer → Token abstraction: emits
- Token abstraction → Parser: consumed by
- Parser → Parser errors: reports failures
- Parser → Score model: builds
- Patterns and notes → Score model: defines contents
- Score model → Instrument factory: selects instruments
- Instrument factory → Instrument abstraction: creates
- Instrument factory → Sampler instrument: selects
- Bundled samples → WAV reader: source audio
- WAV reader → Sampler instrument: decoded samples
- Score model → Effect factory: configures effects
- Effect factory → Effect abstraction: creates
- Effect factory → Echo effect: selects
- Score model → Sound generator: renders
- Instrument abstraction → Sound generator: synthesizes voices
- Effect abstraction → Sound generator: sequential processing
- Note table → Sound generator: note frequencies
- Sound generator → WAV writer: PCM samples
- WAV writer → Output WAV: writes