# kornelszyszka/synesterra architecture

> Architecture diagram of the GitHub repository kornelszyszka/synesterra, 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/kornelszyszka/synesterra
- Repository: https://github.com/kornelszyszka/synesterra

## Overview

Synesterra is a browser-based rhythm and harmony instrument. A user edits a serializable session in the UI, starts transport explicitly, and hears scheduled rhythm clicks alongside an optional tonal drone; the same clock drives circle, timeline, and polygon visuals. The UI also manages validated local session and appearance preferences, language, and themes. The README documents an installable offline PWA. The graph reflects the README and shown import/call evidence; several runtime details, especially PWA wiring and UI actions in omitted excerpts, were not inspected.

Main entry points: [`src/ui/app.ts`](https://github.com/kornelszyszka/synesterra/blob/main/src/ui/app.ts) (Instrument controls), [`src/audio/engine.ts`](https://github.com/kornelszyszka/synesterra/blob/main/src/audio/engine.ts) (Audio engine), [`src/visual/views.ts`](https://github.com/kornelszyszka/synesterra/blob/main/src/visual/views.ts) (SVG views), [`src/domain/harmonic-performance.ts`](https://github.com/kornelszyszka/synesterra/blob/main/src/domain/harmonic-performance.ts) (Harmonic performance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_composition["Instrument UI"]
  node_app["Instrument controls<br/>[app.ts]"]
  node_entry["Browser entry point<br/>[main.ts]"]
end

subgraph group_music["Music Domain"]
  node_session["Session model<br/>[session.ts]"]
  node_rhythm["Rhythm events<br/>[rhythm.ts]"]
  node_harmony["Harmony rules<br/>[harmony.ts]"]
  node_performance["Harmonic performance"]
  node_colors["Note colors<br/>[note-colors.ts]"]
end

subgraph group_sound["Audio Runtime"]
  node_engine["Audio engine<br/>[engine.ts]"]
  node_clock["Transport clock<br/>[clock.ts]"]
  node_scheduler["Look-ahead scheduler<br/>[scheduler.ts]"]
  node_clicks["Click voices<br/>[voices.ts]"]
  node_drone["Drone engine<br/>[drone.ts]"]
end

subgraph group_presentation["Visual Preferences"]
  node_visual["SVG views<br/>[views.ts]"]
  node_themes["Theme palettes<br/>[palette.ts]"]
  node_note_palette["Base note palette<br/>[note-palette.ts]"]
  node_translations["Translations<br/>[index.ts]"]
end

subgraph group_platform["Local Platform"]
  node_preferences["Appearance preferences<br/>[preferences.ts]"]
  node_storage["Session persistence<br/>[storage.ts]"]
  node_pwa["Offline PWA support<br/>[pwa.ts]"]
end

node_user(("Instrument user"))
node_local_store[("Browser localStorage")]

node_user -->|"edits and starts"| node_app
node_app -->|"updates session"| node_session
node_app -->|"controls playback"| node_engine
node_app -->|"loads and saves"| node_storage
node_app -->|"loads and saves"| node_preferences
node_app -->|"renders views"| node_visual
node_app -->|"applies palette"| node_themes
node_app -->|"translates interface"| node_translations
node_session -->|"uses cycle math"| node_rhythm
node_session -->|"uses chord rules"| node_harmony
node_session -->|"uses note palette"| node_colors
node_performance -->|"builds voicings"| node_harmony
node_performance -->|"colors notes"| node_colors
node_performance -->|"finds rhythm events"| node_rhythm
node_performance -->|"reads progression"| node_session
node_engine -->|"configures transport"| node_clock
node_engine -->|"starts scheduler"| node_scheduler
node_engine -->|"creates voices"| node_clicks
node_engine -->|"updates drone"| node_drone
node_scheduler -->|"maps audio time"| node_clock
node_scheduler -->|"schedules events"| node_rhythm
node_scheduler -->|"triggers voices"| node_clicks
node_drone -->|"uses chord rules"| node_harmony
node_drone -->|"uses note timbres"| node_colors
node_visual -->|"draws rhythm"| node_rhythm
node_visual -->|"draws harmonic focus"| node_performance
node_visual -->|"translates labels"| node_translations
node_visual -->|"uses visual theme"| node_themes
node_themes -->|"uses note colors"| node_note_palette
node_colors -->|"uses base colors"| node_note_palette
node_preferences -->|"uses palettes"| node_themes
node_preferences -->|"uses languages"| node_translations
node_storage -->|"reads and writes"| node_local_store
node_preferences -.->|"persists preferences"| node_local_store
node_entry -->|"starts interface"| node_app
node_entry -->|"initializes support"| node_pwa
node_pwa -.->|"caches offline shell"| node_local_store

click node_app "https://github.com/kornelszyszka/synesterra/blob/main/src/ui/app.ts"
click node_session "https://github.com/kornelszyszka/synesterra/blob/main/src/domain/session.ts"
click node_rhythm "https://github.com/kornelszyszka/synesterra/blob/main/src/domain/rhythm.ts"
click node_harmony "https://github.com/kornelszyszka/synesterra/blob/main/src/domain/harmony.ts"
click node_performance "https://github.com/kornelszyszka/synesterra/blob/main/src/domain/harmonic-performance.ts"
click node_colors "https://github.com/kornelszyszka/synesterra/blob/main/src/domain/note-colors.ts"
click node_engine "https://github.com/kornelszyszka/synesterra/blob/main/src/audio/engine.ts"
click node_clock "https://github.com/kornelszyszka/synesterra/blob/main/src/transport/clock.ts"
click node_scheduler "https://github.com/kornelszyszka/synesterra/blob/main/src/audio/scheduler.ts"
click node_clicks "https://github.com/kornelszyszka/synesterra/blob/main/src/audio/voices.ts"
click node_drone "https://github.com/kornelszyszka/synesterra/blob/main/src/audio/drone.ts"
click node_visual "https://github.com/kornelszyszka/synesterra/blob/main/src/visual/views.ts"
click node_themes "https://github.com/kornelszyszka/synesterra/blob/main/src/theme/palette.ts"
click node_note_palette "https://github.com/kornelszyszka/synesterra/blob/main/src/theme/note-palette.ts"
click node_translations "https://github.com/kornelszyszka/synesterra/blob/main/src/i18n/index.ts"
click node_preferences "https://github.com/kornelszyszka/synesterra/blob/main/src/persistence/preferences.ts"
click node_storage "https://github.com/kornelszyszka/synesterra/blob/main/src/persistence/storage.ts"
click node_entry "https://github.com/kornelszyszka/synesterra/blob/main/src/main.ts"
click node_pwa "https://github.com/kornelszyszka/synesterra/blob/main/src/pwa.ts"

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_entry,node_user toneBlue
class node_session,node_rhythm,node_harmony,node_performance,node_colors,node_local_store toneAmber
class node_engine,node_clock,node_scheduler,node_clicks,node_drone toneMint
class node_visual,node_themes,node_note_palette,node_translations toneRose
class node_preferences,node_storage,node_pwa toneIndigo
```

## Components

### Instrument UI

- [Instrument controls](https://github.com/kornelszyszka/synesterra/blob/main/src/ui/app.ts): `src/ui/app.ts`
- [Browser entry point](https://github.com/kornelszyszka/synesterra/blob/main/src/main.ts): `src/main.ts`

### Music Domain

- [Session model](https://github.com/kornelszyszka/synesterra/blob/main/src/domain/session.ts): `src/domain/session.ts`
- [Rhythm events](https://github.com/kornelszyszka/synesterra/blob/main/src/domain/rhythm.ts): `src/domain/rhythm.ts`
- [Harmony rules](https://github.com/kornelszyszka/synesterra/blob/main/src/domain/harmony.ts): `src/domain/harmony.ts`
- [Harmonic performance](https://github.com/kornelszyszka/synesterra/blob/main/src/domain/harmonic-performance.ts): `src/domain/harmonic-performance.ts`
- [Note colors](https://github.com/kornelszyszka/synesterra/blob/main/src/domain/note-colors.ts): `src/domain/note-colors.ts`

### Audio Runtime

- [Audio engine](https://github.com/kornelszyszka/synesterra/blob/main/src/audio/engine.ts): `src/audio/engine.ts`
- [Transport clock](https://github.com/kornelszyszka/synesterra/blob/main/src/transport/clock.ts): `src/transport/clock.ts`
- [Look-ahead scheduler](https://github.com/kornelszyszka/synesterra/blob/main/src/audio/scheduler.ts): `src/audio/scheduler.ts`
- [Click voices](https://github.com/kornelszyszka/synesterra/blob/main/src/audio/voices.ts): `src/audio/voices.ts`
- [Drone engine](https://github.com/kornelszyszka/synesterra/blob/main/src/audio/drone.ts): `src/audio/drone.ts`

### Visual Preferences

- [SVG views](https://github.com/kornelszyszka/synesterra/blob/main/src/visual/views.ts): `src/visual/views.ts`
- [Theme palettes](https://github.com/kornelszyszka/synesterra/blob/main/src/theme/palette.ts): `src/theme/palette.ts`
- [Base note palette](https://github.com/kornelszyszka/synesterra/blob/main/src/theme/note-palette.ts): `src/theme/note-palette.ts`
- [Translations](https://github.com/kornelszyszka/synesterra/blob/main/src/i18n/index.ts): `src/i18n/index.ts`

### Local Platform

- [Appearance preferences](https://github.com/kornelszyszka/synesterra/blob/main/src/persistence/preferences.ts): `src/persistence/preferences.ts`
- [Session persistence](https://github.com/kornelszyszka/synesterra/blob/main/src/persistence/storage.ts): `src/persistence/storage.ts`
- [Offline PWA support](https://github.com/kornelszyszka/synesterra/blob/main/src/pwa.ts): `src/pwa.ts`

### Other components

- **Instrument user**
- **Browser localStorage**

## Connections

- Instrument user → Instrument controls: edits and starts (evidence: `README.md`)
- Instrument controls → Session model: updates session (evidence: `src/ui/app.ts`)
- Instrument controls → Audio engine: controls playback (evidence: `src/ui/app.ts`)
- Instrument controls → Session persistence: loads and saves (evidence: `src/ui/app.ts`)
- Instrument controls → Appearance preferences: loads and saves (evidence: `src/ui/app.ts`)
- Instrument controls → SVG views: renders views (evidence: `src/ui/app.ts`)
- Instrument controls → Theme palettes: applies palette (evidence: `src/ui/app.ts`)
- Instrument controls → Translations: translates interface (evidence: `src/ui/app.ts`)
- Session model → Rhythm events: uses cycle math (evidence: `src/domain/session.ts`)
- Session model → Harmony rules: uses chord rules (evidence: `src/domain/session.ts`)
- Session model → Note colors: uses note palette (evidence: `src/domain/session.ts`)
- Harmonic performance → Harmony rules: builds voicings (evidence: `src/domain/harmonic-performance.ts`)
- Harmonic performance → Note colors: colors notes (evidence: `src/domain/harmonic-performance.ts`)
- Harmonic performance → Rhythm events: finds rhythm events (evidence: `src/domain/harmonic-performance.ts`)
- Harmonic performance → Session model: reads progression (evidence: `src/domain/harmonic-performance.ts`)
- Audio engine → Transport clock: configures transport (evidence: `src/audio/engine.ts`)
- Audio engine → Look-ahead scheduler: starts scheduler (evidence: `src/audio/engine.ts`)
- Audio engine → Click voices: creates voices (evidence: `src/audio/engine.ts`)
- Audio engine → Drone engine: updates drone (evidence: `src/audio/engine.ts`)
- Look-ahead scheduler → Transport clock: maps audio time (evidence: `src/audio/scheduler.ts`)
- Look-ahead scheduler → Rhythm events: schedules events (evidence: `src/audio/scheduler.ts`)
- Look-ahead scheduler → Click voices: triggers voices (evidence: `src/audio/scheduler.ts`)
- Drone engine → Harmony rules: uses chord rules (evidence: `src/audio/drone.ts`)
- Drone engine → Note colors: uses note timbres (evidence: `src/audio/drone.ts`)
- SVG views → Rhythm events: draws rhythm (evidence: `src/visual/views.ts`)
- SVG views → Harmonic performance: draws harmonic focus (evidence: `src/visual/views.ts`)
- SVG views → Translations: translates labels (evidence: `src/visual/views.ts`)
- SVG views → Theme palettes: uses visual theme (evidence: `src/visual/views.ts`)
- Theme palettes → Base note palette: uses note colors (evidence: `src/theme/palette.ts`)
- Note colors → Base note palette: uses base colors (evidence: `src/domain/note-colors.ts`)
- Appearance preferences → Theme palettes: uses palettes (evidence: `src/persistence/preferences.ts`)
- Appearance preferences → Translations: uses languages (evidence: `src/persistence/preferences.ts`)
- Session persistence → Browser localStorage: reads and writes (evidence: `src/persistence/storage.ts`)
- Appearance preferences → Browser localStorage: persists preferences
- Browser entry point → Instrument controls: starts interface (evidence: `src/main.ts`)
- Browser entry point → Offline PWA support: initializes support (evidence: `src/main.ts`)
- Offline PWA support → Browser localStorage: caches offline shell