# sbernauer/breakwater architecture

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

- Interactive diagram: https://gitdiagram.com/sbernauer/breakwater
- Repository: https://github.com/sbernauer/breakwater

## Overview

Breakwater is a Pixelflut server: clients send newline-delimited or binary pixel commands, the server parses them into a shared framebuffer, and concurrently enabled sinks display or distribute that canvas. The graph preserves the documented web, native, VNC, RTMP, NDI, and Prometheus capabilities. Server/parser internals and web HTTP/state modules are represented where paths are supported; sink-specific wiring beyond sampled excerpts follows the documented capabilities and sink dispatcher.

Main entry points: [`breakwater/src/sinks/mod.rs`](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/mod.rs) (Sink dispatcher), [`breakwater-parser/src/framebuffer/shared_memory.rs`](https://github.com/sbernauer/breakwater/blob/main/breakwater-parser/src/framebuffer/shared_memory.rs) (Shared framebuffer), [`breakwater/src/main.rs`](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/main.rs) (Runtime startup), [`breakwater/src/server.rs`](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/server.rs) (TCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_entry["Runtime startup<br/>[main.rs]"]
  node_server["TCP server<br/>[server.rs]"]
  node_buffer["Connection buffer"]
end

subgraph group_pixels["Pixel processing"]
  node_parser["Command parsers<br/>[lib.rs]"]
  node_framebuffer[("Shared framebuffer<br/>[shared_memory.rs]")]
  node_simplefb[("Simple framebuffer<br/>[simple.rs]")]
  node_trackingfb[("Time tracking<br/>[time_tracking.rs]")]
end

subgraph group_outputs["Canvas outputs"]
  node_sinkdispatch["Sink dispatcher<br/>[mod.rs]"]
  node_web["Web sink<br/>[mod.rs]"]
  node_webapi["HTTP and WebSocket<br/>[http_api.rs]"]
  node_webstate["Web shared state<br/>[state.rs]"]
  node_egui["egui display<br/>[mod.rs]"]
  node_winit["winit display<br/>[winit.rs]"]
  node_vnc["VNC sink<br/>[vnc.rs]"]
  node_ffmpeg["FFmpeg stream<br/>[ffmpeg.rs]"]
  node_ndi["NDI source<br/>[ndi.rs]"]
end

subgraph group_observability["Statistics and metrics"]
  node_stats["Statistics<br/>[statistics.rs]"]
  node_prometheus["Prometheus exporter"]
end

node_clients(("Pixelflut clients"))
node_browser(("Web spectators"))
node_display(("Native viewers"))
node_vncclient(("VNC viewers"))
node_rtmp(("RTMP destination"))
node_ndireceiver(("NDI receivers"))
node_metrics(("Prometheus scraper"))

node_clients -->|"send commands"| node_server
node_entry -->|"creates"| node_framebuffer
node_entry -->|"starts"| node_server
node_server -->|"buffers input"| node_buffer
node_server -->|"parses commands"| node_parser
node_parser -->|"reads and writes pixels"| node_framebuffer
node_server -->|"reports connection events"| node_stats
node_entry -->|"starts"| node_stats
node_entry -->|"starts enabled sinks"| node_sinkdispatch
node_sinkdispatch -->|"dispatches"| node_web
node_sinkdispatch -->|"dispatches"| node_egui
node_sinkdispatch -->|"dispatches"| node_winit
node_sinkdispatch -->|"dispatches"| node_vnc
node_sinkdispatch -->|"dispatches"| node_ffmpeg
node_sinkdispatch -->|"dispatches"| node_ndi
node_web -->|"reads pixels"| node_framebuffer
node_web -->|"publishes frames and stats"| node_webstate
node_webapi -->|"serves shared channels"| node_webstate
node_web -->|"serves routes"| node_webapi
node_browser -->|"connects"| node_webapi
node_egui -->|"reads canvas"| node_framebuffer
node_egui -->|"renders"| node_display
node_winit -->|"reads canvas"| node_framebuffer
node_winit -->|"renders"| node_display
node_vnc -->|"reads canvas"| node_framebuffer
node_vnc -->|"serves display"| node_vncclient
node_ffmpeg -->|"reads canvas"| node_framebuffer
node_ffmpeg -.->|"streams video"| node_rtmp
node_ndi -->|"reads canvas"| node_framebuffer
node_ndi -.->|"publishes source"| node_ndireceiver
node_stats -->|"broadcasts information"| node_prometheus
node_entry -->|"starts exporter"| node_prometheus
node_metrics -->|"scrapes metrics"| node_prometheus

click node_entry "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/main.rs"
click node_server "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/server.rs"
click node_buffer "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/connection_buffer.rs"
click node_parser "https://github.com/sbernauer/breakwater/blob/main/breakwater-parser/src/lib.rs"
click node_framebuffer "https://github.com/sbernauer/breakwater/blob/main/breakwater-parser/src/framebuffer/shared_memory.rs"
click node_simplefb "https://github.com/sbernauer/breakwater/blob/main/breakwater-parser/src/framebuffer/simple.rs"
click node_trackingfb "https://github.com/sbernauer/breakwater/blob/main/breakwater-parser/src/framebuffer/time_tracking.rs"
click node_sinkdispatch "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/mod.rs"
click node_web "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/web/mod.rs"
click node_webapi "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/web/http_api.rs"
click node_webstate "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/web/state.rs"
click node_egui "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/egui/mod.rs"
click node_winit "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/winit.rs"
click node_vnc "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/vnc.rs"
click node_ffmpeg "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/ffmpeg.rs"
click node_ndi "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/ndi.rs"
click node_stats "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/statistics.rs"
click node_prometheus "https://github.com/sbernauer/breakwater/blob/main/breakwater/src/prometheus_exporter.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_entry,node_server,node_buffer,node_clients,node_display,node_vncclient toneBlue
class node_parser,node_framebuffer,node_simplefb,node_trackingfb toneAmber
class node_sinkdispatch,node_web,node_webapi,node_webstate,node_egui,node_winit,node_vnc,node_ffmpeg,node_ndi toneMint
class node_stats,node_prometheus toneRose
class node_browser,node_rtmp,node_ndireceiver,node_metrics toneIndigo
```

## Components

### Server runtime

- [Runtime startup](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/main.rs): `breakwater/src/main.rs`
- [TCP server](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/server.rs): `breakwater/src/server.rs`
- [Connection buffer](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/connection_buffer.rs): `breakwater/src/connection_buffer.rs`

### Pixel processing

- [Command parsers](https://github.com/sbernauer/breakwater/blob/main/breakwater-parser/src/lib.rs): `breakwater-parser/src/lib.rs`
- [Shared framebuffer](https://github.com/sbernauer/breakwater/blob/main/breakwater-parser/src/framebuffer/shared_memory.rs): `breakwater-parser/src/framebuffer/shared_memory.rs`
- [Simple framebuffer](https://github.com/sbernauer/breakwater/blob/main/breakwater-parser/src/framebuffer/simple.rs): `breakwater-parser/src/framebuffer/simple.rs`
- [Time tracking](https://github.com/sbernauer/breakwater/blob/main/breakwater-parser/src/framebuffer/time_tracking.rs): `breakwater-parser/src/framebuffer/time_tracking.rs`

### Canvas outputs

- [Sink dispatcher](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/mod.rs): `breakwater/src/sinks/mod.rs`
- [Web sink](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/web/mod.rs): `breakwater/src/sinks/web/mod.rs`
- [HTTP and WebSocket](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/web/http_api.rs): `breakwater/src/sinks/web/http_api.rs`
- [Web shared state](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/web/state.rs): `breakwater/src/sinks/web/state.rs`
- [egui display](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/egui/mod.rs): `breakwater/src/sinks/egui/mod.rs`
- [winit display](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/winit.rs): `breakwater/src/sinks/winit.rs`
- [VNC sink](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/vnc.rs): `breakwater/src/sinks/vnc.rs`
- [FFmpeg stream](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/ffmpeg.rs): `breakwater/src/sinks/ffmpeg.rs`
- [NDI source](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/sinks/ndi.rs): `breakwater/src/sinks/ndi.rs`

### Statistics and metrics

- [Statistics](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/statistics.rs): `breakwater/src/statistics.rs`
- [Prometheus exporter](https://github.com/sbernauer/breakwater/blob/main/breakwater/src/prometheus_exporter.rs): `breakwater/src/prometheus_exporter.rs`

### Other components

- **Pixelflut clients**
- **Web spectators**
- **Native viewers**
- **VNC viewers**
- **RTMP destination**
- **NDI receivers**
- **Prometheus scraper**

## Connections

- Pixelflut clients → TCP server: send commands
- Runtime startup → Shared framebuffer: creates
- Runtime startup → TCP server: starts
- TCP server → Connection buffer: buffers input
- TCP server → Command parsers: parses commands
- Command parsers → Shared framebuffer: reads and writes pixels
- TCP server → Statistics: reports connection events
- Runtime startup → Statistics: starts
- Runtime startup → Sink dispatcher: starts enabled sinks
- Sink dispatcher → Web sink: dispatches
- Sink dispatcher → egui display: dispatches
- Sink dispatcher → winit display: dispatches
- Sink dispatcher → VNC sink: dispatches
- Sink dispatcher → FFmpeg stream: dispatches
- Sink dispatcher → NDI source: dispatches
- Web sink → Shared framebuffer: reads pixels
- Web sink → Web shared state: publishes frames and stats
- HTTP and WebSocket → Web shared state: serves shared channels
- Web sink → HTTP and WebSocket: serves routes
- Web spectators → HTTP and WebSocket: connects
- egui display → Shared framebuffer: reads canvas
- egui display → Native viewers: renders
- winit display → Shared framebuffer: reads canvas
- winit display → Native viewers: renders
- VNC sink → Shared framebuffer: reads canvas
- VNC sink → VNC viewers: serves display
- FFmpeg stream → Shared framebuffer: reads canvas
- FFmpeg stream → RTMP destination: streams video
- NDI source → Shared framebuffer: reads canvas
- NDI source → NDI receivers: publishes source
- Statistics → Prometheus exporter: broadcasts information
- Runtime startup → Prometheus exporter: starts exporter
- Prometheus scraper → Prometheus exporter: scrapes metrics