# school-music/schoolmusic-backend architecture

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

- Interactive diagram: https://gitdiagram.com/school-music/schoolmusic-backend
- Repository: https://github.com/school-music/schoolmusic-backend

## Overview

This is a school-radio backend: users propose tracks and vote for break queues; moderation, playback, schedules and rankings support that core workflow. The graph preserves those domain areas and the central queue, broadcast and persistence layers. Source excerpts confirm queue behavior and startup registrations, but most controllers and supporting services were not sampled, so their internal calls are omitted rather than inferred.

Main entry points: [`schoolmusic-backend/Program.cs`](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Program.cs) (Application startup), [`schoolmusic-backend/Services/QueueService.cs`](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/QueueService.cs) (QueueService), [`schoolmusic-backend/Models/schoolmusicContext.cs`](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Models/schoolmusicContext.cs) (EF database context), [`schoolmusic-backend/Controllers`](https://github.com/school-music/schoolmusic-backend/tree/main/schoolmusic-backend/Controllers) (HTTP controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and moderation"]
  node_controllers["HTTP controllers"]
  node_rankings["Rankings<br/>[RankingsService.cs]"]
  node_program["Application startup<br/>[Program.cs]"]
end

subgraph group_queue["Queue and playback"]
  node_queuehub["QueueHub<br/>[QueueHub.cs]"]
  node_queueservice["QueueService<br/>[QueueService.cs]"]
  node_audio["Audio player"]
end

subgraph group_scheduling["Radio scheduling"]
  node_breakservice["Break service<br/>[BreakService.cs]"]
  node_breakscheduler["Break scheduler"]
  node_radiostatus["Radio status"]
  node_systemstatus["System status"]
  node_scheduleapi["Schedule and recess"]
end

subgraph group_catalog["Music catalog"]
  node_catalogapi["Track administration"]
  node_spotify["Spotify source"]
  node_songinterface["Song source contract"]
end

subgraph group_data["Persistence"]
  node_models["Radio domain models"]
  node_context["EF database context"]
end

node_listener(("Listener"))
node_moderator(("Moderator"))
node_mysql[("MySQL database")]
node_redis[("Redis")]

node_listener -->|"requests tracks"| node_controllers
node_moderator -->|"manages radio"| node_controllers
node_program -->|"maps routes"| node_controllers
node_program -->|"maps hub"| node_queuehub
node_program -->|"registers service"| node_queueservice
node_program -->|"registers service"| node_audio
node_program -->|"hosts scheduler"| node_breakscheduler
node_program -->|"registers source"| node_spotify
node_program -->|"configures database"| node_context
node_queueservice -->|"broadcasts updates"| node_queuehub
node_queueservice -->|"reads and writes"| node_context
node_queueservice -->|"stores proposals"| node_redis
node_context -->|"persists models"| node_mysql
node_queueservice -.->|"selects played tracks"| node_breakservice

click node_controllers "https://github.com/school-music/schoolmusic-backend/tree/main/schoolmusic-backend/Controllers"
click node_queuehub "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Hubs/QueueHub.cs"
click node_queueservice "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/QueueService.cs"
click node_audio "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/AudioPlayerService.cs"
click node_breakservice "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/BreakService.cs"
click node_breakscheduler "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/BreakSchedulerService.cs"
click node_radiostatus "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/RadioStatusService.cs"
click node_systemstatus "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/SystemStatusService.cs"
click node_scheduleapi "https://github.com/school-music/schoolmusic-backend/tree/main/schoolmusic-backend/Controllers"
click node_rankings "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/RankingsService.cs"
click node_catalogapi "https://github.com/school-music/schoolmusic-backend/tree/main/schoolmusic-backend/Controllers"
click node_spotify "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/SpotifySongSource.cs"
click node_songinterface "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/ISongSourceService.cs"
click node_models "https://github.com/school-music/schoolmusic-backend/tree/main/schoolmusic-backend/Models"
click node_context "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Models/schoolmusicContext.cs"
click node_program "https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Program.cs"

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_controllers,node_rankings,node_program toneBlue
class node_queuehub,node_queueservice,node_audio,node_mysql,node_redis toneAmber
class node_breakservice,node_breakscheduler,node_radiostatus,node_systemstatus,node_scheduleapi toneMint
class node_catalogapi,node_spotify,node_songinterface toneRose
class node_models,node_context,node_listener,node_moderator toneIndigo
```

## Components

### API and moderation

- [HTTP controllers](https://github.com/school-music/schoolmusic-backend/tree/main/schoolmusic-backend/Controllers): `schoolmusic-backend/Controllers`
- [Rankings](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/RankingsService.cs): `schoolmusic-backend/Services/RankingsService.cs`
- [Application startup](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Program.cs): `schoolmusic-backend/Program.cs`

### Queue and playback

- [QueueHub](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Hubs/QueueHub.cs): `schoolmusic-backend/Hubs/QueueHub.cs`
- [QueueService](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/QueueService.cs): `schoolmusic-backend/Services/QueueService.cs`
- [Audio player](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/AudioPlayerService.cs): `schoolmusic-backend/Services/AudioPlayerService.cs`

### Radio scheduling

- [Break service](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/BreakService.cs): `schoolmusic-backend/Services/BreakService.cs`
- [Break scheduler](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/BreakSchedulerService.cs): `schoolmusic-backend/Services/BreakSchedulerService.cs`
- [Radio status](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/RadioStatusService.cs): `schoolmusic-backend/Services/RadioStatusService.cs`
- [System status](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/SystemStatusService.cs): `schoolmusic-backend/Services/SystemStatusService.cs`
- [Schedule and recess](https://github.com/school-music/schoolmusic-backend/tree/main/schoolmusic-backend/Controllers): `schoolmusic-backend/Controllers`

### Music catalog

- [Track administration](https://github.com/school-music/schoolmusic-backend/tree/main/schoolmusic-backend/Controllers): `schoolmusic-backend/Controllers`
- [Spotify source](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/SpotifySongSource.cs): `schoolmusic-backend/Services/SpotifySongSource.cs`
- [Song source contract](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Services/ISongSourceService.cs): `schoolmusic-backend/Services/ISongSourceService.cs`

### Persistence

- [Radio domain models](https://github.com/school-music/schoolmusic-backend/tree/main/schoolmusic-backend/Models): `schoolmusic-backend/Models`
- [EF database context](https://github.com/school-music/schoolmusic-backend/blob/main/schoolmusic-backend/Models/schoolmusicContext.cs): `schoolmusic-backend/Models/schoolmusicContext.cs`

### Other components

- **Listener**
- **Moderator**
- **MySQL database**
- **Redis**

## Connections

- Listener → HTTP controllers: requests tracks
- Moderator → HTTP controllers: manages radio
- Application startup → HTTP controllers: maps routes (evidence: `schoolmusic-backend/Program.cs`)
- Application startup → QueueHub: maps hub (evidence: `schoolmusic-backend/Program.cs`)
- Application startup → QueueService: registers service (evidence: `schoolmusic-backend/Program.cs`)
- Application startup → Audio player: registers service (evidence: `schoolmusic-backend/Program.cs`)
- Application startup → Break scheduler: hosts scheduler (evidence: `schoolmusic-backend/Program.cs`)
- Application startup → Spotify source: registers source (evidence: `schoolmusic-backend/Program.cs`)
- Application startup → EF database context: configures database (evidence: `schoolmusic-backend/Program.cs`)
- QueueService → QueueHub: broadcasts updates (evidence: `schoolmusic-backend/Services/QueueService.cs`)
- QueueService → EF database context: reads and writes (evidence: `schoolmusic-backend/Services/QueueService.cs`)
- QueueService → Redis: stores proposals (evidence: `schoolmusic-backend/Services/QueueService.cs`)
- EF database context → MySQL database: persists models
- QueueService → Break service: selects played tracks
