# kacperczeczot/stagesync architecture

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

- Interactive diagram: https://gitdiagram.com/kacperczeczot/stagesync
- Repository: https://github.com/kacperczeczot/stagesync

## Overview

StageSync is a live-show control system: an operator manages projects and setlists, edits timelines, and controls a server-authoritative transport; performers receive synchronized stage views and audio over the LAN. The server also provides project/library storage, MIDI automation, imports, and presence, while desktop and Android launchers help devices find or host a show. Several subsystem links below are documented capabilities; source excerpts do not expose every runtime route or client connection, so those links are marked dashed.

Main entry points: [`apps/server/src/app.ts`](https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/app.ts) (API and runtime), [`apps/web/src/shells/admin/AdminShell.tsx`](https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/shells/admin/AdminShell.tsx) (Admin console), [`apps/web/src/shells/admin/useAdminImportHandlers.ts`](https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/shells/admin/useAdminImportHandlers.ts) (Song import), [`apps/web/src/transport/useTransportSocket.ts`](https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/transport/useTransportSocket.ts) (Transport socket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator and Editing"]
  node_admin["Admin console<br/>[AdminShell.tsx]"]
  node_timeline["Timeline editor"]
  node_import["Song import"]
end

subgraph group_server["Show Server"]
  node_serverapp["API and runtime<br/>[app.ts]"]
  node_transport["Transport SSOT<br/>[engine.ts]"]
  node_storage[("Project storage<br/>[index.ts]")]
  node_midi["MIDI automation<br/>[host.ts]"]
  node_presence["Client presence<br/>[client-presence.ts]"]
  node_live["Live desk<br/>[live-desk.ts]"]
end

subgraph group_performer["Performer Clients"]
  node_client["Performer shell<br/>[ClientShell.tsx]"]
  node_audio["Synced audio<br/>[sync-engine.ts]"]
  node_clienttransport["Transport socket"]
end

subgraph group_launchers["Launch and Hosting"]
  node_desktop["Desktop launcher<br/>[app.js]"]
  node_androidhost["Android local host"]
  node_androidclient["Android performer<br/>[HostWebActivity.kt]"]
end

subgraph group_shared["Shared Show Logic"]
  node_bridge["Text bridge import"]
  node_tempo["Tempo map logic<br/>[time.ts]"]
end

node_operator(("Show operator"))

node_operator -->|"operates"| node_admin
node_admin -.->|"edits projects"| node_timeline
node_admin -->|"starts imports"| node_import
node_import -->|"loads and saves"| node_storage
node_import -.->|"parses song text"| node_bridge
node_serverapp -->|"resolves paths"| node_storage
node_serverapp -->|"wires MIDI"| node_midi
node_serverapp -->|"creates store"| node_live
node_serverapp -->|"uses presence"| node_presence
node_serverapp -.->|"wires transport"| node_transport
node_admin -.->|"controls show"| node_serverapp
node_client -.->|"tracks show state"| node_clienttransport
node_clienttransport -.->|"syncs over LAN"| node_serverapp
node_timeline -.->|"edits timing"| node_tempo
node_audio -->|"resolves tempo"| node_tempo
node_audio -.->|"syncs playback"| node_clienttransport
node_desktop -.->|"connects to host"| node_serverapp
node_androidclient -.->|"joins host"| node_serverapp
node_androidhost -->|"starts local host"| node_serverapp

click node_admin "https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/shells/admin/AdminShell.tsx"
click node_timeline "https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/shells/timeline/lanes/useTimelineLanePointerHandlers.ts"
click node_import "https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/shells/admin/useAdminImportHandlers.ts"
click node_serverapp "https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/app.ts"
click node_transport "https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/transport/engine.ts"
click node_storage "https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/storage/index.ts"
click node_midi "https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/midi/host.ts"
click node_presence "https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/presence/client-presence.ts"
click node_live "https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/live-desk/live-desk.ts"
click node_client "https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/shells/client/ClientShell.tsx"
click node_audio "https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/lib/audio/audio-playback/sync-engine.ts"
click node_clienttransport "https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/transport/useTransportSocket.ts"
click node_desktop "https://github.com/kacperczeczot/stagesync/blob/main/apps/desktop/launcher/app.js"
click node_androidhost "https://github.com/kacperczeczot/stagesync/blob/main/apps/console/android/app/src/main/java/com/stagesync/console/LocalHostService.kt"
click node_androidclient "https://github.com/kacperczeczot/stagesync/blob/main/apps/performer/android/app/src/main/java/com/stagesync/performer/HostWebActivity.kt"
click node_bridge "https://github.com/kacperczeczot/stagesync/blob/main/packages/shared/src/text-anchor-bridge/bridge-orchestrator.ts"
click node_tempo "https://github.com/kacperczeczot/stagesync/blob/main/packages/shared/src/time-tempo/time.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_admin,node_timeline,node_import toneBlue
class node_serverapp,node_transport,node_storage,node_midi,node_presence,node_live toneAmber
class node_client,node_audio,node_clienttransport toneMint
class node_desktop,node_androidhost,node_androidclient toneRose
class node_bridge,node_tempo,node_operator toneIndigo
```

## Components

### Operator and Editing

- [Admin console](https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/shells/admin/AdminShell.tsx): `apps/web/src/shells/admin/AdminShell.tsx`
- [Timeline editor](https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/shells/timeline/lanes/useTimelineLanePointerHandlers.ts): `apps/web/src/shells/timeline/lanes/useTimelineLanePointerHandlers.ts`
- [Song import](https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/shells/admin/useAdminImportHandlers.ts): `apps/web/src/shells/admin/useAdminImportHandlers.ts`

### Show Server

- [API and runtime](https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/app.ts): `apps/server/src/app.ts`
- [Transport SSOT](https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/transport/engine.ts): `apps/server/src/transport/engine.ts`
- [Project storage](https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/storage/index.ts): `apps/server/src/storage/index.ts`
- [MIDI automation](https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/midi/host.ts): `apps/server/src/midi/host.ts`
- [Client presence](https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/presence/client-presence.ts): `apps/server/src/presence/client-presence.ts`
- [Live desk](https://github.com/kacperczeczot/stagesync/blob/main/apps/server/src/live-desk/live-desk.ts): `apps/server/src/live-desk/live-desk.ts`

### Performer Clients

- [Performer shell](https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/shells/client/ClientShell.tsx): `apps/web/src/shells/client/ClientShell.tsx`
- [Synced audio](https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/lib/audio/audio-playback/sync-engine.ts): `apps/web/src/lib/audio/audio-playback/sync-engine.ts`
- [Transport socket](https://github.com/kacperczeczot/stagesync/blob/main/apps/web/src/transport/useTransportSocket.ts): `apps/web/src/transport/useTransportSocket.ts`

### Launch and Hosting

- [Desktop launcher](https://github.com/kacperczeczot/stagesync/blob/main/apps/desktop/launcher/app.js): `apps/desktop/launcher/app.js`
- [Android local host](https://github.com/kacperczeczot/stagesync/blob/main/apps/console/android/app/src/main/java/com/stagesync/console/LocalHostService.kt): `apps/console/android/app/src/main/java/com/stagesync/console/LocalHostService.kt`
- [Android performer](https://github.com/kacperczeczot/stagesync/blob/main/apps/performer/android/app/src/main/java/com/stagesync/performer/HostWebActivity.kt): `apps/performer/android/app/src/main/java/com/stagesync/performer/HostWebActivity.kt`

### Shared Show Logic

- [Text bridge import](https://github.com/kacperczeczot/stagesync/blob/main/packages/shared/src/text-anchor-bridge/bridge-orchestrator.ts): `packages/shared/src/text-anchor-bridge/bridge-orchestrator.ts`
- [Tempo map logic](https://github.com/kacperczeczot/stagesync/blob/main/packages/shared/src/time-tempo/time.ts): `packages/shared/src/time-tempo/time.ts`

### Other components

- **Show operator**

## Connections

- Show operator → Admin console: operates
- Admin console → Timeline editor: edits projects
- Admin console → Song import: starts imports (evidence: `apps/web/src/shells/admin/useAdminImportHandlers.ts`)
- Song import → Project storage: loads and saves (evidence: `apps/web/src/shells/admin/useAdminImportHandlers.ts`)
- Song import → Text bridge import: parses song text
- API and runtime → Project storage: resolves paths (evidence: `apps/server/src/app.ts`)
- API and runtime → MIDI automation: wires MIDI (evidence: `apps/server/src/app.ts`)
- API and runtime → Live desk: creates store (evidence: `apps/server/src/app.ts`)
- API and runtime → Client presence: uses presence (evidence: `apps/server/src/app.ts`)
- API and runtime → Transport SSOT: wires transport (evidence: `apps/server/src/app.ts`)
- Admin console → API and runtime: controls show
- Performer shell → Transport socket: tracks show state
- Transport socket → API and runtime: syncs over LAN
- Timeline editor → Tempo map logic: edits timing
- Synced audio → Tempo map logic: resolves tempo (evidence: `apps/web/src/lib/audio/audio-playback/sync-engine.ts`)
- Synced audio → Transport socket: syncs playback
- Desktop launcher → API and runtime: connects to host
- Android performer → API and runtime: joins host
- Android local host → API and runtime: starts local host (evidence: `apps/console/android/app/src/main/java/com/stagesync/console/LocalHostService.kt`)