# lorenaedwin08-hub/melodymate architecture

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

- Interactive diagram: https://gitdiagram.com/lorenaedwin08-hub/melodymate
- Repository: https://github.com/lorenaedwin08-hub/melodymate

## Overview

MelodyMate is an accessible, voice-guided music-learning web app. Learners choose a module, hear or explore notes, and can submit a singing recording for note, pitch, and timing feedback. The graph shows the documented web/API capabilities alongside the sampled singing-analysis implementation and standalone MIDI support. Browser-to-API wiring and any app-level MIDI workflow were not shown in the excerpts, so those links are marked unverified or omitted.

Main entry points: [`app/main.py`](https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/main.py) (FastAPI endpoints), [`app/static/index.html`](https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/static/index.html) (Accessible page), [`app/static/app.js`](https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/static/app.js) (Browser interface), [`core/notes.py`](https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/notes.py) (Note mapping)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learning experience"]
  node_browser["Browser interface<br/>[app.js]"]
  node_accessible_page["Accessible page<br/>[index.html]"]
  node_styling["Interface styling<br/>[style.css]"]
end

subgraph group_web["Web application"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_reference_audio["Reference audio<br/>[synth.py]"]
end

subgraph group_singing["Singing analysis"]
  node_pitch_tracking["Pitch tracking<br/>[pitch.py]"]
  node_note_segmentation["Note segmentation<br/>[segment.py]"]
  node_melody_comparison["Melody comparison<br/>[melody.py]"]
  node_pitch_feedback["Structured feedback<br/>[feedback.py]"]
  node_timing_feedback["Timing feedback<br/>[timing.py]"]
  node_simple_feedback["Spoken summary<br/>[simple_feedback.py]"]
end

subgraph group_music["Music domain"]
  node_note_mapping["Note mapping<br/>[notes.py]"]
end

subgraph group_input["Input support"]
  node_midi_input["MIDI reader<br/>[midi_input.py]"]
end

node_learner(("Learner"))
node_midi_keyboard(("MIDI keyboard"))

node_learner -.->|"uses"| node_browser
node_api -->|"serves page"| node_accessible_page
node_accessible_page -.->|"hosts behavior"| node_browser
node_accessible_page -.->|"uses styles"| node_styling
node_browser -.->|"requests learning data"| node_api
node_api -->|"generates reference"| node_reference_audio
node_api -->|"analyzes recording"| node_pitch_tracking
node_api -->|"segments pitches"| node_note_segmentation
node_api -->|"compares notes"| node_melody_comparison
node_api -->|"generates feedback"| node_pitch_feedback
node_api -->|"assesses timing"| node_timing_feedback
node_api -->|"summarizes results"| node_simple_feedback
node_api -->|"maps piano keys"| node_note_mapping
node_note_segmentation -->|"converts pitches"| node_note_mapping
node_pitch_feedback -->|"spells note names"| node_note_mapping
node_midi_keyboard -.->|"sends events"| node_midi_input

click node_browser "https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/static/app.js"
click node_accessible_page "https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/static/index.html"
click node_styling "https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/static/style.css"
click node_api "https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/main.py"
click node_reference_audio "https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/synth.py"
click node_pitch_tracking "https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/pitch.py"
click node_note_segmentation "https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/segment.py"
click node_melody_comparison "https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/melody.py"
click node_pitch_feedback "https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/feedback.py"
click node_timing_feedback "https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/timing.py"
click node_simple_feedback "https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/simple_feedback.py"
click node_note_mapping "https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/notes.py"
click node_midi_input "https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/midi_input.py"

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_browser,node_accessible_page,node_styling toneBlue
class node_api,node_reference_audio toneAmber
class node_pitch_tracking,node_note_segmentation,node_melody_comparison,node_pitch_feedback,node_timing_feedback,node_simple_feedback toneMint
class node_note_mapping toneRose
class node_midi_input,node_learner,node_midi_keyboard toneIndigo
```

## Components

### Learning experience

- [Browser interface](https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/static/app.js): `app/static/app.js`
- [Accessible page](https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/static/index.html): `app/static/index.html`
- [Interface styling](https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/static/style.css): `app/static/style.css`

### Web application

- [FastAPI endpoints](https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/main.py): `app/main.py`
- [Reference audio](https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/synth.py): `core/synth.py`

### Singing analysis

- [Pitch tracking](https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/pitch.py): `core/pitch.py`
- [Note segmentation](https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/segment.py): `core/segment.py`
- [Melody comparison](https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/melody.py): `core/melody.py`
- [Structured feedback](https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/feedback.py): `core/feedback.py`
- [Timing feedback](https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/timing.py): `core/timing.py`
- [Spoken summary](https://github.com/lorenaedwin08-hub/melodymate/blob/main/app/simple_feedback.py): `app/simple_feedback.py`

### Music domain

- [Note mapping](https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/notes.py): `core/notes.py`

### Input support

- [MIDI reader](https://github.com/lorenaedwin08-hub/melodymate/blob/main/core/midi_input.py): `core/midi_input.py`

### Other components

- **Learner**
- **MIDI keyboard**

## Connections

- Learner → Browser interface: uses
- FastAPI endpoints → Accessible page: serves page (evidence: `app/main.py`)
- Accessible page → Browser interface: hosts behavior
- Accessible page → Interface styling: uses styles
- Browser interface → FastAPI endpoints: requests learning data
- FastAPI endpoints → Reference audio: generates reference (evidence: `app/main.py`)
- FastAPI endpoints → Pitch tracking: analyzes recording (evidence: `app/main.py`)
- FastAPI endpoints → Note segmentation: segments pitches (evidence: `app/main.py`)
- FastAPI endpoints → Melody comparison: compares notes (evidence: `app/main.py`)
- FastAPI endpoints → Structured feedback: generates feedback (evidence: `app/main.py`)
- FastAPI endpoints → Timing feedback: assesses timing (evidence: `app/main.py`)
- FastAPI endpoints → Spoken summary: summarizes results (evidence: `app/main.py`)
- FastAPI endpoints → Note mapping: maps piano keys (evidence: `app/main.py`)
- Note segmentation → Note mapping: converts pitches (evidence: `core/segment.py`)
- Structured feedback → Note mapping: spells note names (evidence: `core/feedback.py`)
- MIDI keyboard → MIDI reader: sends events