# shane-mason/fieldstation42 architecture

> Architecture diagram of the GitHub repository shane-mason/fieldstation42, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shane-mason/fieldstation42
- Repository: https://github.com/shane-mason/fieldstation42

## Overview

FieldStation42 simulates scheduled broadcast TV: station configuration and media catalogs feed schedules and programming blocks, which the player tunes and plays as a continuous channel experience. Users manage stations through the web console or local UI, control playback through web/API and IR inputs, and see guide, on-screen, and overlay information. The source index supports the main scheduling and playback links; several web/API capabilities are documented but their handler internals were not sampled, so those connections are shown only where documented or indexed.

Main entry points: [`fs42/station_player.py`](https://github.com/shane-mason/fieldstation42/blob/main/fs42/station_player.py) (Station Player), [`fs42/liquid_schedule.py`](https://github.com/shane-mason/fieldstation42/blob/main/fs42/liquid_schedule.py) (Liquid Schedule), [`field_player.py`](https://github.com/shane-mason/fieldstation42/blob/main/field_player.py) (Player Process), [`fs42/catalog.py`](https://github.com/shane-mason/fieldstation42/blob/main/fs42/catalog.py) (Media Catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Station Setup"]
  node_station_config["Station Manager<br/>[station_manager.py]"]
  node_catalog[("Media Catalog<br/>[catalog.py]")]
  node_media["Media Processing<br/>[media_processor.py]"]
  node_fluid["Fluid Builder<br/>[fluid_builder.py]"]
end

subgraph group_schedule["Programming"]
  node_sequences["Sequence API<br/>[sequence_api.py]"]
  node_schedule_builder["Liquid Schedule<br/>[liquid_schedule.py]"]
  node_blocks["Programming Blocks<br/>[liquid_blocks.py]"]
  node_liquid_manager["Liquid Manager<br/>[liquid_manager.py]"]
  node_live_schedule["Live Schedule Agent"]
end

subgraph group_playback["Playback Runtime"]
  node_player_entry["Player Process<br/>[field_player.py]"]
  node_station_player["Station Player<br/>[station_player.py]"]
  node_reception["Reception<br/>[reception.py]"]
end

subgraph group_control["Control Interfaces"]
  node_web_server["Web Server<br/>[fs42_server.py]"]
  node_api_routes["REST API"]
  node_web_console["Web Console"]
  node_web_remote["Web Remote"]
  node_ir_remote["IR Remote Input"]
end

subgraph group_display["Viewer Experience"]
  node_guide["Program Guide<br/>[guide_tk.py]"]
  node_osd["On-Screen Display"]
  node_overlays["Playback Overlays"]
end

node_viewer(("Viewer / Operator"))
node_mpv["MPV Player"]

node_viewer -->|"configures stations"| node_web_console
node_viewer -->|"controls playback"| node_web_remote
node_viewer -->|"sends IR input"| node_ir_remote
node_web_server -->|"registers routes"| node_api_routes
node_web_console -.->|"uses web console"| node_web_server
node_web_remote -.->|"controls over HTTP"| node_web_server
node_api_routes -->|"queries player state"| node_station_config
node_station_config -.->|"configures catalog"| node_catalog
node_catalog -->|"processes media"| node_media
node_catalog -->|"scans fluid files"| node_fluid
node_schedule_builder -->|"selects content"| node_catalog
node_schedule_builder -->|"resolves sequence"| node_sequences
node_schedule_builder -->|"builds blocks"| node_blocks
node_liquid_manager -->|"uses block plans"| node_blocks
node_liquid_manager -->|"loads sequences"| node_sequences
node_live_schedule -->|"updates schedule"| node_schedule_builder
node_live_schedule -->|"refreshes schedules"| node_liquid_manager
node_player_entry -->|"loads stations"| node_station_config
node_player_entry -->|"starts playback"| node_station_player
node_player_entry -->|"starts API server"| node_web_server
node_station_player -->|"gets programming"| node_liquid_manager
node_station_player -->|"handles reception"| node_reception
node_station_player -.->|"plays media"| node_mpv
node_ir_remote -.->|"controls playback"| node_player_entry
node_station_player -->|"shows guide"| node_guide
node_station_player -->|"renders overlays"| node_overlays
node_viewer -->|"views schedule"| node_guide
node_viewer -->|"views channel info"| node_osd

click node_station_config "https://github.com/shane-mason/fieldstation42/blob/main/fs42/station_manager.py"
click node_catalog "https://github.com/shane-mason/fieldstation42/blob/main/fs42/catalog.py"
click node_media "https://github.com/shane-mason/fieldstation42/blob/main/fs42/media_processor.py"
click node_fluid "https://github.com/shane-mason/fieldstation42/blob/main/fs42/fluid_builder.py"
click node_sequences "https://github.com/shane-mason/fieldstation42/blob/main/fs42/sequence_api.py"
click node_schedule_builder "https://github.com/shane-mason/fieldstation42/blob/main/fs42/liquid_schedule.py"
click node_blocks "https://github.com/shane-mason/fieldstation42/blob/main/fs42/liquid_blocks.py"
click node_liquid_manager "https://github.com/shane-mason/fieldstation42/blob/main/fs42/liquid_manager.py"
click node_live_schedule "https://github.com/shane-mason/fieldstation42/blob/main/fs42/live_schedule_agent.py"
click node_player_entry "https://github.com/shane-mason/fieldstation42/blob/main/field_player.py"
click node_station_player "https://github.com/shane-mason/fieldstation42/blob/main/fs42/station_player.py"
click node_reception "https://github.com/shane-mason/fieldstation42/blob/main/fs42/reception.py"
click node_web_server "https://github.com/shane-mason/fieldstation42/blob/main/fs42/fs42_server/fs42_server.py"
click node_api_routes "https://github.com/shane-mason/fieldstation42/tree/main/fs42/fs42_server/api"
click node_web_console "https://github.com/shane-mason/fieldstation42/tree/main/fs42/fs42_server/static"
click node_web_remote "https://github.com/shane-mason/fieldstation42/tree/main/fs42/remote"
click node_ir_remote "https://github.com/shane-mason/fieldstation42/blob/main/fs42/pi/remote_controller.py"
click node_guide "https://github.com/shane-mason/fieldstation42/blob/main/fs42/guide_tk.py"
click node_osd "https://github.com/shane-mason/fieldstation42/tree/main/fs42/osd"
click node_overlays "https://github.com/shane-mason/fieldstation42/tree/main/fs42/overlay"

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_station_config,node_catalog,node_media,node_fluid,node_viewer toneBlue
class node_sequences,node_schedule_builder,node_blocks,node_liquid_manager,node_live_schedule toneAmber
class node_player_entry,node_station_player,node_reception toneMint
class node_web_server,node_api_routes,node_web_console,node_web_remote,node_ir_remote toneRose
class node_guide,node_osd,node_overlays,node_mpv toneIndigo
```

## Components

### Station Setup

- [Station Manager](https://github.com/shane-mason/fieldstation42/blob/main/fs42/station_manager.py): `fs42/station_manager.py`
- [Media Catalog](https://github.com/shane-mason/fieldstation42/blob/main/fs42/catalog.py): `fs42/catalog.py`
- [Media Processing](https://github.com/shane-mason/fieldstation42/blob/main/fs42/media_processor.py): `fs42/media_processor.py`
- [Fluid Builder](https://github.com/shane-mason/fieldstation42/blob/main/fs42/fluid_builder.py): `fs42/fluid_builder.py`

### Programming

- [Sequence API](https://github.com/shane-mason/fieldstation42/blob/main/fs42/sequence_api.py): `fs42/sequence_api.py`
- [Liquid Schedule](https://github.com/shane-mason/fieldstation42/blob/main/fs42/liquid_schedule.py): `fs42/liquid_schedule.py`
- [Programming Blocks](https://github.com/shane-mason/fieldstation42/blob/main/fs42/liquid_blocks.py): `fs42/liquid_blocks.py`
- [Liquid Manager](https://github.com/shane-mason/fieldstation42/blob/main/fs42/liquid_manager.py): `fs42/liquid_manager.py`
- [Live Schedule Agent](https://github.com/shane-mason/fieldstation42/blob/main/fs42/live_schedule_agent.py): `fs42/live_schedule_agent.py`

### Playback Runtime

- [Player Process](https://github.com/shane-mason/fieldstation42/blob/main/field_player.py): `field_player.py`
- [Station Player](https://github.com/shane-mason/fieldstation42/blob/main/fs42/station_player.py): `fs42/station_player.py`
- [Reception](https://github.com/shane-mason/fieldstation42/blob/main/fs42/reception.py): `fs42/reception.py`

### Control Interfaces

- [Web Server](https://github.com/shane-mason/fieldstation42/blob/main/fs42/fs42_server/fs42_server.py): `fs42/fs42_server/fs42_server.py`
- [REST API](https://github.com/shane-mason/fieldstation42/tree/main/fs42/fs42_server/api): `fs42/fs42_server/api`
- [Web Console](https://github.com/shane-mason/fieldstation42/tree/main/fs42/fs42_server/static): `fs42/fs42_server/static`
- [Web Remote](https://github.com/shane-mason/fieldstation42/tree/main/fs42/remote): `fs42/remote`
- [IR Remote Input](https://github.com/shane-mason/fieldstation42/blob/main/fs42/pi/remote_controller.py): `fs42/pi/remote_controller.py`

### Viewer Experience

- [Program Guide](https://github.com/shane-mason/fieldstation42/blob/main/fs42/guide_tk.py): `fs42/guide_tk.py`
- [On-Screen Display](https://github.com/shane-mason/fieldstation42/tree/main/fs42/osd): `fs42/osd`
- [Playback Overlays](https://github.com/shane-mason/fieldstation42/tree/main/fs42/overlay): `fs42/overlay`

### Other components

- **Viewer / Operator**
- **MPV Player**

## Connections

- Viewer / Operator → Web Console: configures stations
- Viewer / Operator → Web Remote: controls playback
- Viewer / Operator → IR Remote Input: sends IR input
- Web Server → REST API: registers routes (evidence: `fs42/fs42_server/fs42_server.py`)
- Web Console → Web Server: uses web console
- Web Remote → Web Server: controls over HTTP
- REST API → Station Manager: queries player state (evidence: `fs42/fs42_server/api/player.py`)
- Station Manager → Media Catalog: configures catalog
- Media Catalog → Media Processing: processes media (evidence: `fs42/catalog.py`)
- Media Catalog → Fluid Builder: scans fluid files (evidence: `fs42/catalog.py`)
- Liquid Schedule → Media Catalog: selects content (evidence: `fs42/liquid_schedule.py`)
- Liquid Schedule → Sequence API: resolves sequence (evidence: `fs42/liquid_schedule.py`)
- Liquid Schedule → Programming Blocks: builds blocks (evidence: `fs42/liquid_schedule.py`)
- Liquid Manager → Programming Blocks: uses block plans (evidence: `fs42/liquid_manager.py`)
- Liquid Manager → Sequence API: loads sequences (evidence: `fs42/liquid_manager.py`)
- Live Schedule Agent → Liquid Schedule: updates schedule (evidence: `fs42/live_schedule_agent.py`)
- Live Schedule Agent → Liquid Manager: refreshes schedules (evidence: `fs42/live_schedule_agent.py`)
- Player Process → Station Manager: loads stations (evidence: `field_player.py`)
- Player Process → Station Player: starts playback (evidence: `field_player.py`)
- Player Process → Web Server: starts API server (evidence: `field_player.py`)
- Station Player → Liquid Manager: gets programming (evidence: `fs42/station_player.py`)
- Station Player → Reception: handles reception (evidence: `fs42/station_player.py`)
- Station Player → MPV Player: plays media
- IR Remote Input → Player Process: controls playback
- Station Player → Program Guide: shows guide (evidence: `fs42/station_player.py`)
- Station Player → Playback Overlays: renders overlays (evidence: `fs42/station_player.py`)
- Viewer / Operator → Program Guide: views schedule
- Viewer / Operator → On-Screen Display: views channel info