# utsapoddar/cadence architecture

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

- Interactive diagram: https://gitdiagram.com/utsapoddar/cadence
- Repository: https://github.com/utsapoddar/cadence
- Video tour (about a minute): https://gitdiagram.com/utsapoddar/cadence/video

## Overview

Cadence is a static browser app for evidence-linked sound sessions. Users browse research-backed modules, inspect study and protocol details, and play a synthesized session; tinnitus playback additionally prompts for pitch calibration and saves that pitch locally. The README documents the catalog-to-interface workflow and synthesis modes; the sampled source confirms playback, calibration, and audio graph behavior. Some page initialization and catalog-loading details are unsampled, so those links are limited to documented relationships.

Main entry points: [`ui.js`](https://github.com/utsapoddar/cadence/blob/main/ui.js) (Cards and controls), [`tinnitus-matcher.js`](https://github.com/utsapoddar/cadence/blob/main/tinnitus-matcher.js) (Pitch matcher), [`audio-engine.js`](https://github.com/utsapoddar/cadence/blob/main/audio-engine.js) (Synthesis engine), [`index.html`](https://github.com/utsapoddar/cadence/blob/main/index.html) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["App interface"]
  node_shell["App shell<br/>[index.html]"]
  node_ui["Cards and controls<br/>[ui.js]"]
end

subgraph group_catalog["Module catalog"]
  node_catalog_data["Module data<br/>[frequencies.json]"]
  node_studies["Cited studies"]
end

subgraph group_playback["Audio playback"]
  node_audio["Synthesis engine<br/>[audio-engine.js]"]
end

subgraph group_calibration["Tinnitus calibration"]
  node_matcher["Pitch matcher"]
end

node_user(("Listener"))
node_web_audio["Web Audio API"]
node_local_storage[("Browser storage")]
node_gsap["GSAP animation"]

node_user -->|"browses and controls"| node_ui
node_shell -->|"loads interface"| node_ui
node_catalog_data -->|"supplies modules"| node_ui
node_ui -->|"opens citations"| node_studies
node_ui -->|"requests pitch"| node_matcher
node_matcher -->|"reads and saves"| node_local_storage
node_matcher -->|"plays probe tone"| node_web_audio
node_ui -->|"starts and stops"| node_audio
node_audio -->|"builds audio graph"| node_web_audio
node_ui -.->|"animates interface"| node_gsap

click node_shell "https://github.com/utsapoddar/cadence/blob/main/index.html"
click node_ui "https://github.com/utsapoddar/cadence/blob/main/ui.js"
click node_catalog_data "https://github.com/utsapoddar/cadence/blob/main/frequencies.json"
click node_audio "https://github.com/utsapoddar/cadence/blob/main/audio-engine.js"
click node_matcher "https://github.com/utsapoddar/cadence/blob/main/tinnitus-matcher.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_shell,node_ui toneBlue
class node_catalog_data,node_studies,node_local_storage toneAmber
class node_audio,node_web_audio toneMint
class node_matcher toneRose
class node_user,node_gsap toneIndigo
```

## Components

### App interface

- [App shell](https://github.com/utsapoddar/cadence/blob/main/index.html): `index.html`
- [Cards and controls](https://github.com/utsapoddar/cadence/blob/main/ui.js): `ui.js`

### Module catalog

- [Module data](https://github.com/utsapoddar/cadence/blob/main/frequencies.json): `frequencies.json`
- **Cited studies**

### Audio playback

- [Synthesis engine](https://github.com/utsapoddar/cadence/blob/main/audio-engine.js): `audio-engine.js`

### Tinnitus calibration

- [Pitch matcher](https://github.com/utsapoddar/cadence/blob/main/tinnitus-matcher.js): `tinnitus-matcher.js`

### Other components

- **Listener**
- **Web Audio API**
- **Browser storage**
- **GSAP animation**

## Connections

- Listener → Cards and controls: browses and controls
- App shell → Cards and controls: loads interface
- Module data → Cards and controls: supplies modules
- Cards and controls → Cited studies: opens citations
- Cards and controls → Pitch matcher: requests pitch
- Pitch matcher → Browser storage: reads and saves
- Pitch matcher → Web Audio API: plays probe tone
- Cards and controls → Synthesis engine: starts and stops
- Synthesis engine → Web Audio API: builds audio graph
- Cards and controls → GSAP animation: animates interface