# jopaferreira/pei-mta architecture

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

- Interactive diagram: https://gitdiagram.com/jopaferreira/pei-mta
- Repository: https://github.com/jopaferreira/pei-mta

## Overview

Musical Theory Trainer is a browser-based practice app: learners choose a training filter, request an interval, scale/mode, or key-signature exercise, answer it, and receive feedback and a theoretical explanation. Registered users can review per-topic and daily performance; guest use is also supported. The graph reflects documented API calls and sampled backend ownership. Frontend rendering/audio libraries and some dashboard behavior are described in the README or excerpts, but unsampled implementation details are not inferred.

Main entry points: [`src/frontend/app.js`](https://github.com/jopaferreira/pei-mta/blob/main/src/frontend/app.js) (Practice interface), [`src/backend/main.py`](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py) (Exercise API), [`src/backend/models.py`](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/models.py) (Attempt history), [`src/backend/music_logic.py`](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/music_logic.py) (Interval generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_practice["Musical practice"]
  node_spa["Practice interface<br/>[app.js]"]
  node_exercise_api["Exercise API<br/>[main.py]"]
  node_intervals["Interval generator<br/>[music_logic.py]"]
  node_scales["Scale and mode generator<br/>[music_logic.py]"]
  node_keys["Key signature generator<br/>[music_logic.py]"]
  node_notation["Staff notation<br/>[app.js]"]
  node_audio["Audio playback<br/>[app.js]"]
  node_explanations["Answer explanations<br/>[music_logic.py]"]
end

subgraph group_accounts["Accounts and progress"]
  node_auth_ui["Login and guest mode<br/>[app.js]"]
  node_auth_api["Registration and login<br/>[main.py]"]
  node_attempt_api["Attempt recording<br/>[main.py]"]
  node_dashboard_api["Metrics aggregation<br/>[main.py]"]
  node_dashboard_ui["Progress dashboard<br/>[app.js]"]
  node_user_data[("User profiles<br/>[models.py]")]
  node_attempt_data[("Attempt history<br/>[models.py]")]
end

subgraph group_platform["Application platform"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_static_files["Static frontend<br/>[main.py]"]
end

node_learner(("Learner"))
node_browser(("Browser"))
node_sqlite[("SQLite")]

node_learner -->|"uses"| node_spa
node_spa -->|"submits credentials"| node_auth_api
node_auth_api -->|"reads and writes"| node_user_data
node_spa -->|"requests exercise"| node_exercise_api
node_exercise_api -->|"generates interval"| node_intervals
node_exercise_api -->|"generates scale"| node_scales
node_exercise_api -->|"generates key"| node_keys
node_exercise_api -->|"returns exercise"| node_spa
node_spa -->|"renders staff"| node_notation
node_spa -->|"plays notes"| node_audio
node_learner -->|"answers"| node_spa
node_spa -->|"shows feedback"| node_explanations
node_spa -->|"records attempt"| node_attempt_api
node_attempt_api -->|"writes attempt"| node_attempt_data
node_spa -->|"requests metrics"| node_dashboard_api
node_dashboard_api -->|"reads history"| node_attempt_data
node_spa -->|"displays progress"| node_dashboard_ui
node_spa -->|"calls API"| node_fastapi
node_fastapi -->|"serves frontend"| node_static_files
node_user_data -->|"persists in"| node_sqlite
node_attempt_data -->|"persists in"| node_sqlite
node_browser -.->|"loads"| node_spa

click node_spa "https://github.com/jopaferreira/pei-mta/blob/main/src/frontend/app.js"
click node_exercise_api "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py"
click node_intervals "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/music_logic.py"
click node_scales "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/music_logic.py"
click node_keys "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/music_logic.py"
click node_notation "https://github.com/jopaferreira/pei-mta/blob/main/src/frontend/app.js"
click node_audio "https://github.com/jopaferreira/pei-mta/blob/main/src/frontend/app.js"
click node_explanations "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/music_logic.py"
click node_auth_ui "https://github.com/jopaferreira/pei-mta/blob/main/src/frontend/app.js"
click node_auth_api "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py"
click node_attempt_api "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py"
click node_dashboard_api "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py"
click node_dashboard_ui "https://github.com/jopaferreira/pei-mta/blob/main/src/frontend/app.js"
click node_user_data "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/models.py"
click node_attempt_data "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/models.py"
click node_fastapi "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py"
click node_static_files "https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.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_spa,node_exercise_api,node_intervals,node_scales,node_keys,node_notation,node_audio,node_explanations,node_browser toneBlue
class node_auth_ui,node_auth_api,node_attempt_api,node_dashboard_api,node_dashboard_ui,node_user_data,node_attempt_data,node_sqlite toneAmber
class node_fastapi,node_static_files toneMint
class node_learner toneIndigo
```

## Components

### Musical practice

- [Practice interface](https://github.com/jopaferreira/pei-mta/blob/main/src/frontend/app.js): `src/frontend/app.js`
- [Exercise API](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py): `src/backend/main.py`
- [Interval generator](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/music_logic.py): `src/backend/music_logic.py`
- [Scale and mode generator](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/music_logic.py): `src/backend/music_logic.py`
- [Key signature generator](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/music_logic.py): `src/backend/music_logic.py`
- [Staff notation](https://github.com/jopaferreira/pei-mta/blob/main/src/frontend/app.js): `src/frontend/app.js`
- [Audio playback](https://github.com/jopaferreira/pei-mta/blob/main/src/frontend/app.js): `src/frontend/app.js`
- [Answer explanations](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/music_logic.py): `src/backend/music_logic.py`

### Accounts and progress

- [Login and guest mode](https://github.com/jopaferreira/pei-mta/blob/main/src/frontend/app.js): `src/frontend/app.js`
- [Registration and login](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py): `src/backend/main.py`
- [Attempt recording](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py): `src/backend/main.py`
- [Metrics aggregation](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py): `src/backend/main.py`
- [Progress dashboard](https://github.com/jopaferreira/pei-mta/blob/main/src/frontend/app.js): `src/frontend/app.js`
- [User profiles](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/models.py): `src/backend/models.py`
- [Attempt history](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/models.py): `src/backend/models.py`

### Application platform

- [FastAPI app](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py): `src/backend/main.py`
- [Static frontend](https://github.com/jopaferreira/pei-mta/blob/main/src/backend/main.py): `src/backend/main.py`

### Other components

- **Learner**
- **Browser**
- **SQLite**

## Connections

- Learner → Practice interface: uses (evidence: `README.md`)
- Practice interface → Registration and login: submits credentials (evidence: `src/frontend/app.js`)
- Registration and login → User profiles: reads and writes (evidence: `src/backend/main.py`)
- Practice interface → Exercise API: requests exercise (evidence: `src/frontend/app.js`)
- Exercise API → Interval generator: generates interval (evidence: `src/backend/main.py`)
- Exercise API → Scale and mode generator: generates scale (evidence: `src/backend/main.py`)
- Exercise API → Key signature generator: generates key (evidence: `src/backend/main.py`)
- Exercise API → Practice interface: returns exercise (evidence: `src/frontend/app.js`)
- Practice interface → Staff notation: renders staff (evidence: `src/frontend/app.js`)
- Practice interface → Audio playback: plays notes (evidence: `src/frontend/app.js`)
- Learner → Practice interface: answers (evidence: `src/frontend/app.js`)
- Practice interface → Answer explanations: shows feedback (evidence: `README.md`)
- Practice interface → Attempt recording: records attempt (evidence: `src/frontend/app.js`)
- Attempt recording → Attempt history: writes attempt (evidence: `src/backend/main.py`)
- Practice interface → Metrics aggregation: requests metrics (evidence: `src/frontend/app.js`)
- Metrics aggregation → Attempt history: reads history (evidence: `src/backend/main.py`)
- Practice interface → Progress dashboard: displays progress (evidence: `README.md`)
- Practice interface → FastAPI app: calls API (evidence: `src/frontend/app.js`)
- FastAPI app → Static frontend: serves frontend (evidence: `src/backend/main.py`)
- User profiles → SQLite: persists in (evidence: `src/backend/models.py`)
- Attempt history → SQLite: persists in (evidence: `src/backend/models.py`)
- Browser → Practice interface: loads (evidence: `README.md`)
