# wa1o/radio-campus architecture

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

- Interactive diagram: https://gitdiagram.com/wa1o/radio-campus
- Repository: https://github.com/wa1o/radio-campus

## Overview

Radio Campus lets campus listeners vote on two context-selected songs, while a public screen plays the winning music and scheduled announcements. Administrators manage the catalog, rules, events, announcements, live controls, and settings. The server’s Director coordinates station state; contextual selection, catalog tools, and persistence support it. The README documents optional YouTube playlist import and AI narration. Some page and route implementations were not excerpted, so uncertain interactions are omitted or marked unverified.

Main entry points: [`server/src/routes/admin.js`](https://github.com/wa1o/radio-campus/blob/main/server/src/routes/admin.js) (Admin API), [`server/src/schema.sql`](https://github.com/wa1o/radio-campus/blob/main/server/src/schema.sql) (PostgreSQL), [`server/src/index.js`](https://github.com/wa1o/radio-campus/blob/main/server/src/index.js) (HTTP and sockets), [`server/src/director.js`](https://github.com/wa1o/radio-campus/blob/main/server/src/director.js) (Station director)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Campus interfaces"]
  node_screen["Public screen<br/>[Screen.jsx]"]
  node_voting["Mobile voting<br/>[Vote.jsx]"]
  node_adminui["Admin panel<br/>[Admin.jsx]"]
  node_cliententry["Route entry<br/>[main.jsx]"]
  node_client_socket["Socket client<br/>[socket.jsx]"]
  node_speech["Browser speech<br/>[speech.js]"]
end

subgraph group_runtime["Station runtime"]
  node_server["HTTP and sockets<br/>[index.js]"]
  node_director["Station director<br/>[director.js]"]
  node_publicroutes["Public API<br/>[public.js]"]
  node_auth["Admin authentication<br/>[auth.js]"]
  node_database[("PostgreSQL<br/>[schema.sql]")]
  node_dj["Announcer text<br/>[dj.js]"]
end

subgraph group_catalog["Catalog and context"]
  node_selection["Context selection<br/>[context.js]"]
  node_songtools["Song tools<br/>[songtools.js]"]
  node_youtube["Playlist import<br/>[youtube.js]"]
end

subgraph group_admin["Administration"]
  node_adminroutes["Admin API<br/>[admin.js]"]
  node_settings["Station settings<br/>[settings.js]"]
  node_backup["Backup restore<br/>[backup.js]"]
end

node_listeners(("Listeners"))
node_administrator(("Administrator"))
node_weather["Open-Meteo"]
node_youtubeapi["YouTube Data API"]
node_gemini["Gemini"]

node_cliententry -->|"routes to"| node_screen
node_cliententry -->|"routes to"| node_voting
node_cliententry -->|"routes to"| node_adminui
node_listeners -->|"vote via"| node_voting
node_listeners -->|"view playback"| node_screen
node_administrator -->|"manage station"| node_adminui
node_screen -->|"uses connection"| node_client_socket
node_voting -->|"uses connection"| node_client_socket
node_adminui -->|"uses connection"| node_client_socket
node_adminui -->|"previews voice"| node_speech
node_adminui -.->|"requests API"| node_server
node_server -->|"mounts routes"| node_publicroutes
node_server -->|"mounts routes"| node_adminroutes
node_server -->|"dispatches events"| node_director
node_server -->|"seeds admin"| node_auth
node_publicroutes -->|"queries"| node_database
node_publicroutes -->|"uses auth"| node_auth
node_adminroutes -->|"queries"| node_database
node_adminroutes -->|"requires admin"| node_auth
node_adminroutes -->|"imports playlists"| node_youtube
node_adminroutes -->|"calls song tools"| node_songtools
node_adminroutes -->|"handles backup"| node_backup
node_adminroutes -->|"previews narration"| node_dj
node_director -->|"reads and writes"| node_database
node_director -->|"loads settings"| node_settings
node_director -->|"selects candidates"| node_selection
node_director -->|"requests narration"| node_dj
node_selection -->|"reads catalog"| node_database
node_selection -->|"loads settings"| node_settings
node_selection -->|"fetches temperature"| node_weather
node_songtools -->|"stores songs"| node_database
node_songtools -->|"requests metadata"| node_youtube
node_youtube -->|"imports playlist"| node_database
node_youtube -->|"cleans and tags"| node_songtools
node_backup -->|"exports and restores"| node_database
node_settings -->|"reads and writes"| node_database
node_youtube -->|"requests data"| node_youtubeapi
node_dj -.->|"optional AI"| node_gemini

click node_screen "https://github.com/wa1o/radio-campus/blob/main/client/src/pages/Screen.jsx"
click node_voting "https://github.com/wa1o/radio-campus/blob/main/client/src/pages/Vote.jsx"
click node_adminui "https://github.com/wa1o/radio-campus/blob/main/client/src/pages/Admin.jsx"
click node_cliententry "https://github.com/wa1o/radio-campus/blob/main/client/src/main.jsx"
click node_client_socket "https://github.com/wa1o/radio-campus/blob/main/client/src/socket.jsx"
click node_speech "https://github.com/wa1o/radio-campus/blob/main/client/src/speech.js"
click node_server "https://github.com/wa1o/radio-campus/blob/main/server/src/index.js"
click node_director "https://github.com/wa1o/radio-campus/blob/main/server/src/director.js"
click node_publicroutes "https://github.com/wa1o/radio-campus/blob/main/server/src/routes/public.js"
click node_auth "https://github.com/wa1o/radio-campus/blob/main/server/src/auth.js"
click node_database "https://github.com/wa1o/radio-campus/blob/main/server/src/schema.sql"
click node_adminroutes "https://github.com/wa1o/radio-campus/blob/main/server/src/routes/admin.js"
click node_settings "https://github.com/wa1o/radio-campus/blob/main/server/src/settings.js"
click node_backup "https://github.com/wa1o/radio-campus/blob/main/server/src/backup.js"
click node_selection "https://github.com/wa1o/radio-campus/blob/main/server/src/context.js"
click node_songtools "https://github.com/wa1o/radio-campus/blob/main/server/src/songtools.js"
click node_youtube "https://github.com/wa1o/radio-campus/blob/main/server/src/youtube.js"
click node_dj "https://github.com/wa1o/radio-campus/blob/main/server/src/dj.js"

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_screen,node_voting,node_adminui,node_cliententry,node_client_socket,node_speech toneBlue
class node_server,node_director,node_publicroutes,node_auth,node_database,node_dj toneAmber
class node_selection,node_songtools,node_youtube,node_youtubeapi toneMint
class node_adminroutes,node_settings,node_backup toneRose
class node_listeners,node_administrator,node_weather,node_gemini toneIndigo
```

## Components

### Campus interfaces

- [Public screen](https://github.com/wa1o/radio-campus/blob/main/client/src/pages/Screen.jsx): `client/src/pages/Screen.jsx`
- [Mobile voting](https://github.com/wa1o/radio-campus/blob/main/client/src/pages/Vote.jsx): `client/src/pages/Vote.jsx`
- [Admin panel](https://github.com/wa1o/radio-campus/blob/main/client/src/pages/Admin.jsx): `client/src/pages/Admin.jsx`
- [Route entry](https://github.com/wa1o/radio-campus/blob/main/client/src/main.jsx): `client/src/main.jsx`
- [Socket client](https://github.com/wa1o/radio-campus/blob/main/client/src/socket.jsx): `client/src/socket.jsx`
- [Browser speech](https://github.com/wa1o/radio-campus/blob/main/client/src/speech.js): `client/src/speech.js`

### Station runtime

- [HTTP and sockets](https://github.com/wa1o/radio-campus/blob/main/server/src/index.js): `server/src/index.js`
- [Station director](https://github.com/wa1o/radio-campus/blob/main/server/src/director.js): `server/src/director.js`
- [Public API](https://github.com/wa1o/radio-campus/blob/main/server/src/routes/public.js): `server/src/routes/public.js`
- [Admin authentication](https://github.com/wa1o/radio-campus/blob/main/server/src/auth.js): `server/src/auth.js`
- [PostgreSQL](https://github.com/wa1o/radio-campus/blob/main/server/src/schema.sql): `server/src/schema.sql`
- [Announcer text](https://github.com/wa1o/radio-campus/blob/main/server/src/dj.js): `server/src/dj.js`

### Catalog and context

- [Context selection](https://github.com/wa1o/radio-campus/blob/main/server/src/context.js): `server/src/context.js`
- [Song tools](https://github.com/wa1o/radio-campus/blob/main/server/src/songtools.js): `server/src/songtools.js`
- [Playlist import](https://github.com/wa1o/radio-campus/blob/main/server/src/youtube.js): `server/src/youtube.js`

### Administration

- [Admin API](https://github.com/wa1o/radio-campus/blob/main/server/src/routes/admin.js): `server/src/routes/admin.js`
- [Station settings](https://github.com/wa1o/radio-campus/blob/main/server/src/settings.js): `server/src/settings.js`
- [Backup restore](https://github.com/wa1o/radio-campus/blob/main/server/src/backup.js): `server/src/backup.js`

### Other components

- **Listeners**
- **Administrator**
- **Open-Meteo**
- **YouTube Data API**
- **Gemini**

## Connections

- Route entry → Public screen: routes to (evidence: `client/src/main.jsx`)
- Route entry → Mobile voting: routes to (evidence: `client/src/main.jsx`)
- Route entry → Admin panel: routes to (evidence: `client/src/main.jsx`)
- Listeners → Mobile voting: vote via (evidence: `README.md`)
- Listeners → Public screen: view playback (evidence: `README.md`)
- Administrator → Admin panel: manage station (evidence: `README.md`)
- Public screen → Socket client: uses connection (evidence: `client/src/pages/Screen.jsx`)
- Mobile voting → Socket client: uses connection (evidence: `client/src/pages/Vote.jsx`)
- Admin panel → Socket client: uses connection (evidence: `client/src/pages/Admin.jsx`)
- Admin panel → Browser speech: previews voice (evidence: `client/src/pages/Admin.jsx`)
- Admin panel → HTTP and sockets: requests API
- HTTP and sockets → Public API: mounts routes (evidence: `server/src/index.js`)
- HTTP and sockets → Admin API: mounts routes (evidence: `server/src/index.js`)
- HTTP and sockets → Station director: dispatches events (evidence: `server/src/index.js`)
- HTTP and sockets → Admin authentication: seeds admin (evidence: `server/src/index.js`)
- Public API → PostgreSQL: queries (evidence: `server/src/routes/public.js`)
- Public API → Admin authentication: uses auth (evidence: `server/src/routes/public.js`)
- Admin API → PostgreSQL: queries (evidence: `server/src/routes/admin.js`)
- Admin API → Admin authentication: requires admin (evidence: `server/src/routes/admin.js`)
- Admin API → Playlist import: imports playlists (evidence: `server/src/routes/admin.js`)
- Admin API → Song tools: calls song tools (evidence: `server/src/routes/admin.js`)
- Admin API → Backup restore: handles backup (evidence: `server/src/routes/admin.js`)
- Admin API → Announcer text: previews narration (evidence: `server/src/routes/admin.js`)
- Station director → PostgreSQL: reads and writes (evidence: `server/src/director.js`)
- Station director → Station settings: loads settings (evidence: `server/src/director.js`)
- Station director → Context selection: selects candidates (evidence: `server/src/director.js`)
- Station director → Announcer text: requests narration (evidence: `server/src/director.js`)
- Context selection → PostgreSQL: reads catalog (evidence: `server/src/context.js`)
- Context selection → Station settings: loads settings (evidence: `server/src/context.js`)
- Context selection → Open-Meteo: fetches temperature (evidence: `server/src/context.js`)
- Song tools → PostgreSQL: stores songs (evidence: `server/src/songtools.js`)
- Song tools → Playlist import: requests metadata (evidence: `server/src/songtools.js`)
- Playlist import → PostgreSQL: imports playlist (evidence: `server/src/youtube.js`)
- Playlist import → Song tools: cleans and tags (evidence: `server/src/youtube.js`)
- Backup restore → PostgreSQL: exports and restores (evidence: `server/src/backup.js`)
- Station settings → PostgreSQL: reads and writes (evidence: `server/src/settings.js`)
- Playlist import → YouTube Data API: requests data (evidence: `server/src/youtube.js`)
- Announcer text → Gemini: optional AI (evidence: `README.md`)
