# toghroltp/pealayer architecture

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

- Interactive diagram: https://gitdiagram.com/toghroltp/pealayer
- Repository: https://github.com/toghroltp/pealayer
- Video tour (about a minute): https://gitdiagram.com/toghroltp/pealayer/video

## Overview

Pealayer combines desktop video playback and a 4D cue editor with a background hardware-control engine; an HTTP/WebSocket service exposes playback and media browsing to a browser remote. The graph follows the documented playback-to-timeline-to-device workflow and the sampled calls from the app and editor into the engine. Sidecar pairing, recording, and some UI behavior are documented capabilities, but their precise internal wiring is not fully visible in the excerpts.

Main entry points: [`src/app.rs`](https://github.com/toghroltp/pealayer/blob/main/src/app.rs) (Player App), [`src/ui/layout.rs`](https://github.com/toghroltp/pealayer/blob/main/src/ui/layout.rs) (Timeline Editor), [`src/server/mod.rs`](https://github.com/toghroltp/pealayer/blob/main/src/server/mod.rs) (HTTP / WS Server), [`src/four_d/engine.rs`](https://github.com/toghroltp/pealayer/blob/main/src/four_d/engine.rs) (Cue Scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Player"]
  node_app["Player App<br/>[app.rs]"]
  node_ui["Player Panels"]
  node_video["mpv Renderer<br/>[render.rs]"]
end

subgraph group_timeline["4D Timeline"]
  node_timeline_ui["Timeline Editor<br/>[layout.rs]"]
  node_models["Timeline Models<br/>[models.rs]"]
  node_history["Undo History<br/>[history.rs]"]
  node_patterns["Effect Patterns<br/>[patterns.rs]"]
  node_curve["Analog Curves<br/>[curve.rs]"]
  node_curve_record["Curve Recording<br/>[curve_record.rs]"]
end

subgraph group_hardware["Hardware Engine"]
  node_engine["Cue Scheduler<br/>[engine.rs]"]
  node_protocol["Serial Protocol<br/>[protocol.rs]"]
end

subgraph group_remote["Remote Control"]
  node_webui["Browser Remote<br/>[App.tsx]"]
  node_remote_controls["Remote Controls"]
  node_server["HTTP / WS Server<br/>[mod.rs]"]
  node_fs_api["Media Browsing<br/>[fs_api.rs]"]
  node_thumbnails["Thumbnail Service<br/>[thumbnails.rs]"]
end

subgraph group_platform["Platform Integration"]
  node_interop["Command Bridge<br/>[interop.rs]"]
end

node_user(("Viewer / Editor"))
node_mpv["libmpv"]
node_device(("Serial Controller"))
node_media(("Media Files / Streams"))
node_sidecar["4D Sidecar Data"]

node_user -->|"operates"| node_app
node_app -->|"renders"| node_ui
node_app -->|"controls playback"| node_mpv
node_app -->|"renders frames"| node_video
node_video -->|"requests frames"| node_mpv
node_media -->|"opens"| node_app
node_app -->|"hosts editor"| node_timeline_ui
node_timeline_ui -->|"edits cues"| node_models
node_timeline_ui -->|"tracks edits"| node_history
node_timeline_ui -->|"compiles and sends queue"| node_engine
node_app -->|"sends playback updates"| node_engine
node_app -->|"updates analog tracks"| node_curve
node_patterns -->|"creates effects"| node_models
node_curve_record -->|"records curve data"| node_models
node_engine -->|"encodes commands"| node_protocol
node_engine -->|"writes serial commands"| node_device
node_user -->|"uses remote"| node_webui
node_webui -->|"shows controls"| node_remote_controls
node_webui -->|"sends commands and polls state"| node_server
node_server -->|"dispatches commands and state"| node_app
node_app -->|"handles interop commands"| node_interop
node_server -->|"browses and trashes media"| node_fs_api
node_server -->|"requests thumbnails"| node_thumbnails
node_fs_api -->|"reads media folders"| node_media
node_thumbnails -->|"reads media files"| node_media
node_app -->|"pairs timeline on open"| node_sidecar

click node_app "https://github.com/toghroltp/pealayer/blob/main/src/app.rs"
click node_ui "https://github.com/toghroltp/pealayer/tree/main/src/ui"
click node_video "https://github.com/toghroltp/pealayer/blob/main/src/mpv/render.rs"
click node_timeline_ui "https://github.com/toghroltp/pealayer/blob/main/src/ui/layout.rs"
click node_models "https://github.com/toghroltp/pealayer/blob/main/src/four_d/models.rs"
click node_history "https://github.com/toghroltp/pealayer/blob/main/src/four_d/history.rs"
click node_patterns "https://github.com/toghroltp/pealayer/blob/main/src/four_d/patterns.rs"
click node_curve "https://github.com/toghroltp/pealayer/blob/main/src/four_d/curve.rs"
click node_curve_record "https://github.com/toghroltp/pealayer/blob/main/src/four_d/curve_record.rs"
click node_engine "https://github.com/toghroltp/pealayer/blob/main/src/four_d/engine.rs"
click node_protocol "https://github.com/toghroltp/pealayer/blob/main/src/four_d/protocol.rs"
click node_webui "https://github.com/toghroltp/pealayer/blob/main/web_ui/src/App.tsx"
click node_remote_controls "https://github.com/toghroltp/pealayer/blob/main/web_ui/src/components/RemoteControlTab.tsx"
click node_server "https://github.com/toghroltp/pealayer/blob/main/src/server/mod.rs"
click node_fs_api "https://github.com/toghroltp/pealayer/blob/main/src/server/fs_api.rs"
click node_thumbnails "https://github.com/toghroltp/pealayer/blob/main/src/server/thumbnails.rs"
click node_interop "https://github.com/toghroltp/pealayer/blob/main/src/platform/interop.rs"

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_app,node_ui,node_video,node_user toneBlue
class node_timeline_ui,node_models,node_history,node_patterns,node_curve,node_curve_record toneAmber
class node_engine,node_protocol toneMint
class node_webui,node_remote_controls,node_server,node_fs_api,node_thumbnails toneRose
class node_interop,node_mpv,node_device,node_media,node_sidecar toneIndigo
```

## Components

### Desktop Player

- [Player App](https://github.com/toghroltp/pealayer/blob/main/src/app.rs): `src/app.rs`
- [Player Panels](https://github.com/toghroltp/pealayer/tree/main/src/ui): `src/ui`
- [mpv Renderer](https://github.com/toghroltp/pealayer/blob/main/src/mpv/render.rs): `src/mpv/render.rs`

### 4D Timeline

- [Timeline Editor](https://github.com/toghroltp/pealayer/blob/main/src/ui/layout.rs): `src/ui/layout.rs`
- [Timeline Models](https://github.com/toghroltp/pealayer/blob/main/src/four_d/models.rs): `src/four_d/models.rs`
- [Undo History](https://github.com/toghroltp/pealayer/blob/main/src/four_d/history.rs): `src/four_d/history.rs`
- [Effect Patterns](https://github.com/toghroltp/pealayer/blob/main/src/four_d/patterns.rs): `src/four_d/patterns.rs`
- [Analog Curves](https://github.com/toghroltp/pealayer/blob/main/src/four_d/curve.rs): `src/four_d/curve.rs`
- [Curve Recording](https://github.com/toghroltp/pealayer/blob/main/src/four_d/curve_record.rs): `src/four_d/curve_record.rs`

### Hardware Engine

- [Cue Scheduler](https://github.com/toghroltp/pealayer/blob/main/src/four_d/engine.rs): `src/four_d/engine.rs`
- [Serial Protocol](https://github.com/toghroltp/pealayer/blob/main/src/four_d/protocol.rs): `src/four_d/protocol.rs`

### Remote Control

- [Browser Remote](https://github.com/toghroltp/pealayer/blob/main/web_ui/src/App.tsx): `web_ui/src/App.tsx`
- [Remote Controls](https://github.com/toghroltp/pealayer/blob/main/web_ui/src/components/RemoteControlTab.tsx): `web_ui/src/components/RemoteControlTab.tsx`
- [HTTP / WS Server](https://github.com/toghroltp/pealayer/blob/main/src/server/mod.rs): `src/server/mod.rs`
- [Media Browsing](https://github.com/toghroltp/pealayer/blob/main/src/server/fs_api.rs): `src/server/fs_api.rs`
- [Thumbnail Service](https://github.com/toghroltp/pealayer/blob/main/src/server/thumbnails.rs): `src/server/thumbnails.rs`

### Platform Integration

- [Command Bridge](https://github.com/toghroltp/pealayer/blob/main/src/platform/interop.rs): `src/platform/interop.rs`

### Other components

- **Viewer / Editor**
- **libmpv**
- **Serial Controller**
- **Media Files / Streams**
- **4D Sidecar Data**

## Connections

- Viewer / Editor → Player App: operates
- Player App → Player Panels: renders
- Player App → libmpv: controls playback
- Player App → mpv Renderer: renders frames
- mpv Renderer → libmpv: requests frames
- Media Files / Streams → Player App: opens
- Player App → Timeline Editor: hosts editor
- Timeline Editor → Timeline Models: edits cues
- Timeline Editor → Undo History: tracks edits
- Timeline Editor → Cue Scheduler: compiles and sends queue
- Player App → Cue Scheduler: sends playback updates
- Player App → Analog Curves: updates analog tracks
- Effect Patterns → Timeline Models: creates effects
- Curve Recording → Timeline Models: records curve data
- Cue Scheduler → Serial Protocol: encodes commands
- Cue Scheduler → Serial Controller: writes serial commands
- Viewer / Editor → Browser Remote: uses remote
- Browser Remote → Remote Controls: shows controls
- Browser Remote → HTTP / WS Server: sends commands and polls state
- HTTP / WS Server → Player App: dispatches commands and state
- Player App → Command Bridge: handles interop commands
- HTTP / WS Server → Media Browsing: browses and trashes media
- HTTP / WS Server → Thumbnail Service: requests thumbnails
- Media Browsing → Media Files / Streams: reads media folders
- Thumbnail Service → Media Files / Streams: reads media files
- Player App → 4D Sidecar Data: pairs timeline on open