# omarsuniaga/suniplayer architecture

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

- Interactive diagram: https://gitdiagram.com/omarsuniaga/suniplayer
- Repository: https://github.com/omarsuniaga/suniplayer

## Overview

SuniPlayer is a cross-platform live-performance tool: musicians prepare repertoire and timed sets, then run them through a player with queue and live/edit modes. The web app is the more mature implementation; native provides mobile audio and persistence, while core holds shared domain state and services. The graph includes documented import, history/recovery, track-profile, and collaboration capabilities. Several UI-to-service links are dashed because the relevant implementations were not sampled; solid links are limited to relationships shown in excerpts or the source index.

Main entry points: [`packages/core/src/network/SessionManager.ts`](https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/network/SessionManager.ts) (Session manager), [`apps/web/src/pages/Player.tsx`](https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/pages/Player.tsx) (Live player), [`apps/native/app/_layout.tsx`](https://github.com/omarsuniaga/suniplayer/blob/main/apps/native/app/_layout.tsx) (Native app), [`apps/web/src/store/useProjectStore.ts`](https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/store/useProjectStore.ts) (Project state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_webapp["Web app<br/>[App.tsx]"]
  node_builder["Set builder<br/>[Builder.tsx]"]
  node_library["Library and import<br/>[Library.tsx]"]
  node_player["Live player<br/>[Player.tsx]"]
  node_history["History dashboard<br/>[History.tsx]"]
  node_nativeapp["Native app<br/>[_layout.tsx]"]
end

subgraph group_domain["Shared domain"]
  node_setservice["Set generation"]
  node_projectstate["Project state<br/>[useProjectStore.ts]"]
  node_playerstate["Player state<br/>[usePlayerStore.ts]"]
  node_sessionrecovery["Session recovery"]
end

subgraph group_platform["Platform services"]
  node_webstorage[("Browser storage<br/>[IDBStorage.ts]")]
  node_nativeaudio["Native audio engine<br/>[ExpoAudioEngine.ts]"]
  node_nativestorage[("Native storage<br/>[SQLiteStorage.ts]")]
  node_corestorage["Storage bridge<br/>[storage.ts]"]
end

subgraph group_collaboration["Live collaboration"]
  node_markers["Track markers"]
  node_syncui["Sync controls"]
  node_sessionmanager["Session manager<br/>[SessionManager.ts]"]
  node_clock["Clock synchronization"]
  node_yjs["Shared state<br/>[YjsStore.ts]"]
  node_p2p["P2P transport<br/>[P2PTransport.ts]"]
end

node_musician(("Musician"))

node_musician -->|"prepares and performs"| node_webapp
node_musician -->|"uses mobile app"| node_nativeapp
node_builder -.->|"generates sets"| node_setservice
node_library -.->|"manages repertoire"| node_projectstate
node_player -.->|"controls playback"| node_playerstate
node_player -.->|"plays audio"| node_nativeaudio
node_player -.->|"edits markers"| node_markers
node_history -.->|"recovers sessions"| node_sessionrecovery
node_sessionrecovery -->|"captures and restores"| node_projectstate
node_projectstate -->|"uses shared state"| node_playerstate
node_corestorage -.->|"delegates storage"| node_webstorage
node_corestorage -.->|"delegates storage"| node_nativestorage
node_sessionmanager -->|"registers handlers"| node_p2p
node_sessionmanager -->|"connects shared state"| node_yjs
node_sessionmanager -->|"uses clock sync"| node_clock
node_sessionmanager -->|"updates session state"| node_playerstate
node_syncui -.->|"coordinates sessions"| node_sessionmanager
node_nativeapp -.->|"uses audio engine"| node_nativeaudio
node_nativeapp -.->|"persists locally"| node_nativestorage

click node_webapp "https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/App.tsx"
click node_builder "https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/pages/Builder.tsx"
click node_library "https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/pages/Library.tsx"
click node_player "https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/pages/Player.tsx"
click node_history "https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/pages/History.tsx"
click node_markers "https://github.com/omarsuniaga/suniplayer/tree/main/apps/web/src/features/collaboration/markers"
click node_syncui "https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/services/network/SyncEnsembleOrchestrator.ts"
click node_setservice "https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/services/setBuilderService.ts"
click node_projectstate "https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/store/useProjectStore.ts"
click node_playerstate "https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/store/usePlayerStore.ts"
click node_sessionrecovery "https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/services/showSessionStorage.ts"
click node_sessionmanager "https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/network/SessionManager.ts"
click node_clock "https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/network/clockSyncService.ts"
click node_yjs "https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/network/crdt/YjsStore.ts"
click node_webstorage "https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/platform/browser/IDBStorage.ts"
click node_nativeapp "https://github.com/omarsuniaga/suniplayer/blob/main/apps/native/app/_layout.tsx"
click node_nativeaudio "https://github.com/omarsuniaga/suniplayer/blob/main/apps/native/src/platform/ExpoAudioEngine.ts"
click node_nativestorage "https://github.com/omarsuniaga/suniplayer/blob/main/apps/native/src/platform/SQLiteStorage.ts"
click node_corestorage "https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/store/storage.ts"
click node_p2p "https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/network/P2PTransport.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_webapp,node_builder,node_library,node_player,node_history,node_nativeapp toneBlue
class node_setservice,node_projectstate,node_playerstate,node_sessionrecovery toneAmber
class node_webstorage,node_nativeaudio,node_nativestorage,node_corestorage toneMint
class node_markers,node_syncui,node_sessionmanager,node_clock,node_yjs,node_p2p toneRose
class node_musician toneIndigo
```

## Components

### Web experience

- [Web app](https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Set builder](https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/pages/Builder.tsx): `apps/web/src/pages/Builder.tsx`
- [Library and import](https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/pages/Library.tsx): `apps/web/src/pages/Library.tsx`
- [Live player](https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/pages/Player.tsx): `apps/web/src/pages/Player.tsx`
- [History dashboard](https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/pages/History.tsx): `apps/web/src/pages/History.tsx`
- [Native app](https://github.com/omarsuniaga/suniplayer/blob/main/apps/native/app/_layout.tsx): `apps/native/app/_layout.tsx`

### Shared domain

- [Set generation](https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/services/setBuilderService.ts): `packages/core/src/services/setBuilderService.ts`
- [Project state](https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/store/useProjectStore.ts): `apps/web/src/store/useProjectStore.ts`
- [Player state](https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/store/usePlayerStore.ts): `packages/core/src/store/usePlayerStore.ts`
- [Session recovery](https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/services/showSessionStorage.ts): `apps/web/src/services/showSessionStorage.ts`

### Platform services

- [Browser storage](https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/platform/browser/IDBStorage.ts): `apps/web/src/platform/browser/IDBStorage.ts`
- [Native audio engine](https://github.com/omarsuniaga/suniplayer/blob/main/apps/native/src/platform/ExpoAudioEngine.ts): `apps/native/src/platform/ExpoAudioEngine.ts`
- [Native storage](https://github.com/omarsuniaga/suniplayer/blob/main/apps/native/src/platform/SQLiteStorage.ts): `apps/native/src/platform/SQLiteStorage.ts`
- [Storage bridge](https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/store/storage.ts): `packages/core/src/store/storage.ts`

### Live collaboration

- [Track markers](https://github.com/omarsuniaga/suniplayer/tree/main/apps/web/src/features/collaboration/markers): `apps/web/src/features/collaboration/markers`
- [Sync controls](https://github.com/omarsuniaga/suniplayer/blob/main/apps/web/src/services/network/SyncEnsembleOrchestrator.ts): `apps/web/src/services/network/SyncEnsembleOrchestrator.ts`
- [Session manager](https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/network/SessionManager.ts): `packages/core/src/network/SessionManager.ts`
- [Clock synchronization](https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/network/clockSyncService.ts): `packages/core/src/network/clockSyncService.ts`
- [Shared state](https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/network/crdt/YjsStore.ts): `packages/core/src/network/crdt/YjsStore.ts`
- [P2P transport](https://github.com/omarsuniaga/suniplayer/blob/main/packages/core/src/network/P2PTransport.ts): `packages/core/src/network/P2PTransport.ts`

### Other components

- **Musician**

## Connections

- Musician → Web app: prepares and performs (evidence: `README.md`)
- Musician → Native app: uses mobile app (evidence: `README.md`)
- Set builder → Set generation: generates sets
- Library and import → Project state: manages repertoire
- Live player → Player state: controls playback
- Live player → Native audio engine: plays audio
- Live player → Track markers: edits markers
- History dashboard → Session recovery: recovers sessions
- Session recovery → Project state: captures and restores (evidence: `apps/web/src/services/showSessionStorage.ts`)
- Project state → Player state: uses shared state (evidence: `apps/web/src/store/useProjectStore.ts`)
- Storage bridge → Browser storage: delegates storage
- Storage bridge → Native storage: delegates storage
- Session manager → P2P transport: registers handlers (evidence: `packages/core/src/network/SessionManager.ts`)
- Session manager → Shared state: connects shared state (evidence: `packages/core/src/network/SessionManager.ts`)
- Session manager → Clock synchronization: uses clock sync (evidence: `packages/core/src/network/SessionManager.ts`)
- Session manager → Player state: updates session state (evidence: `packages/core/src/network/SessionManager.ts`)
- Sync controls → Session manager: coordinates sessions
- Native app → Native audio engine: uses audio engine
- Native app → Native storage: persists locally