# tt8747430-png/piano-trainer architecture

> Architecture diagram of the GitHub repository tt8747430-png/piano-trainer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tt8747430-png/piano-trainer
- Repository: https://github.com/tt8747430-png/piano-trainer

## Overview

Piano Trainer is an installable, offline-capable piano-learning app, available in English and Russian. Learners follow a path, explore the chords and scales songs require, then practise with a player that can play along, step through music, or wait for input. The app also includes lessons, quizzes, trainer exercises, song editing, and pattern management. The graph follows the documented workflow and sampled app wiring; unsampled feature links are omitted rather than inferred.

Main entry points: [`src/app/App.tsx`](https://github.com/tt8747430-png/piano-trainer/blob/main/src/app/App.tsx) (App Providers), [`src/app/router.tsx`](https://github.com/tt8747430-png/piano-trainer/blob/main/src/app/router.tsx) (Route Dispatch), [`src/main.tsx`](https://github.com/tt8747430-png/piano-trainer/blob/main/src/main.tsx) (App Bootstrap), [`src/app/routes/explorer-search.ts`](https://github.com/tt8747430-png/piano-trainer/blob/main/src/app/routes/explorer-search.ts) (Music Explorers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_entry["App Bootstrap<br/>[main.tsx]"]
  node_app["App Providers<br/>[App.tsx]"]
  node_router["Route Dispatch<br/>[router.tsx]"]
end

subgraph group_learn["Learning Content"]
  node_path["Learning Path"]
  node_lessons["Lessons"]
  node_songs["Songs and Pieces"]
end

subgraph group_explore["Music Exploration"]
  node_explorers["Music Explorers<br/>[explorer-search.ts]"]
  node_music["Music Theory"]
  node_patterns["Pattern Library"]
end

subgraph group_practice["Practice and Creation"]
  node_practice["Practice Modes"]
  node_trainer["Trainer Exercises"]
  node_player["Practice Player"]
  node_editor["Score Editor"]
end

subgraph group_state["Learner State and Services"]
  node_progress[("Learning Progress")]
  node_settings[("Settings")]
  node_takes[("Recorded Takes")]
  node_audio["Audio Services"]
  node_midi["MIDI Services"]
  node_storage[("Browser Storage<br/>[safe-storage.ts]")]
end

node_learner(("Learner"))

node_learner -->|"learn piano"| node_entry
node_entry -->|"renders"| node_app
node_app -->|"provides routes"| node_router
node_router -->|"routes to"| node_path
node_router -->|"routes to"| node_lessons
node_router -->|"routes to"| node_songs
node_router -->|"reads search"| node_explorers
node_router -->|"routes to"| node_player
node_router -->|"routes to"| node_trainer
node_router -->|"routes to"| node_editor
node_explorers -->|"uses theory"| node_music
node_explorers -->|"validates patterns"| node_patterns
node_entry -->|"creates store"| node_patterns
node_entry -->|"creates store"| node_songs
node_entry -->|"creates store"| node_progress
node_entry -->|"creates store"| node_settings
node_entry -->|"creates store"| node_takes
node_app -->|"provides store"| node_settings
node_app -->|"provides store"| node_progress
node_app -->|"provides store"| node_patterns
node_app -->|"provides store"| node_songs
node_app -->|"provides store"| node_takes
node_player -->|"plays through"| node_audio
node_trainer -->|"uses theory"| node_music
node_trainer -.->|"tracks mastery"| node_progress
node_editor -.->|"manages takes"| node_takes
node_app -.->|"reconnects"| node_midi
node_settings -.->|"persists settings"| node_storage

click node_entry "https://github.com/tt8747430-png/piano-trainer/blob/main/src/main.tsx"
click node_app "https://github.com/tt8747430-png/piano-trainer/blob/main/src/app/App.tsx"
click node_router "https://github.com/tt8747430-png/piano-trainer/blob/main/src/app/router.tsx"
click node_path "https://github.com/tt8747430-png/piano-trainer/tree/main/src/pages/path"
click node_lessons "https://github.com/tt8747430-png/piano-trainer/tree/main/src/pages/learn"
click node_songs "https://github.com/tt8747430-png/piano-trainer/tree/main/src/entities/piece"
click node_explorers "https://github.com/tt8747430-png/piano-trainer/blob/main/src/app/routes/explorer-search.ts"
click node_music "https://github.com/tt8747430-png/piano-trainer/tree/main/src/shared/lib/music"
click node_patterns "https://github.com/tt8747430-png/piano-trainer/tree/main/src/entities/pattern"
click node_practice "https://github.com/tt8747430-png/piano-trainer/tree/main/src/features/practice"
click node_trainer "https://github.com/tt8747430-png/piano-trainer/tree/main/src/features/trainer"
click node_player "https://github.com/tt8747430-png/piano-trainer/tree/main/src/pages/player"
click node_editor "https://github.com/tt8747430-png/piano-trainer/tree/main/src/pages/score-editor"
click node_progress "https://github.com/tt8747430-png/piano-trainer/tree/main/src/entities/progress"
click node_settings "https://github.com/tt8747430-png/piano-trainer/tree/main/src/entities/settings"
click node_takes "https://github.com/tt8747430-png/piano-trainer/tree/main/src/entities/take"
click node_audio "https://github.com/tt8747430-png/piano-trainer/tree/main/src/shared/api/audio"
click node_midi "https://github.com/tt8747430-png/piano-trainer/tree/main/src/shared/api/midi"
click node_storage "https://github.com/tt8747430-png/piano-trainer/blob/main/src/shared/lib/safe-storage.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_entry,node_app,node_router toneBlue
class node_path,node_lessons,node_songs toneAmber
class node_explorers,node_music,node_patterns toneMint
class node_practice,node_trainer,node_player,node_editor toneRose
class node_progress,node_settings,node_takes,node_audio,node_midi,node_storage,node_learner toneIndigo
```

## Components

### Application

- [App Bootstrap](https://github.com/tt8747430-png/piano-trainer/blob/main/src/main.tsx): `src/main.tsx`
- [App Providers](https://github.com/tt8747430-png/piano-trainer/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Route Dispatch](https://github.com/tt8747430-png/piano-trainer/blob/main/src/app/router.tsx): `src/app/router.tsx`

### Learning Content

- [Learning Path](https://github.com/tt8747430-png/piano-trainer/tree/main/src/pages/path): `src/pages/path`
- [Lessons](https://github.com/tt8747430-png/piano-trainer/tree/main/src/pages/learn): `src/pages/learn`
- [Songs and Pieces](https://github.com/tt8747430-png/piano-trainer/tree/main/src/entities/piece): `src/entities/piece`

### Music Exploration

- [Music Explorers](https://github.com/tt8747430-png/piano-trainer/blob/main/src/app/routes/explorer-search.ts): `src/app/routes/explorer-search.ts`
- [Music Theory](https://github.com/tt8747430-png/piano-trainer/tree/main/src/shared/lib/music): `src/shared/lib/music`
- [Pattern Library](https://github.com/tt8747430-png/piano-trainer/tree/main/src/entities/pattern): `src/entities/pattern`

### Practice and Creation

- [Practice Modes](https://github.com/tt8747430-png/piano-trainer/tree/main/src/features/practice): `src/features/practice`
- [Trainer Exercises](https://github.com/tt8747430-png/piano-trainer/tree/main/src/features/trainer): `src/features/trainer`
- [Practice Player](https://github.com/tt8747430-png/piano-trainer/tree/main/src/pages/player): `src/pages/player`
- [Score Editor](https://github.com/tt8747430-png/piano-trainer/tree/main/src/pages/score-editor): `src/pages/score-editor`

### Learner State and Services

- [Learning Progress](https://github.com/tt8747430-png/piano-trainer/tree/main/src/entities/progress): `src/entities/progress`
- [Settings](https://github.com/tt8747430-png/piano-trainer/tree/main/src/entities/settings): `src/entities/settings`
- [Recorded Takes](https://github.com/tt8747430-png/piano-trainer/tree/main/src/entities/take): `src/entities/take`
- [Audio Services](https://github.com/tt8747430-png/piano-trainer/tree/main/src/shared/api/audio): `src/shared/api/audio`
- [MIDI Services](https://github.com/tt8747430-png/piano-trainer/tree/main/src/shared/api/midi): `src/shared/api/midi`
- [Browser Storage](https://github.com/tt8747430-png/piano-trainer/blob/main/src/shared/lib/safe-storage.ts): `src/shared/lib/safe-storage.ts`

### Other components

- **Learner**

## Connections

- Learner → App Bootstrap: learn piano (evidence: `README.md`)
- App Bootstrap → App Providers: renders (evidence: `src/main.tsx`)
- App Providers → Route Dispatch: provides routes (evidence: `src/app/App.tsx`)
- Route Dispatch → Learning Path: routes to (evidence: `src/app/router.tsx`)
- Route Dispatch → Lessons: routes to (evidence: `src/app/router.tsx`)
- Route Dispatch → Songs and Pieces: routes to (evidence: `src/app/router.tsx`)
- Route Dispatch → Music Explorers: reads search (evidence: `src/app/router.tsx`)
- Route Dispatch → Practice Player: routes to (evidence: `src/app/router.tsx`)
- Route Dispatch → Trainer Exercises: routes to (evidence: `src/app/router.tsx`)
- Route Dispatch → Score Editor: routes to (evidence: `src/app/router.tsx`)
- Music Explorers → Music Theory: uses theory (evidence: `src/app/routes/explorer-search.ts`)
- Music Explorers → Pattern Library: validates patterns (evidence: `src/app/routes/explorer-search.ts`)
- App Bootstrap → Pattern Library: creates store (evidence: `src/main.tsx`)
- App Bootstrap → Songs and Pieces: creates store (evidence: `src/main.tsx`)
- App Bootstrap → Learning Progress: creates store (evidence: `src/main.tsx`)
- App Bootstrap → Settings: creates store (evidence: `src/main.tsx`)
- App Bootstrap → Recorded Takes: creates store (evidence: `src/main.tsx`)
- App Providers → Settings: provides store (evidence: `src/app/App.tsx`)
- App Providers → Learning Progress: provides store (evidence: `src/app/App.tsx`)
- App Providers → Pattern Library: provides store (evidence: `src/app/App.tsx`)
- App Providers → Songs and Pieces: provides store (evidence: `src/app/App.tsx`)
- App Providers → Recorded Takes: provides store (evidence: `src/app/App.tsx`)
- Practice Player → Audio Services: plays through
- Trainer Exercises → Music Theory: uses theory (evidence: `src/features/trainer/draw.ts`)
- Trainer Exercises → Learning Progress: tracks mastery
- Score Editor → Recorded Takes: manages takes
- App Providers → MIDI Services: reconnects
- Settings → Browser Storage: persists settings
