# khvostiv/music-practice-management-system architecture

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

- Interactive diagram: https://gitdiagram.com/khvostiv/music-practice-management-system
- Repository: https://github.com/khvostiv/music-practice-management-system
- Video tour (about a minute): https://gitdiagram.com/khvostiv/music-practice-management-system/video

## Overview

Piano Piece Tracker is a Spring Boot app for maintaining a personal piano repertoire and practice history. A user logs in or registers, then manages pieces and sheet-music PDFs, records timed practice, creates learning goals, and views dashboard totals. Controllers own the web/API entry points; services implement domain operations and repositories persist user-scoped records. The README documents optional S3 storage. Some controllers and integrations are unsampled, so uncertain wiring is shown only as unverified; the graph does not assume their implementation details.

Main entry points: [`src/main/java/ca/sheridancollege/khvostiv/services/PianoPieceService.java`](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/PianoPieceService.java) (Piece management), [`src/main/java/ca/sheridancollege/khvostiv/services/LearningGoalService.java`](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/LearningGoalService.java) (Goal tracking), [`src/main/java/ca/sheridancollege/khvostiv/services/PracticeSessionService.java`](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/PracticeSessionService.java) (Session tracking), [`src/main/java/ca/sheridancollege/khvostiv/controllers/HomeController.java`](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/HomeController.java) (Home and pieces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and access"]
  node_home["Home and pieces"]
  node_authapi["Authentication API"]
  node_authsvc["Authentication"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_jwtfilter["JWT filter"]
  node_security["Security config"]
end

subgraph group_domain["Repertoire and goals"]
  node_pieceapi["Piece API"]
  node_piecesvc["Piece management"]
  node_goalsapi["Learning goals API"]
  node_goalsvc["Goal tracking"]
end

subgraph group_practice["Practice and insights"]
  node_practiceapi["Practice endpoints"]
  node_practicepage["Practice page"]
  node_practicesvc["Session tracking"]
  node_dashboard["Dashboard metrics"]
  node_dashboardapi["Dashboard page"]
end

subgraph group_persistence["Persistence and files"]
  node_pieces[("Piece records")]
  node_sessions[("Session records")]
  node_goals[("Goal records")]
  node_users[("User records")]
  node_composers[("Composer records")]
  node_sheetmusic["Sheet music storage"]
end

node_user(("Piano student"))
node_s3[("Amazon S3")]

node_user -->|"uses"| node_home
node_home -->|"authenticates"| node_authsvc
node_authapi -->|"delegates to"| node_authsvc
node_authsvc -->|"creates token"| node_jwt
node_jwtfilter -->|"validates token"| node_jwt
node_security -.->|"configures"| node_jwtfilter
node_home -->|"manages pieces"| node_piecesvc
node_home -->|"looks up"| node_composers
node_home -->|"stores and serves"| node_sheetmusic
node_pieceapi -->|"delegates to"| node_piecesvc
node_piecesvc -->|"reads and writes"| node_pieces
node_piecesvc -->|"loads owner"| node_users
node_piecesvc -->|"deletes piece goals"| node_goals
node_piecesvc -->|"deletes piece sessions"| node_sessions
node_goalsapi -->|"delegates to"| node_goalsvc
node_goalsvc -->|"reads and writes"| node_goals
node_goalsvc -->|"loads target piece"| node_pieces
node_goalsvc -->|"measures practice"| node_sessions
node_goalsvc -->|"loads owner"| node_users
node_practiceapi -->|"delegates to"| node_practicesvc
node_practicepage -->|"records sessions"| node_practicesvc
node_practicesvc -->|"reads and writes"| node_sessions
node_practicesvc -->|"loads associated piece"| node_pieces
node_practicesvc -->|"loads owner"| node_users
node_dashboardapi -.->|"loads metrics"| node_dashboard
node_dashboard -->|"gets pieces"| node_piecesvc
node_dashboard -->|"gets sessions"| node_practicesvc
node_dashboard -->|"gets goals"| node_goalsvc
node_sheetmusic -.->|"may store PDFs"| node_s3

click node_home "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/HomeController.java"
click node_authapi "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/AuthenticationController.java"
click node_authsvc "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/AuthenticationService.java"
click node_jwt "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/JwtService.java"
click node_jwtfilter "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/config/JwtAuthenticationFilter.java"
click node_security "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/config/SecurityConfig.java"
click node_pieceapi "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/PianoPieceController.java"
click node_piecesvc "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/PianoPieceService.java"
click node_goalsapi "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/LearningGoalController.java"
click node_goalsvc "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/LearningGoalService.java"
click node_practiceapi "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/PracticeSessionController.java"
click node_practicepage "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/PracticePageController.java"
click node_practicesvc "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/PracticeSessionService.java"
click node_dashboard "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/DashboardService.java"
click node_dashboardapi "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/DashboardController.java"
click node_pieces "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/repositories/PianoPieceRepository.java"
click node_sessions "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/repositories/PracticeSessionRepository.java"
click node_goals "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/repositories/LearningGoalRepository.java"
click node_users "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/repositories/UserRepository.java"
click node_composers "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/repositories/ComposerRepository.java"
click node_sheetmusic "https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/SheetMusicService.java"

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_home,node_authapi,node_authsvc,node_jwt,node_jwtfilter,node_security toneBlue
class node_pieceapi,node_piecesvc,node_goalsapi,node_goalsvc,node_s3 toneAmber
class node_practiceapi,node_practicepage,node_practicesvc,node_dashboard,node_dashboardapi toneMint
class node_pieces,node_sessions,node_goals,node_users,node_composers,node_sheetmusic toneRose
class node_user toneIndigo
```

## Components

### Web and access

- [Home and pieces](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/HomeController.java): `src/main/java/ca/sheridancollege/khvostiv/controllers/HomeController.java`
- [Authentication API](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/AuthenticationController.java): `src/main/java/ca/sheridancollege/khvostiv/controllers/AuthenticationController.java`
- [Authentication](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/AuthenticationService.java): `src/main/java/ca/sheridancollege/khvostiv/services/AuthenticationService.java`
- [JWT service](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/JwtService.java): `src/main/java/ca/sheridancollege/khvostiv/services/JwtService.java`
- [JWT filter](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/config/JwtAuthenticationFilter.java): `src/main/java/ca/sheridancollege/khvostiv/config/JwtAuthenticationFilter.java`
- [Security config](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/config/SecurityConfig.java): `src/main/java/ca/sheridancollege/khvostiv/config/SecurityConfig.java`

### Repertoire and goals

- [Piece API](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/PianoPieceController.java): `src/main/java/ca/sheridancollege/khvostiv/controllers/PianoPieceController.java`
- [Piece management](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/PianoPieceService.java): `src/main/java/ca/sheridancollege/khvostiv/services/PianoPieceService.java`
- [Learning goals API](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/LearningGoalController.java): `src/main/java/ca/sheridancollege/khvostiv/controllers/LearningGoalController.java`
- [Goal tracking](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/LearningGoalService.java): `src/main/java/ca/sheridancollege/khvostiv/services/LearningGoalService.java`

### Practice and insights

- [Practice endpoints](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/PracticeSessionController.java): `src/main/java/ca/sheridancollege/khvostiv/controllers/PracticeSessionController.java`
- [Practice page](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/PracticePageController.java): `src/main/java/ca/sheridancollege/khvostiv/controllers/PracticePageController.java`
- [Session tracking](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/PracticeSessionService.java): `src/main/java/ca/sheridancollege/khvostiv/services/PracticeSessionService.java`
- [Dashboard metrics](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/DashboardService.java): `src/main/java/ca/sheridancollege/khvostiv/services/DashboardService.java`
- [Dashboard page](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/controllers/DashboardController.java): `src/main/java/ca/sheridancollege/khvostiv/controllers/DashboardController.java`

### Persistence and files

- [Piece records](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/repositories/PianoPieceRepository.java): `src/main/java/ca/sheridancollege/khvostiv/repositories/PianoPieceRepository.java`
- [Session records](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/repositories/PracticeSessionRepository.java): `src/main/java/ca/sheridancollege/khvostiv/repositories/PracticeSessionRepository.java`
- [Goal records](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/repositories/LearningGoalRepository.java): `src/main/java/ca/sheridancollege/khvostiv/repositories/LearningGoalRepository.java`
- [User records](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/repositories/UserRepository.java): `src/main/java/ca/sheridancollege/khvostiv/repositories/UserRepository.java`
- [Composer records](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/repositories/ComposerRepository.java): `src/main/java/ca/sheridancollege/khvostiv/repositories/ComposerRepository.java`
- [Sheet music storage](https://github.com/khvostiv/music-practice-management-system/blob/main/src/main/java/ca/sheridancollege/khvostiv/services/SheetMusicService.java): `src/main/java/ca/sheridancollege/khvostiv/services/SheetMusicService.java`

### Other components

- **Piano student**
- **Amazon S3**

## Connections

- Piano student → Home and pieces: uses (evidence: `README.md`)
- Home and pieces → Authentication: authenticates (evidence: `src/main/java/ca/sheridancollege/khvostiv/controllers/HomeController.java`)
- Authentication API → Authentication: delegates to (evidence: `src/main/java/ca/sheridancollege/khvostiv/controllers/AuthenticationController.java`)
- Authentication → JWT service: creates token (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/AuthenticationService.java`)
- JWT filter → JWT service: validates token (evidence: `src/main/java/ca/sheridancollege/khvostiv/config/JwtAuthenticationFilter.java`)
- Security config → JWT filter: configures (evidence: `src/main/java/ca/sheridancollege/khvostiv/config/SecurityConfig.java`)
- Home and pieces → Piece management: manages pieces (evidence: `src/main/java/ca/sheridancollege/khvostiv/controllers/HomeController.java`)
- Home and pieces → Composer records: looks up (evidence: `src/main/java/ca/sheridancollege/khvostiv/controllers/HomeController.java`)
- Home and pieces → Sheet music storage: stores and serves (evidence: `src/main/java/ca/sheridancollege/khvostiv/controllers/HomeController.java`)
- Piece API → Piece management: delegates to (evidence: `src/main/java/ca/sheridancollege/khvostiv/controllers/PianoPieceController.java`)
- Piece management → Piece records: reads and writes (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/PianoPieceService.java`)
- Piece management → User records: loads owner (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/PianoPieceService.java`)
- Piece management → Goal records: deletes piece goals (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/PianoPieceService.java`)
- Piece management → Session records: deletes piece sessions (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/PianoPieceService.java`)
- Learning goals API → Goal tracking: delegates to (evidence: `src/main/java/ca/sheridancollege/khvostiv/controllers/LearningGoalController.java`)
- Goal tracking → Goal records: reads and writes (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/LearningGoalService.java`)
- Goal tracking → Piece records: loads target piece (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/LearningGoalService.java`)
- Goal tracking → Session records: measures practice (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/LearningGoalService.java`)
- Goal tracking → User records: loads owner (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/LearningGoalService.java`)
- Practice endpoints → Session tracking: delegates to (evidence: `src/main/java/ca/sheridancollege/khvostiv/controllers/PracticeSessionController.java`)
- Practice page → Session tracking: records sessions (evidence: `src/main/java/ca/sheridancollege/khvostiv/controllers/PracticePageController.java`)
- Session tracking → Session records: reads and writes (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/PracticeSessionService.java`)
- Session tracking → Piece records: loads associated piece (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/PracticeSessionService.java`)
- Session tracking → User records: loads owner (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/PracticeSessionService.java`)
- Dashboard page → Dashboard metrics: loads metrics (evidence: `src/main/java/ca/sheridancollege/khvostiv/controllers/DashboardController.java`)
- Dashboard metrics → Piece management: gets pieces (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/DashboardService.java`)
- Dashboard metrics → Session tracking: gets sessions (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/DashboardService.java`)
- Dashboard metrics → Goal tracking: gets goals (evidence: `src/main/java/ca/sheridancollege/khvostiv/services/DashboardService.java`)
- Sheet music storage → Amazon S3: may store PDFs (evidence: `README.md`)