# saarsena/theory-aide architecture

> Architecture diagram of the GitHub repository saarsena/theory-aide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saarsena/theory-aide
- Repository: https://github.com/saarsena/theory-aide

## Overview

Theory Aide is an Ableton Live extension and a companion browser-based music-theory course. In Live, a producer selects a clip, scene, or arrangement range; the extension extracts MIDI notes, routes them to the relevant analysis, and presents findings and suggested next steps. The shared TypeScript engine covers harmony, rhythm, voicing, counterpoint, form, texture, and composition mapping. The site teaches theory and demonstrates a shared analysis path with curated examples. Relationships for unsampled capabilities follow the README; sampled source excerpts confirm selected implementation links.

Main entry points: [`src/extension.ts`](https://github.com/saarsena/theory-aide/blob/main/src/extension.ts) (Commands and MIDI extraction), [`src/theory/timeline.ts`](https://github.com/saarsena/theory-aide/blob/main/src/theory/timeline.ts) (Harmonic timeline), [`site/src`](https://github.com/saarsena/theory-aide/tree/main/site/src) (Course and demos), [`src/theory/analyzer.ts`](https://github.com/saarsena/theory-aide/blob/main/src/theory/analyzer.ts) (Harmony and key analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_live["Live extension"]
  node_commands["Commands and MIDI extraction<br/>[extension.ts]"]
end

subgraph group_engine["Analysis engine"]
  node_harmony["Harmony and key analysis<br/>[analyzer.ts]"]
  node_primitives["Scales and chord primitives<br/>[core.ts]"]
  node_tables["Theory data<br/>[data.ts]"]
  node_timeline["Harmonic timeline<br/>[timeline.ts]"]
  node_counterpoint["Counterpoint checker<br/>[counterpoint.ts]"]
  node_dimensions["Composition dimensions<br/>[dimensions.ts]"]
  node_form["Arrangement form<br/>[form.ts]"]
  node_mapping["Composition map<br/>[map.ts]"]
  node_rhythm["Rhythm and phrasing<br/>[rhythm.ts]"]
  node_voicing["Voicing and density<br/>[voicing.ts]"]
  node_timbre["Timbre and dynamics<br/>[timbre.ts]"]
  node_tonerow["Tone row analysis<br/>[tonerow.ts]"]
end

subgraph group_guidance["Creative guidance"]
  node_nextmoves["Next-move suggestions<br/>[nextMoves.ts]"]
end

subgraph group_website["Teaching website"]
  node_sitecourse["Course and demos"]
  node_sitecontent["Teaching examples<br/>[examples.ts]"]
  node_player["Playable note demos<br/>[player.ts]"]
  node_sitenav["Reading paths<br/>[clusters.js]"]
end

node_producer(("Music producer"))
node_livehost["Ableton Live"]
node_reader(("Course reader"))
node_browser["Web browser"]

node_producer -->|"selects MIDI"| node_livehost
node_livehost -->|"dispatches commands"| node_commands
node_commands -->|"analyzes harmony"| node_harmony
node_commands -->|"analyzes selections"| node_timeline
node_commands -->|"checks tracks"| node_counterpoint
node_commands -->|"scores dimensions"| node_dimensions
node_commands -->|"detects sections"| node_form
node_commands -->|"maps composition"| node_mapping
node_commands -->|"analyzes phrasing"| node_rhythm
node_commands -->|"checks voicing"| node_voicing
node_commands -->|"analyzes texture"| node_timbre
node_commands -->|"checks tone rows"| node_tonerow
node_commands -->|"builds suggestions"| node_nextmoves
node_harmony -->|"uses"| node_primitives
node_harmony -->|"uses"| node_tables
node_timeline -->|"recognizes chords"| node_primitives
node_timeline -->|"uses key analysis"| node_harmony
node_counterpoint -->|"uses pitch classes"| node_primitives
node_dimensions -->|"scores analysis"| node_timeline
node_form -->|"uses analysis"| node_timeline
node_mapping -->|"uses analysis"| node_timeline
node_rhythm -->|"reads notes"| node_timeline
node_voicing -->|"uses analysis"| node_timeline
node_timbre -->|"uses analysis"| node_timeline
node_tonerow -->|"uses theory"| node_primitives
node_tonerow -->|"uses notes"| node_timeline
node_nextmoves -->|"uses analysis"| node_timeline
node_reader -->|"opens course"| node_browser
node_browser -->|"runs demos"| node_sitecourse
node_sitecourse -->|"loads examples"| node_sitecontent
node_sitecourse -->|"plays examples"| node_player
node_sitecourse -->|"analyzes examples"| node_counterpoint
node_sitecourse -->|"organizes lessons"| node_sitenav

click node_commands "https://github.com/saarsena/theory-aide/blob/main/src/extension.ts"
click node_harmony "https://github.com/saarsena/theory-aide/blob/main/src/theory/analyzer.ts"
click node_primitives "https://github.com/saarsena/theory-aide/blob/main/src/theory/core.ts"
click node_tables "https://github.com/saarsena/theory-aide/blob/main/src/theory/data.ts"
click node_timeline "https://github.com/saarsena/theory-aide/blob/main/src/theory/timeline.ts"
click node_counterpoint "https://github.com/saarsena/theory-aide/blob/main/src/theory/counterpoint.ts"
click node_dimensions "https://github.com/saarsena/theory-aide/blob/main/src/theory/dimensions.ts"
click node_form "https://github.com/saarsena/theory-aide/blob/main/src/theory/form.ts"
click node_mapping "https://github.com/saarsena/theory-aide/blob/main/src/theory/map.ts"
click node_rhythm "https://github.com/saarsena/theory-aide/blob/main/src/theory/rhythm.ts"
click node_voicing "https://github.com/saarsena/theory-aide/blob/main/src/theory/voicing.ts"
click node_timbre "https://github.com/saarsena/theory-aide/blob/main/src/theory/timbre.ts"
click node_tonerow "https://github.com/saarsena/theory-aide/blob/main/src/theory/tonerow.ts"
click node_nextmoves "https://github.com/saarsena/theory-aide/blob/main/src/theory/nextMoves.ts"
click node_sitecourse "https://github.com/saarsena/theory-aide/tree/main/site/src"
click node_sitecontent "https://github.com/saarsena/theory-aide/blob/main/site/src/examples.ts"
click node_player "https://github.com/saarsena/theory-aide/blob/main/site/src/lib/player.ts"
click node_sitenav "https://github.com/saarsena/theory-aide/blob/main/site/_data/clusters.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_commands,node_browser toneBlue
class node_harmony,node_primitives,node_tables,node_timeline,node_counterpoint,node_dimensions,node_form,node_mapping,node_rhythm,node_voicing,node_timbre,node_tonerow toneAmber
class node_nextmoves toneMint
class node_sitecourse,node_sitecontent,node_player,node_sitenav toneRose
class node_producer,node_livehost,node_reader toneIndigo
```

## Components

### Live extension

- [Commands and MIDI extraction](https://github.com/saarsena/theory-aide/blob/main/src/extension.ts): `src/extension.ts`

### Analysis engine

- [Harmony and key analysis](https://github.com/saarsena/theory-aide/blob/main/src/theory/analyzer.ts): `src/theory/analyzer.ts`
- [Scales and chord primitives](https://github.com/saarsena/theory-aide/blob/main/src/theory/core.ts): `src/theory/core.ts`
- [Theory data](https://github.com/saarsena/theory-aide/blob/main/src/theory/data.ts): `src/theory/data.ts`
- [Harmonic timeline](https://github.com/saarsena/theory-aide/blob/main/src/theory/timeline.ts): `src/theory/timeline.ts`
- [Counterpoint checker](https://github.com/saarsena/theory-aide/blob/main/src/theory/counterpoint.ts): `src/theory/counterpoint.ts`
- [Composition dimensions](https://github.com/saarsena/theory-aide/blob/main/src/theory/dimensions.ts): `src/theory/dimensions.ts`
- [Arrangement form](https://github.com/saarsena/theory-aide/blob/main/src/theory/form.ts): `src/theory/form.ts`
- [Composition map](https://github.com/saarsena/theory-aide/blob/main/src/theory/map.ts): `src/theory/map.ts`
- [Rhythm and phrasing](https://github.com/saarsena/theory-aide/blob/main/src/theory/rhythm.ts): `src/theory/rhythm.ts`
- [Voicing and density](https://github.com/saarsena/theory-aide/blob/main/src/theory/voicing.ts): `src/theory/voicing.ts`
- [Timbre and dynamics](https://github.com/saarsena/theory-aide/blob/main/src/theory/timbre.ts): `src/theory/timbre.ts`
- [Tone row analysis](https://github.com/saarsena/theory-aide/blob/main/src/theory/tonerow.ts): `src/theory/tonerow.ts`

### Creative guidance

- [Next-move suggestions](https://github.com/saarsena/theory-aide/blob/main/src/theory/nextMoves.ts): `src/theory/nextMoves.ts`

### Teaching website

- [Course and demos](https://github.com/saarsena/theory-aide/tree/main/site/src): `site/src`
- [Teaching examples](https://github.com/saarsena/theory-aide/blob/main/site/src/examples.ts): `site/src/examples.ts`
- [Playable note demos](https://github.com/saarsena/theory-aide/blob/main/site/src/lib/player.ts): `site/src/lib/player.ts`
- [Reading paths](https://github.com/saarsena/theory-aide/blob/main/site/_data/clusters.js): `site/_data/clusters.js`

### Other components

- **Music producer**
- **Ableton Live**
- **Course reader**
- **Web browser**

## Connections

- Music producer → Ableton Live: selects MIDI (evidence: `README.md`)
- Ableton Live → Commands and MIDI extraction: dispatches commands (evidence: `README.md`)
- Commands and MIDI extraction → Harmony and key analysis: analyzes harmony (evidence: `README.md`)
- Commands and MIDI extraction → Harmonic timeline: analyzes selections (evidence: `README.md`)
- Commands and MIDI extraction → Counterpoint checker: checks tracks (evidence: `README.md`)
- Commands and MIDI extraction → Composition dimensions: scores dimensions (evidence: `README.md`)
- Commands and MIDI extraction → Arrangement form: detects sections (evidence: `README.md`)
- Commands and MIDI extraction → Composition map: maps composition (evidence: `README.md`)
- Commands and MIDI extraction → Rhythm and phrasing: analyzes phrasing (evidence: `README.md`)
- Commands and MIDI extraction → Voicing and density: checks voicing (evidence: `README.md`)
- Commands and MIDI extraction → Timbre and dynamics: analyzes texture (evidence: `README.md`)
- Commands and MIDI extraction → Tone row analysis: checks tone rows (evidence: `README.md`)
- Commands and MIDI extraction → Next-move suggestions: builds suggestions (evidence: `src/extension.ts`)
- Harmony and key analysis → Scales and chord primitives: uses (evidence: `src/theory/analyzer.ts`)
- Harmony and key analysis → Theory data: uses (evidence: `src/theory/analyzer.ts`)
- Harmonic timeline → Scales and chord primitives: recognizes chords (evidence: `src/theory/timeline.ts`)
- Harmonic timeline → Harmony and key analysis: uses key analysis (evidence: `src/theory/timeline.ts`)
- Counterpoint checker → Scales and chord primitives: uses pitch classes (evidence: `src/theory/counterpoint.ts`)
- Composition dimensions → Harmonic timeline: scores analysis (evidence: `src/theory/dimensions.ts`)
- Arrangement form → Harmonic timeline: uses analysis (evidence: `src/theory/form.ts`)
- Composition map → Harmonic timeline: uses analysis (evidence: `src/theory/map.ts`)
- Rhythm and phrasing → Harmonic timeline: reads notes (evidence: `src/theory/rhythm.ts`)
- Voicing and density → Harmonic timeline: uses analysis (evidence: `src/theory/voicing.ts`)
- Timbre and dynamics → Harmonic timeline: uses analysis (evidence: `src/theory/timbre.ts`)
- Tone row analysis → Scales and chord primitives: uses theory (evidence: `src/theory/tonerow.ts`)
- Tone row analysis → Harmonic timeline: uses notes (evidence: `src/theory/tonerow.ts`)
- Next-move suggestions → Harmonic timeline: uses analysis (evidence: `src/theory/nextMoves.ts`)
- Course reader → Web browser: opens course (evidence: `README.md`)
- Web browser → Course and demos: runs demos (evidence: `site/src/main.ts`)
- Course and demos → Teaching examples: loads examples (evidence: `site/src/main.ts`)
- Course and demos → Playable note demos: plays examples (evidence: `site/src/main.ts`)
- Course and demos → Counterpoint checker: analyzes examples (evidence: `site/src/main.ts`)
- Course and demos → Reading paths: organizes lessons (evidence: `site/_data/clusters.js`)