# another-machine/omnichord architecture

> Architecture diagram of the GitHub repository another-machine/omnichord, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/another-machine/omnichord
- Repository: https://github.com/another-machine/omnichord

## Overview

#### Purpose and runtime

Omnichord is a no-build static browser instrument: a chord grid plus playable harp strip, synthesized held/plucked voices, and programmed drum rhythms. It runs from any static HTTP server; the browser is the runtime.

The document and module bootstrap are:
- `index.html`
- `app.js`

`index.html` provides the import map required for bare-specifier dependencies, including `@amplib/music-theory` and `@amplib/sound-synthesis`.

#### Application composition

`app.js` is the likely top-level composition point: it connects the instrument model, rendering, controls, sound, layout, theme, and touch input into one browser application.

The core collaborating modules are:
- `app.js`
- `controller.js`
- `cartridge.js`

`controller.js` is the control/state boundary for UI actions such as menu configuration, chord editing, selection changes, and hash-driven edit mode. `cartridge.js` represents the selected musical setup: enabled chords and user-facing instrument/rhythm/layout choices.

#### Musical chord domain

Chord definitions and chord-set behavior are isolated from rendering and audio:
- `chords.js`
- `cartridge.js`

`chords.js` is the integration boundary for theory-derived chord data. The application presents up to the original 84-chord root/type grid, while chord editing disables entries rather than changing the underlying theory source. The resulting enabled-chord set is consumed by layout and interaction layers.

#### Responsive visual layout

The layout subsystem translates enabled chords and viewport orientation into instrument geometry:
- `layout.js`
- `app.js`

It supports the three documented policies: fixed slots, row-filling by chord type, and flex packing near a square grid. It also places the harp at logical `first` or `last`, adapting that choice to portrait versus landscape, and reserves the opposite edge for the menu lane. This is a primary boundary between application state and screen-specific rendering.

#### Rendering and themes

Visual presentation is separated into color calculation/theme state and application rendering:
- `theme.js`
- `app.js`
- `layout.js`

Themes derive colors from chord position—root across hue and chord type across lightness—rather than assigning fixed colors per chord. Presets and custom slider ranges therefore affect rendering without altering chord, layout, or audio data.

#### Audio engine and external synthesis

Audio behavior is centralized behind:
- `sounds.js`
- `app.js`

`sounds.js` integrates the external sound-synthesis package to create FM-based chord-pad and harp voices plus synthesized drum patterns. Voice selection changes both pad and harp as one instrument. Rhythm and BPM are audio/control inputs rather than sample playback controls, avoiding sample-loading and playback-rate dependencies.

External service/package boundaries:
- `index.html` — import-map resolution for `@amplib/music-theory` and `@amplib/sound-synthesis`
- Browser Web Audio capabilities used by the synthesis dependency

#### Pointer and touch interaction

Direct instrument gestures are handled separately from application control widgets:
- `touch.js`
- `controller.js`
- `app.js`

`touch.js` is the input boundary for tapping chord cells and sliding/playing the harp strip. `controller.js` distinguishes these musical interactions from configuration actions and edit-chord mode, where grid taps disable chords. URL hash state supports entering and leaving edit mode through browser navigation.

