# maximebrison/multitrack architecture

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

- Interactive diagram: https://gitdiagram.com/maximebrison/multitrack
- Repository: https://github.com/maximebrison/multitrack

## Overview

Multitrack routes radio messages and commands between serial-connected plugin devices and a tracking/dispatch core, with a browser dashboard for entity locations, status, and plugin settings. The main flow is radio data through the plugin’s serial bridge and WebSocket connection to the core, then to browser clients; operator commands travel back through plugin HTTP endpoints to the radio. The graph also preserves discovery, plugin UI elements, mapping, and persistence. Several frontend and core relationships are documented or indexed but not sampled in detail, so uncertain links are omitted.

Main entry points: [`src/plugin_demo/multitrack/MultitrackAPI.py`](https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/MultitrackAPI.py) (Plugin API), [`src/app/app.ts`](https://github.com/maximebrison/multitrack/blob/main/src/app/app.ts) (Core dispatcher), [`src/app/frontend/src/App.tsx`](https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/App.tsx) (Dashboard app), [`src/app/modules/MultitrackServer.ts`](https://github.com/maximebrison/multitrack/blob/main/src/app/modules/MultitrackServer.ts) (WebSocket server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["Radio plugin"]
  node_plugin_api["Plugin API<br/>[MultitrackAPI.py]"]
  node_plugin_elements["Control elements<br/>[Elements.py]"]
  node_plugin_models["Plugin models<br/>[models.py]"]
  node_serial_bridge["Serial bridge<br/>[SerialBridge.py]"]
  node_serial_driver["Serial driver<br/>[SerialDriver.py]"]
  node_udp_listener["UDP discovery<br/>[UDPListener.py]"]
end

subgraph group_core["Core services"]
  node_core_app["Core dispatcher<br/>[app.ts]"]
  node_core_server["WebSocket server"]
  node_discoverer["Plugin discovery<br/>[Discoverer.ts]"]
  node_auth["Authentication<br/>[Authenticator.ts]"]
  node_plugin_registry["Plugin registry<br/>[Database.ts]"]
end

subgraph group_frontend["Operator dashboard"]
  node_frontend_app["Dashboard app<br/>[App.tsx]"]
  node_app_context["Controller context<br/>[AppContext.tsx]"]
  node_controllers["UI controllers"]
  node_socket_controller["Socket messaging"]
  node_map_controller["Entity map<br/>[MapController.ts]"]
  node_mainframe["Map and sidebar<br/>[Mainframe.tsx]"]
  node_settings["Plugin settings"]
end

subgraph group_state["Domain state"]
  node_sqlite[("SQLite database<br/>[database.ts]")]
  node_entity_state["Entity state<br/>[app.ts]"]
  node_core_data_db["Core data access<br/>[Database.ts]"]
end

node_radio(("Radio device"))
node_browser_operator(("Operator"))

node_plugin_api -->|"creates"| node_serial_bridge
node_plugin_api -->|"configures"| node_serial_driver
node_plugin_api -->|"registers routes"| node_plugin_elements
node_plugin_api -->|"starts"| node_udp_listener
node_plugin_elements -->|"builds endpoints"| node_plugin_models
node_serial_bridge -->|"delegates parsing"| node_serial_driver
node_radio -.->|"sends serial data"| node_serial_driver
node_serial_bridge -.->|"queues data"| node_plugin_api
node_plugin_api -.->|"streams plugin data"| node_core_server
node_core_app -->|"dispatches discovery"| node_discoverer
node_core_app -->|"dispatches callbacks"| node_core_server
node_core_app -->|"updates entities"| node_entity_state
node_core_app -->|"loads plugins"| node_plugin_registry
node_core_server -.->|"authenticates clients"| node_auth
node_plugin_registry -.->|"accesses database"| node_sqlite
node_core_data_db -->|"opens database"| node_sqlite
node_browser_operator -.->|"uses dashboard"| node_frontend_app
node_frontend_app -->|"consumes context"| node_app_context
node_app_context -->|"creates controllers"| node_controllers
node_controllers -->|"owns socket"| node_socket_controller
node_controllers -->|"owns map"| node_map_controller
node_frontend_app -->|"renders"| node_mainframe
node_frontend_app -->|"renders"| node_settings
node_mainframe -.->|"displays map"| node_map_controller
node_socket_controller -.->|"exchanges envelopes"| node_core_server
node_core_app -.->|"broadcasts entity updates"| node_socket_controller
node_plugin_api -.->|"sends plugin data"| node_core_app

click node_plugin_api "https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/MultitrackAPI.py"
click node_plugin_elements "https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/Elements.py"
click node_plugin_models "https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/models.py"
click node_serial_bridge "https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/SerialBridge.py"
click node_serial_driver "https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/SerialDriver.py"
click node_udp_listener "https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/UDPListener.py"
click node_core_app "https://github.com/maximebrison/multitrack/blob/main/src/app/app.ts"
click node_core_server "https://github.com/maximebrison/multitrack/blob/main/src/app/modules/MultitrackServer.ts"
click node_discoverer "https://github.com/maximebrison/multitrack/blob/main/src/app/modules/Discoverer.ts"
click node_auth "https://github.com/maximebrison/multitrack/blob/main/src/app/modules/Authenticator.ts"
click node_plugin_registry "https://github.com/maximebrison/multitrack/blob/main/src/app/modules/Database.ts"
click node_sqlite "https://github.com/maximebrison/multitrack/blob/main/src/app/ctx/database.ts"
click node_entity_state "https://github.com/maximebrison/multitrack/blob/main/src/app/app.ts"
click node_frontend_app "https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/App.tsx"
click node_app_context "https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/ctx/AppContext.tsx"
click node_controllers "https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/controllers/_ContextController.ts"
click node_socket_controller "https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/controllers/SocketController.ts"
click node_map_controller "https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/controllers/MapController.ts"
click node_mainframe "https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/parts/Mainframe.tsx"
click node_settings "https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/parts/SettingsDiscover.tsx"
click node_core_data_db "https://github.com/maximebrison/multitrack/blob/main/src/app/modules/Database.ts"

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_plugin_api,node_plugin_elements,node_plugin_models,node_serial_bridge,node_serial_driver,node_udp_listener toneBlue
class node_core_app,node_core_server,node_discoverer,node_auth,node_plugin_registry toneAmber
class node_frontend_app,node_app_context,node_controllers,node_socket_controller,node_map_controller,node_mainframe,node_settings toneMint
class node_sqlite,node_entity_state,node_core_data_db toneRose
class node_radio,node_browser_operator toneIndigo
```

## Components

### Radio plugin

- [Plugin API](https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/MultitrackAPI.py): `src/plugin_demo/multitrack/MultitrackAPI.py`
- [Control elements](https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/Elements.py): `src/plugin_demo/multitrack/Elements.py`
- [Plugin models](https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/models.py): `src/plugin_demo/multitrack/models.py`
- [Serial bridge](https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/SerialBridge.py): `src/plugin_demo/multitrack/SerialBridge.py`
- [Serial driver](https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/SerialDriver.py): `src/plugin_demo/multitrack/SerialDriver.py`
- [UDP discovery](https://github.com/maximebrison/multitrack/blob/main/src/plugin_demo/multitrack/UDPListener.py): `src/plugin_demo/multitrack/UDPListener.py`

### Core services

- [Core dispatcher](https://github.com/maximebrison/multitrack/blob/main/src/app/app.ts): `src/app/app.ts`
- [WebSocket server](https://github.com/maximebrison/multitrack/blob/main/src/app/modules/MultitrackServer.ts): `src/app/modules/MultitrackServer.ts`
- [Plugin discovery](https://github.com/maximebrison/multitrack/blob/main/src/app/modules/Discoverer.ts): `src/app/modules/Discoverer.ts`
- [Authentication](https://github.com/maximebrison/multitrack/blob/main/src/app/modules/Authenticator.ts): `src/app/modules/Authenticator.ts`
- [Plugin registry](https://github.com/maximebrison/multitrack/blob/main/src/app/modules/Database.ts): `src/app/modules/Database.ts`

### Operator dashboard

- [Dashboard app](https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/App.tsx): `src/app/frontend/src/App.tsx`
- [Controller context](https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/ctx/AppContext.tsx): `src/app/frontend/src/ctx/AppContext.tsx`
- [UI controllers](https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/controllers/_ContextController.ts): `src/app/frontend/src/controllers/_ContextController.ts`
- [Socket messaging](https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/controllers/SocketController.ts): `src/app/frontend/src/controllers/SocketController.ts`
- [Entity map](https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/controllers/MapController.ts): `src/app/frontend/src/controllers/MapController.ts`
- [Map and sidebar](https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/parts/Mainframe.tsx): `src/app/frontend/src/parts/Mainframe.tsx`
- [Plugin settings](https://github.com/maximebrison/multitrack/blob/main/src/app/frontend/src/parts/SettingsDiscover.tsx): `src/app/frontend/src/parts/SettingsDiscover.tsx`

### Domain state

- [SQLite database](https://github.com/maximebrison/multitrack/blob/main/src/app/ctx/database.ts): `src/app/ctx/database.ts`
- [Entity state](https://github.com/maximebrison/multitrack/blob/main/src/app/app.ts): `src/app/app.ts`
- [Core data access](https://github.com/maximebrison/multitrack/blob/main/src/app/modules/Database.ts): `src/app/modules/Database.ts`

### Other components

- **Radio device**
- **Operator**

## Connections

- Plugin API → Serial bridge: creates (evidence: `src/plugin_demo/multitrack/MultitrackAPI.py`)
- Plugin API → Serial driver: configures (evidence: `src/plugin_demo/multitrack/MultitrackAPI.py`)
- Plugin API → Control elements: registers routes (evidence: `src/plugin_demo/multitrack/MultitrackAPI.py`)
- Plugin API → UDP discovery: starts (evidence: `src/plugin_demo/multitrack/MultitrackAPI.py`)
- Control elements → Plugin models: builds endpoints (evidence: `src/plugin_demo/multitrack/models.py`)
- Serial bridge → Serial driver: delegates parsing (evidence: `src/plugin_demo/multitrack/SerialBridge.py`)
- Radio device → Serial driver: sends serial data
- Serial bridge → Plugin API: queues data (evidence: `src/plugin_demo/multitrack/MultitrackAPI.py`)
- Plugin API → WebSocket server: streams plugin data
- Core dispatcher → Plugin discovery: dispatches discovery (evidence: `src/app/app.ts`)
- Core dispatcher → WebSocket server: dispatches callbacks (evidence: `src/app/app.ts`)
- Core dispatcher → Entity state: updates entities (evidence: `src/app/app.ts`)
- Core dispatcher → Plugin registry: loads plugins (evidence: `src/app/app.ts`)
- WebSocket server → Authentication: authenticates clients (evidence: `src/app/modules/MultitrackServer.ts`)
- Plugin registry → SQLite database: accesses database
- Core data access → SQLite database: opens database (evidence: `src/app/modules/Database.ts`)
- Operator → Dashboard app: uses dashboard
- Dashboard app → Controller context: consumes context (evidence: `src/app/frontend/src/App.tsx`)
- Controller context → UI controllers: creates controllers (evidence: `src/app/frontend/src/ctx/AppContext.tsx`)
- UI controllers → Socket messaging: owns socket (evidence: `src/app/frontend/src/controllers/_ContextController.ts`)
- UI controllers → Entity map: owns map (evidence: `src/app/frontend/src/controllers/_ContextController.ts`)
- Dashboard app → Map and sidebar: renders (evidence: `src/app/frontend/src/App.tsx`)
- Dashboard app → Plugin settings: renders (evidence: `src/app/frontend/src/App.tsx`)
- Map and sidebar → Entity map: displays map
- Socket messaging → WebSocket server: exchanges envelopes
- Core dispatcher → Socket messaging: broadcasts entity updates
- Plugin API → Core dispatcher: sends plugin data