# kinkpedil/frlcast architecture

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

- Interactive diagram: https://gitdiagram.com/kinkpedil/frlcast
- Repository: https://github.com/kinkpedil/frlcast

## Overview

FRLcast is a race-control and broadcast system for FR Legends leagues. An operator manages an event in the console; race state and timing feed live classification, race-control actions, overlays, and driver information. Optional inputs include official game-server timing and minimap vision tracking. Hosted mode adds public audience pages and cloud-linked drivers; desktop mode adds local commentary and the timing API. The graph preserves documented capabilities, but some connections are documented only at product level because their implementation was not excerpted.

Main entry points: [`public/js/race-state.js`](https://github.com/kinkpedil/frlcast/blob/main/public/js/race-state.js) (Race control), [`server/index.js`](https://github.com/kinkpedil/frlcast/blob/main/server/index.js) (Local server), [`android/src/com/frl/driver/MainActivity.java`](https://github.com/kinkpedil/frlcast/blob/main/android/src/com/frl/driver/MainActivity.java) (Driver phone app), [`public/js/vision.js`](https://github.com/kinkpedil/frlcast/blob/main/public/js/vision.js) (Vision tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Race console"]
  node_consoleui["Operator console<br/>[panel.js]"]
  node_racecontrol["Race control<br/>[race-state.js]"]
end

subgraph group_race["Race and timing"]
  node_championship["Championship scoring<br/>[points.js]"]
  node_timing["Race timing<br/>[timing.js]"]
  node_tracker["Position tracking<br/>[tracker.js]"]
  node_vision["Vision tracking<br/>[vision.js]"]
  node_visionworker["Vision worker<br/>[vision-worker.js]"]
  node_officialapi["Official timing API<br/>[timing-api.js]"]
  node_server["Local server<br/>[index.js]"]
  node_statefile[("Local state store<br/>[file-store.js]")]
  node_driverauth["Driver authentication<br/>[drivers-auth.js]"]
end

subgraph group_broadcast["Broadcast features"]
  node_overlays["OBS overlays<br/>[overlay.js]"]
  node_commentary["Spoken commentary<br/>[commentary.js]"]
end

subgraph group_hosted["Hosted services"]
  node_audience["Audience poll<br/>[app.js]"]
  node_cloudlink["Cloud event linking<br/>[cloud-link.js]"]
  node_cloudbus["Cloud updates<br/>[cloudbus.js]"]
  node_supastore[("Hosted data access<br/>[supabase-store.js]")]
end

subgraph group_driver["Driver app"]
  node_driverphone["Driver phone app<br/>[MainActivity.java]"]
  node_driveroverlay["Floating flag window"]
  node_driverbackend["Driver backend client<br/>[Backend.java]"]
end

node_operator(("Race operator"))
node_game(("FR Legends server"))
node_drivers(("Drivers"))
node_obs(("OBS audience"))

node_operator -->|"operates"| node_consoleui
node_consoleui -->|"controls race"| node_racecontrol
node_racecontrol -->|"records timing"| node_timing
node_racecontrol -->|"scores rounds"| node_championship
node_vision -->|"runs worker"| node_visionworker
node_vision -->|"uses tracking"| node_tracker
node_game -->|"provides laps"| node_officialapi
node_officialapi -->|"feeds timing"| node_server
node_server -->|"serves race state"| node_racecontrol
node_server -->|"persists state"| node_statefile
node_racecontrol -->|"supplies race data"| node_overlays
node_overlays -->|"renders broadcast"| node_obs
node_racecontrol -->|"drives commentary"| node_commentary
node_drivers -->|"uses app"| node_driverphone
node_driverphone -->|"sends requests"| node_driverbackend
node_driverbackend -->|"calls driver API"| node_server
node_server -->|"authenticates drivers"| node_driverauth
node_driverphone -->|"starts overlay"| node_driveroverlay
node_driveroverlay -->|"polls race state"| node_server
node_audience -.->|"links hosted events"| node_cloudlink
node_cloudlink -->|"uses hosted storage"| node_supastore
node_cloudbus -->|"syncs cloud data"| node_supastore
node_audience -.->|"votes in poll"| node_cloudbus

click node_consoleui "https://github.com/kinkpedil/frlcast/blob/main/public/js/panel.js"
click node_racecontrol "https://github.com/kinkpedil/frlcast/blob/main/public/js/race-state.js"
click node_championship "https://github.com/kinkpedil/frlcast/blob/main/public/js/points.js"
click node_timing "https://github.com/kinkpedil/frlcast/blob/main/public/js/timing.js"
click node_tracker "https://github.com/kinkpedil/frlcast/blob/main/public/js/tracker.js"
click node_vision "https://github.com/kinkpedil/frlcast/blob/main/public/js/vision.js"
click node_visionworker "https://github.com/kinkpedil/frlcast/blob/main/public/js/vision-worker.js"
click node_officialapi "https://github.com/kinkpedil/frlcast/blob/main/server/timing-api.js"
click node_server "https://github.com/kinkpedil/frlcast/blob/main/server/index.js"
click node_statefile "https://github.com/kinkpedil/frlcast/blob/main/server/file-store.js"
click node_overlays "https://github.com/kinkpedil/frlcast/blob/main/public/overlay/overlay.js"
click node_commentary "https://github.com/kinkpedil/frlcast/blob/main/public/js/commentary.js"
click node_audience "https://github.com/kinkpedil/frlcast/blob/main/site/app.js"
click node_cloudlink "https://github.com/kinkpedil/frlcast/blob/main/server/cloud-link.js"
click node_cloudbus "https://github.com/kinkpedil/frlcast/blob/main/public/js/cloudbus.js"
click node_supastore "https://github.com/kinkpedil/frlcast/blob/main/public/js/supabase-store.js"
click node_driverphone "https://github.com/kinkpedil/frlcast/blob/main/android/src/com/frl/driver/MainActivity.java"
click node_driveroverlay "https://github.com/kinkpedil/frlcast/blob/main/android/src/com/frl/driver/OverlayService.java"
click node_driverbackend "https://github.com/kinkpedil/frlcast/blob/main/android/src/com/frl/driver/Backend.java"
click node_driverauth "https://github.com/kinkpedil/frlcast/blob/main/server/drivers-auth.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_consoleui,node_racecontrol toneBlue
class node_championship,node_timing,node_tracker,node_vision,node_visionworker,node_officialapi,node_server,node_statefile,node_driverauth toneAmber
class node_overlays,node_commentary,node_game toneMint
class node_audience,node_cloudlink,node_cloudbus,node_supastore toneRose
class node_driverphone,node_driveroverlay,node_driverbackend,node_operator,node_drivers,node_obs toneIndigo
```

## Components

### Race console

- [Operator console](https://github.com/kinkpedil/frlcast/blob/main/public/js/panel.js): `public/js/panel.js`
- [Race control](https://github.com/kinkpedil/frlcast/blob/main/public/js/race-state.js): `public/js/race-state.js`

### Race and timing

- [Championship scoring](https://github.com/kinkpedil/frlcast/blob/main/public/js/points.js): `public/js/points.js`
- [Race timing](https://github.com/kinkpedil/frlcast/blob/main/public/js/timing.js): `public/js/timing.js`
- [Position tracking](https://github.com/kinkpedil/frlcast/blob/main/public/js/tracker.js): `public/js/tracker.js`
- [Vision tracking](https://github.com/kinkpedil/frlcast/blob/main/public/js/vision.js): `public/js/vision.js`
- [Vision worker](https://github.com/kinkpedil/frlcast/blob/main/public/js/vision-worker.js): `public/js/vision-worker.js`
- [Official timing API](https://github.com/kinkpedil/frlcast/blob/main/server/timing-api.js): `server/timing-api.js`
- [Local server](https://github.com/kinkpedil/frlcast/blob/main/server/index.js): `server/index.js`
- [Local state store](https://github.com/kinkpedil/frlcast/blob/main/server/file-store.js): `server/file-store.js`
- [Driver authentication](https://github.com/kinkpedil/frlcast/blob/main/server/drivers-auth.js): `server/drivers-auth.js`

### Broadcast features

- [OBS overlays](https://github.com/kinkpedil/frlcast/blob/main/public/overlay/overlay.js): `public/overlay/overlay.js`
- [Spoken commentary](https://github.com/kinkpedil/frlcast/blob/main/public/js/commentary.js): `public/js/commentary.js`

### Hosted services

- [Audience poll](https://github.com/kinkpedil/frlcast/blob/main/site/app.js): `site/app.js`
- [Cloud event linking](https://github.com/kinkpedil/frlcast/blob/main/server/cloud-link.js): `server/cloud-link.js`
- [Cloud updates](https://github.com/kinkpedil/frlcast/blob/main/public/js/cloudbus.js): `public/js/cloudbus.js`
- [Hosted data access](https://github.com/kinkpedil/frlcast/blob/main/public/js/supabase-store.js): `public/js/supabase-store.js`

### Driver app

- [Driver phone app](https://github.com/kinkpedil/frlcast/blob/main/android/src/com/frl/driver/MainActivity.java): `android/src/com/frl/driver/MainActivity.java`
- [Floating flag window](https://github.com/kinkpedil/frlcast/blob/main/android/src/com/frl/driver/OverlayService.java): `android/src/com/frl/driver/OverlayService.java`
- [Driver backend client](https://github.com/kinkpedil/frlcast/blob/main/android/src/com/frl/driver/Backend.java): `android/src/com/frl/driver/Backend.java`

### Other components

- **Race operator**
- **FR Legends server**
- **Drivers**
- **OBS audience**

## Connections

- Race operator → Operator console: operates (evidence: `README.md`)
- Operator console → Race control: controls race (evidence: `README.md`)
- Race control → Race timing: records timing (evidence: `README.md`)
- Race control → Championship scoring: scores rounds (evidence: `public/js/race-state.js`)
- Vision tracking → Vision worker: runs worker (evidence: `public/js/vision.js`)
- Vision tracking → Position tracking: uses tracking (evidence: `public/js/vision.js`)
- FR Legends server → Official timing API: provides laps (evidence: `README.md`)
- Official timing API → Local server: feeds timing (evidence: `README.md`)
- Local server → Race control: serves race state (evidence: `server/index.js`)
- Local server → Local state store: persists state (evidence: `server/index.js`)
- Race control → OBS overlays: supplies race data (evidence: `README.md`)
- OBS overlays → OBS audience: renders broadcast (evidence: `README.md`)
- Race control → Spoken commentary: drives commentary (evidence: `README.md`)
- Drivers → Driver phone app: uses app (evidence: `README.md`)
- Driver phone app → Driver backend client: sends requests (evidence: `android/src/com/frl/driver/MainActivity.java`)
- Driver backend client → Local server: calls driver API (evidence: `android/src/com/frl/driver/Backend.java`)
- Local server → Driver authentication: authenticates drivers (evidence: `server/index.js`)
- Driver phone app → Floating flag window: starts overlay (evidence: `android/src/com/frl/driver/MainActivity.java`)
- Floating flag window → Local server: polls race state (evidence: `android/src/com/frl/driver/OverlayService.java`)
- Audience poll → Cloud event linking: links hosted events (evidence: `README.md`)
- Cloud event linking → Hosted data access: uses hosted storage (evidence: `server/cloud-link.js`)
- Cloud updates → Hosted data access: syncs cloud data (evidence: `public/js/cloudbus.js`)
- Audience poll → Cloud updates: votes in poll (evidence: `README.md`)