Main entry points: [`app.js`](https://github.com/another-machine/omnichord/blob/main/app.js) (Application composition), [`controller.js`](https://github.com/another-machine/omnichord/blob/main/controller.js) (Control state), [`cartridge.js`](https://github.com/another-machine/omnichord/blob/main/cartridge.js) (Selected setup), [`sounds.js`](https://github.com/another-machine/omnichord/blob/main/sounds.js) (Synthesis engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Browser runtime"]
  node_document["HTML document + import map<br/>bootstrap<br/>[index.html]"]
  node_browser(("Browser + Web Audio<br/>runtime"))
  node_music_theory{{"Music theory package<br/>external dependency"}}
  node_sound_synthesis{{"Sound synthesis package<br/>external dependency"}}
end

subgraph group_core["Instrument state"]
  node_app["Application composition<br/>browser app<br/>[app.js]"]
  node_controller["Control state<br/>controller<br/>[controller.js]"]
  node_cartridge["Selected setup<br/>instrument model<br/>[cartridge.js]"]
  node_chords["Chord theory boundary<br/>chord domain<br/>[chords.js]"]
end

subgraph group_visual["Layout and rendering"]
  node_layout["Responsive geometry<br/>layout engine<br/>[layout.js]"]
  node_theme["Position-derived themes<br/>theme engine<br/>[theme.js]"]
  node_rendering["Instrument UI<br/>rendered interface"]
end

subgraph group_interaction["Input and audio"]
  node_touch["Instrument gestures<br/>pointer input<br/>[touch.js]"]
  node_sounds["Synthesis engine<br/>audio engine<br/>[sounds.js]"]
end

node_document -->|"boots module"| node_app
node_document -->|"import map"| node_music_theory
node_document -->|"import map"| node_sound_synthesis
node_browser -->|"runs"| node_app
node_app -->|"coordinates actions"| node_controller
node_app -->|"uses setup"| node_cartridge
node_app -->|"requests geometry"| node_layout
node_app -->|"applies theme"| node_theme
node_app -->|"renders"| node_rendering
node_app -->|"binds gestures"| node_touch
node_app -->|"drives audio"| node_sounds
node_controller -->|"updates choices"| node_cartridge
node_cartridge -->|"enables chord set"| node_chords
node_chords -->|"derives chord data"| node_music_theory
node_cartridge -->|"enabled chords"| node_layout
node_layout -->|"positions controls"| node_rendering
node_theme -->|"supplies colors"| node_rendering
node_touch -->|"musical and edit actions"| node_controller
node_controller -->|"voice, rhythm, BPM"| node_sounds
node_sounds -->|"creates voices"| node_sound_synthesis
node_sounds -->|"Web Audio output"| node_browser

click node_document "https://github.com/another-machine/omnichord/blob/main/index.html"
click node_app "https://github.com/another-machine/omnichord/blob/main/app.js"
click node_controller "https://github.com/another-machine/omnichord/blob/main/controller.js"
click node_cartridge "https://github.com/another-machine/omnichord/blob/main/cartridge.js"
click node_chords "https://github.com/another-machine/omnichord/blob/main/chords.js"
click node_layout "https://github.com/another-machine/omnichord/blob/main/layout.js"
click node_theme "https://github.com/another-machine/omnichord/blob/main/theme.js"
click node_touch "https://github.com/another-machine/omnichord/blob/main/touch.js"
click node_sounds "https://github.com/another-machine/omnichord/blob/main/sounds.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_document,node_browser,node_music_theory,node_sound_synthesis toneBlue
class node_app,node_controller,node_cartridge,node_chords toneAmber
class node_layout,node_theme,node_rendering toneMint
class node_touch,node_sounds toneRose
```

## Components

### Browser runtime

- [HTML document + import map](https://github.com/another-machine/omnichord/blob/main/index.html): bootstrap · Resolves bare music and synthesis dependencies. · `index.html`
- **Browser + Web Audio**: runtime
- **Music theory package**: external dependency
- **Sound synthesis package**: external dependency

### Instrument state

- [Application composition](https://github.com/another-machine/omnichord/blob/main/app.js): browser app · Connects state, visuals, input, and sound. · `app.js`
- [Control state](https://github.com/another-machine/omnichord/blob/main/controller.js): controller · Handles configuration, selection, chord editing, and hash edit mode. · `controller.js`
- [Selected setup](https://github.com/another-machine/omnichord/blob/main/cartridge.js): instrument model · Stores enabled chords and user-facing instrument choices. · `cartridge.js`
- [Chord theory boundary](https://github.com/another-machine/omnichord/blob/main/chords.js): chord domain · Provides the fixed root/type grid and enabled-chord behavior. · `chords.js`

### Layout and rendering

- [Responsive geometry](https://github.com/another-machine/omnichord/blob/main/layout.js): layout engine · Maps enabled chords and orientation to grid, harp, and menu lanes. · `layout.js`
- [Position-derived themes](https://github.com/another-machine/omnichord/blob/main/theme.js): theme engine · Calculates chord colors from root and chord type. · `theme.js`
- **Instrument UI**: rendered interface · Chord grid, harp strip, menu, and edit presentation.

### Input and audio

- [Instrument gestures](https://github.com/another-machine/omnichord/blob/main/touch.js): pointer input · Interprets chord taps and harp sliding. · `touch.js`
- [Synthesis engine](https://github.com/another-machine/omnichord/blob/main/sounds.js): audio engine · Creates FM pad, harp, and programmed drum voices. · `sounds.js`

## Connections

- HTML document + import map → Application composition: boots module
- HTML document + import map → Music theory package: import map
- HTML document + import map → Sound synthesis package: import map
- Browser + Web Audio → Application composition: runs
- Application composition → Control state: coordinates actions
- Application composition → Selected setup: uses setup
- Application composition → Responsive geometry: requests geometry
- Application composition → Position-derived themes: applies theme
- Application composition → Instrument UI: renders
- Application composition → Instrument gestures: binds gestures
- Application composition → Synthesis engine: drives audio
- Control state → Selected setup: updates choices
- Selected setup → Chord theory boundary: enables chord set
- Chord theory boundary → Music theory package: derives chord data
- Selected setup → Responsive geometry: enabled chords
- Responsive geometry → Instrument UI: positions controls
- Position-derived themes → Instrument UI: supplies colors
- Instrument gestures → Control state: musical and edit actions
- Control state → Synthesis engine: voice, rhythm, BPM
- Synthesis engine → Sound synthesis package: creates voices
- Synthesis engine → Browser + Web Audio: Web Audio output