# frequencehit/heron-broadcaster architecture

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

- Interactive diagram: https://gitdiagram.com/frequencehit/heron-broadcaster
- Repository: https://github.com/frequencehit/heron-broadcaster

## Overview

Heron is a self-hosted radio automation system: operators use the web interface to manage a music library and programming, then the API coordinates playback through station engines to streaming outputs. Separate product branches cover library ingestion and analysis, rotation, audio processing, listener-facing features, backups, and monitoring. The graph combines README-documented capabilities with sampled routing and engine/output excerpts; several subsystem links are documented rather than verified in unsampled implementation files.

Main entry points: [`crates/api/src/app.rs`](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/app.rs) (HTTP API), [`crates/engine/src/engine.rs`](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/engine/src/engine.rs) (Station engine), [`web/src/App.tsx`](https://github.com/frequencehit/heron-broadcaster/blob/main/web/src/App.tsx) (Web interface), [`web/src/api/index.ts`](https://github.com/frequencehit/heron-broadcaster/blob/main/web/src/api/index.ts) (Typed API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operation["Web and API"]
  node_web["Web interface<br/>[App.tsx]"]
  node_client["Typed API client<br/>[index.ts]"]
  node_api["HTTP API<br/>[app.rs]"]
  node_auth["Sessions and roles<br/>[auth.rs]"]
end

subgraph group_music["Library and Programming"]
  node_library["Library management<br/>[library.rs]"]
  node_ingest["Import and review<br/>[import.rs]"]
  node_librarian["File organization<br/>[journal.rs]"]
  node_analysis["Track analysis<br/>[analyzer.rs]"]
  node_rotation["Music rotation<br/>[select.rs]"]
  node_medleys["Medley creation<br/>[medley.rs]"]
end

subgraph group_air["Playback and Audio"]
  node_engine["Station engine<br/>[engine.rs]"]
  node_api_engine["Engine link<br/>[engine.rs]"]
  node_outputs["Encoding and outputs<br/>[pipeline.rs]"]
  node_audio_processing["Audio processing<br/>[mod.rs]"]
end

subgraph group_engagement["Listeners and Integrations"]
  node_listener_features["Listener features<br/>[shows.rs]"]
  node_public_gateway["Public gateway<br/>[gateway.rs]"]
  node_listener_stats["Listener statistics<br/>[mod.rs]"]
  node_webhooks["Webhooks<br/>[webhooks.rs]"]
end

subgraph group_reliability["Operations"]
  node_database[("Application database<br/>[db.rs]")]
  node_backups["Backups<br/>[mod.rs]"]
  node_monitoring["Monitoring<br/>[telemetry.rs]"]
end

node_operator(("Radio operator"))
node_icecast{{"Icecast servers"}}

node_operator -->|"operates"| node_web
node_web -->|"uses"| node_client
node_client -->|"requests"| node_api
node_api -->|"routes through"| node_auth
node_api -->|"routes to"| node_library
node_api -->|"routes to"| node_ingest
node_ingest -.->|"files and imports"| node_librarian
node_library -.->|"analyzes tracks"| node_analysis
node_api -.->|"manages programming"| node_rotation
node_api -.->|"persists state"| node_database
node_api -.->|"controls"| node_api_engine
node_api_engine -->|"calls over gRPC"| node_engine
node_engine -->|"streams audio"| node_outputs
node_engine -.->|"processes audio"| node_audio_processing
node_outputs -->|"streams to"| node_icecast
node_api -.->|"manages"| node_medleys
node_api -.->|"manages"| node_listener_features
node_listener_features -.->|"exposes interactions"| node_public_gateway
node_icecast -.->|"provides listener counts"| node_listener_stats
node_api -.->|"configures"| node_webhooks
node_api -.->|"provides backup operations"| node_backups
node_api -.->|"pushes telemetry"| node_monitoring

click node_web "https://github.com/frequencehit/heron-broadcaster/blob/main/web/src/App.tsx"
click node_client "https://github.com/frequencehit/heron-broadcaster/blob/main/web/src/api/index.ts"
click node_api "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/app.rs"
click node_auth "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/auth.rs"
click node_library "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/library.rs"
click node_ingest "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/import.rs"
click node_librarian "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/librarian/src/journal.rs"
click node_analysis "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/analysis/src/analyzer.rs"
click node_rotation "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/rotation/src/select.rs"
click node_database "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/service/src/db.rs"
click node_engine "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/engine/src/engine.rs"
click node_api_engine "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/engine.rs"
click node_outputs "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/outputs/src/pipeline.rs"
click node_audio_processing "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/dsp/src/agc/mod.rs"
click node_medleys "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/core/src/medley.rs"
click node_listener_features "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/core/src/shows.rs"
click node_public_gateway "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/gateway.rs"
click node_listener_stats "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/listeners/mod.rs"
click node_webhooks "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/webhooks.rs"
click node_backups "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/backups/mod.rs"
click node_monitoring "https://github.com/frequencehit/heron-broadcaster/blob/main/crates/service/src/telemetry.rs"

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_web,node_client,node_api,node_auth toneBlue
class node_library,node_ingest,node_librarian,node_analysis,node_rotation,node_medleys toneAmber
class node_engine,node_api_engine,node_outputs,node_audio_processing,node_icecast toneMint
class node_listener_features,node_public_gateway,node_listener_stats,node_webhooks toneRose
class node_database,node_backups,node_monitoring,node_operator toneIndigo
```

## Components

### Web and API

- [Web interface](https://github.com/frequencehit/heron-broadcaster/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Typed API client](https://github.com/frequencehit/heron-broadcaster/blob/main/web/src/api/index.ts): `web/src/api/index.ts`
- [HTTP API](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/app.rs): `crates/api/src/app.rs`
- [Sessions and roles](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/auth.rs): `crates/api/src/auth.rs`

### Library and Programming

- [Library management](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/library.rs): `crates/api/src/library.rs`
- [Import and review](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/import.rs): `crates/api/src/import.rs`
- [File organization](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/librarian/src/journal.rs): `crates/librarian/src/journal.rs`
- [Track analysis](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/analysis/src/analyzer.rs): `crates/analysis/src/analyzer.rs`
- [Music rotation](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/rotation/src/select.rs): `crates/rotation/src/select.rs`
- [Medley creation](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/core/src/medley.rs): `crates/core/src/medley.rs`

### Playback and Audio

- [Station engine](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/engine/src/engine.rs): `crates/engine/src/engine.rs`
- [Engine link](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/engine.rs): `crates/api/src/engine.rs`
- [Encoding and outputs](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/outputs/src/pipeline.rs): `crates/outputs/src/pipeline.rs`
- [Audio processing](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/dsp/src/agc/mod.rs): `crates/dsp/src/agc/mod.rs`

### Listeners and Integrations

- [Listener features](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/core/src/shows.rs): `crates/core/src/shows.rs`
- [Public gateway](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/gateway.rs): `crates/api/src/gateway.rs`
- [Listener statistics](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/listeners/mod.rs): `crates/api/src/listeners/mod.rs`
- [Webhooks](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/webhooks.rs): `crates/api/src/webhooks.rs`

### Operations

- [Application database](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/service/src/db.rs): `crates/service/src/db.rs`
- [Backups](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/api/src/backups/mod.rs): `crates/api/src/backups/mod.rs`
- [Monitoring](https://github.com/frequencehit/heron-broadcaster/blob/main/crates/service/src/telemetry.rs): `crates/service/src/telemetry.rs`

### Other components

- **Radio operator**
- **Icecast servers**

## Connections

- Radio operator → Web interface: operates
- Web interface → Typed API client: uses (evidence: `web/src/App.tsx`)
- Typed API client → HTTP API: requests (evidence: `web/src/api/index.ts`)
- HTTP API → Sessions and roles: routes through (evidence: `crates/api/src/app.rs`)
- HTTP API → Library management: routes to (evidence: `crates/api/src/app.rs`)
- HTTP API → Import and review: routes to (evidence: `crates/api/src/app.rs`)
- Import and review → File organization: files and imports
- Library management → Track analysis: analyzes tracks
- HTTP API → Music rotation: manages programming
- HTTP API → Application database: persists state
- HTTP API → Engine link: controls
- Engine link → Station engine: calls over gRPC (evidence: `crates/api/src/engine.rs`)
- Station engine → Encoding and outputs: streams audio (evidence: `crates/outputs/src/pipeline.rs`)
- Station engine → Audio processing: processes audio
- Encoding and outputs → Icecast servers: streams to
- HTTP API → Medley creation: manages
- HTTP API → Listener features: manages
- Listener features → Public gateway: exposes interactions
- Icecast servers → Listener statistics: provides listener counts
- HTTP API → Webhooks: configures (evidence: `crates/api/src/app.rs`)
- HTTP API → Backups: provides backup operations (evidence: `crates/api/src/app.rs`)
- HTTP API → Monitoring: pushes telemetry
