# SlimeVR Server Architecture This document explains how the server is structured, why it's structured that way, and how to extend it correctly. --- ## Mental Model Every significant part of the server a tracker, a UDP connection, a SolarXR session, a config file is a **module**. Every module is a list of behaviours sharing one context: ![Architecture diagram](architecture.svg) That's the entire system. Everything else is an application of this pattern. --- ## Why This Pattern The server handles many concurrent connections, each with independent state that many other components need to observe. A shared mutable object works fine until two coroutines update it at the same time, or you need to know *when* something changed, or you want to add a feature without touching existing code. The reducer pattern solves all three: - **Thread safety**: `StateFlow.update` is atomic. Concurrent dispatches serialize without locks. - **Observability**: `context.state` is a hot `StateFlow` it always holds the current value and any code can `collect` it and react to changes without being coupled to the producer. - **Extensibility**: adding a feature means adding a `Behaviour` to a list. Nothing else changes. The cost is that you cannot mutate state directly. Everything goes through `dispatch`. That constraint is the point. --- ## The Context `Context` (`context/context.kt`) holds the current state as a `StateFlow`, the coroutine scope that defines this module's lifetime, and the behaviour list. ```kotlin class Context( val state: StateFlow, val scope: CoroutineScope, val behaviours: CopyOnWriteArrayList>, ) { fun dispatch(action: A) fun dispatchAll(actions: List) fun observeAll(receiver: C) } ``` `Context.create` takes an initial state and a list of behaviours. On each `dispatch`, it folds every behaviour's `reduce` over the current state in order and publishes the result. Behaviours that don't care about an action return the state unchanged. `dispatchAll(actions)` applies a list of actions in one atomic `StateFlow.update`. Use it when you need multiple state changes to be visible as one - intermediate states are never published, so no observer fires between them. `observeAll(receiver)` calls `observe(receiver)` on every behaviour in the list. This is how observation is wired after construction - see [Module Lifecycle](#module-lifecycle). The `behaviours` list is a `CopyOnWriteArrayList`. This allows adding behaviours after construction, which is needed for modules whose behaviour list depends on runtime context (e.g. `TrackingChecklist` adds step behaviours in `startObserving`). --- ## Behaviours A behaviour is one feature of a module. It has two methods, both optional: ```kotlin interface Behaviour { fun reduce(state: S, action: A): S = state // pure, no side effects fun observe(receiver: C) {} // side effects go here } ``` `reduce` is a pure function - it cannot launch coroutines, call external services, or read from a clock. It just maps `(state, action) → state`. `observe` is called once after construction, after the context exists. This is where you launch coroutines, subscribe to flows, register event listeners. All coroutines launched here should use `receiver.context.scope` so they die when the module dies - no manual cleanup, no leaks. **Why behaviours instead of methods on the module class?** The natural alternative is one class with methods for each feature - ping handling, handshake logic, sensor registration, timeout detection, all in the same file. That works until the class has 20 features and every change has global blast radius. Behaviours make the feature list explicit: you read `create()`, you see exactly what the module does. Adding or removing a feature is one line in that list, touching nothing else. **Why `observe` is separate from `reduce`:** `reduce` must stay pure so state transitions are testable and predictable. Side effects in `observe` are isolated - a behaviour that logs packets doesn't affect state, a behaviour that saves config doesn't affect packet handling. ### Scoping Behaviours to Module Lifetime Every behaviour's coroutines run inside `receiver.context.scope`. When a UDP connection drops, its scope is cancelled, which cancels every coroutine every behaviour launched for that connection. No teardown code needed anywhere. This is why `observe` receives the module (or context) rather than taking a raw `CoroutineScope` parameter - it enforces that behaviours cannot outlive their module. ### Stateless vs. Stateful Behaviours All behaviours are `class`es, instantiated at the call site: ```kotlin class PacketBehaviour : UDPConnectionBehaviour { ... } val behaviours = listOf(PacketBehaviour(), PacketLossBehaviour(), HandshakeBehaviour()) ``` Even behaviours with no constructor arguments are `class`es. `object` is banned for behaviours because `observe()` often needs to capture mutable state (timers, counters, flags). An `object` shares that state across every module instance that uses it — a subtle, hard-to-trace bug. Requiring `class` enforces that each module instance gets its own behaviour instance, with its own isolated state. The allocation cost is negligible. Behaviours that need external services take them as constructor arguments: ```kotlin class TrackerConfigBehaviour( private val settings: Settings, private val hardwareId: String, ) : TrackerBehaviour { ... } ``` When a behaviour is conditional (depends on a nullable service), use `buildList`: ```kotlin val behaviours: List = buildList { add(AlwaysPresentBehaviour()) optionalService?.let { add(OptionalServiceBehaviour(it)) } } ``` For modules like `SolarXRBridge` where the behaviour list is large and reusable, extract it into a named function on the companion object: ```kotlin companion object { fun buildBehaviours(appContext: AppContextProvider): List = buildList { add(DataFeedInitBehaviour(appContext.server, appContext.skeleton)) add(FirmwareBehaviour(appContext.server, appContext.firmwareManager)) // ... } } ``` This lets tests call `buildBehaviours` with a stub context, or ignore it entirely and construct the module directly with only the behaviours they need. ### The Receiver Type The type parameter `C` controls what `observe` receives. For simple modules where behaviours only need to dispatch or subscribe to state, `C` is the context itself. For modules where behaviours also need to call methods (send bytes, emit events), `C` is the module class: ```kotlin // behaviours only dispatch/observe state typealias GlobalConfigBehaviour = Behaviour // behaviours also call receiver.send(), receiver.packetEvents.on(...) typealias UDPConnectionBehaviour = Behaviour ``` ### File Layout Behaviours live in a `behaviours.kt` file in the same package as the module, separate from the module class itself: ``` tracker/ ├── module.kt ← Tracker class, TrackerState, TrackerActions, typealiases ├── behaviours.kt ← TrackerBasicBehaviour, TrackerTPSBehaviour, ... └── config.kt ← TrackerConfigBehaviour (its own file - distinct concern) ``` `module.kt` is the standard name for the file containing the module class, state, actions, and typealiases. `behaviours.kt` holds the implementations. For modules with many distinct feature areas, split behaviours by feature instead of one file - `solarxr/` uses this: `datafeed.kt`, `firmware.kt`, `provisioning.kt`, etc. each live alongside `module.kt`. --- ## Module Lifecycle Every module has a two-step lifecycle: **construction** then **observation wiring**. ```kotlin // Step 1: create the module (pure construction, no side effects) val manager = FirmwareManager.create(ctx = phase1, scope = scope) // Step 2: wire observation (launches coroutines, subscribes to flows) manager.startObserving() ``` `create()` builds the context with its behaviour list and constructs the module. No coroutines are launched, no flows are subscribed. The module is inert. `startObserving()` calls `context.observeAll(this)`, which calls `observe(receiver)` on every behaviour. This is where all side effects begin. **Why separate construction from observation?** Some modules need to exist before all their dependencies are assembled. For example, `TrackingChecklist` is constructed before `AppContext` exists, but its step behaviours depend on `Skeleton` and `VRCConfigManager` which are part of `AppContext`. By deferring observation, the module can be constructed in any order and wired later: ```kotlin // Constructed early - no AppContext needed yet val trackingChecklist = TrackingChecklist.create(scope = this) // AppContext assembled from all modules val appContext = AppContext(server, config, serialServer, skeleton, ..., trackingChecklist) // Observation wired now - TrackingChecklist adds its step behaviours using AppContext appContext.startObserving() ``` `AppContext.startObserving()` calls `startObserving()` on every bootstrap module in sequence, and `trackingChecklist.startObserving(appContext)` adds its behaviours to `context.behaviours` before calling `context.observeAll(this)`. **Runtime modules** (UDP connections, SolarXR bridges, HID receivers) are created and immediately observed - they have all their dependencies at creation time: ```kotlin val bridge = SolarXRBridge.create(id = id, appContext = appContext, scope = scope) // startObserving() is called inside create() ``` --- ## Dependency Injection The server uses a typed context hierarchy for dependency injection. Contexts are interfaces - modules declare the minimum phase they need in `create()`, which gives compile-time guarantees that their dependencies exist. ``` Phase1ContextProvider └── AppContextProvider ``` **`Phase1ContextProvider`** - the bootstrap phase. Available before `AppContext` is assembled: ```kotlin interface Phase1ContextProvider { val server: VRServer val config: AppConfig val serialServer: SerialServer } ``` **`AppContextProvider`** - the full application context. Available after all bootstrap modules are constructed: ```kotlin interface AppContextProvider : Phase1ContextProvider { val skeleton: Skeleton val firmwareManager: FirmwareManager val vrcConfigManager: VRCConfigManager? val provisioningManager: ProvisioningManager val heightCalibrationManager: HeightCalibrationManager val trackingChecklist: TrackingChecklist fun startObserving() } ``` **The rule:** always use `AppContextProvider` unless the module genuinely cannot be constructed after `AppContext` is assembled. In practice, only bootstrap modules (`FirmwareManager`, `Skeleton`, `ProvisioningManager`, `HeightCalibrationManager`) use `Phase1ContextProvider` in `create()`. Runtime modules like `SolarXRBridge` always receive `AppContextProvider`. The concrete classes `Phase1Context` and `AppContext` implement these interfaces. Tests implement the interfaces directly with only the fields they need - see [Testing](#testing). --- ## Actions Actions are `sealed interface`s. This matters because the compiler enforces exhaustive `when` in reducers - you cannot forget to handle a new action type. Named actions also mean you can grep for all places a specific transition can occur. ```kotlin sealed interface UDPConnectionActions { data class Handshake(val deviceId: Int) : UDPConnectionActions data class LastPacket(val packetNum: Long?, val time: Long) : UDPConnectionActions data object Disconnected : UDPConnectionActions } ``` The choice between a flexible `Update` action and a named action is about who else needs to react: - **`Update`** when only the caller cares about the change. It carries a lambda that transforms state directly. No other behaviour pattern-matches it, so there's no coupling. - **Named action** when other behaviours need to react to this specific event. `Handshake` in `UDPConnectionActions` signals to multiple behaviours that a connection is now established; each one matches it independently. ```kotlin // Nothing else needs to react - use Update tracker.context.dispatch(TrackerActions.Update { copy(tps = newTps) }) // Multiple behaviours react to this - use a named action connection.context.dispatch(UDPConnectionActions.Handshake(deviceId = id)) ``` If you find yourself dispatching an `Update` that other behaviours start matching against, it's time to promote it to a named action. --- ## EventDispatcher `EventDispatcher` routes events to typed listeners. Each behaviour registers its own listener in `observe`: ```kotlin receiver.packetEvents.on { packet -> ... } // only SensorInfo receiver.packetEvents.onAny { packet -> ... } // every packet ``` **Why not a central `when` block?** A central switch means every new packet type requires editing the dispatch hub. With `EventDispatcher`, each behaviour owns its subscription. Adding a new packet type means adding a class to `packets.kt` and a listener in a behaviour - the routing hub never changes. It also means behaviours are self-contained: `SensorInfoBehaviour` is the only place that knows what to do with `SensorInfo`. No shared routing code. `EventDispatcher` dispatches by the runtime type of the event by default. When events are wrapped (e.g. `PacketEvent` where the actual packet is the inner value), pass a `keyOf` lambda to tell the dispatcher which type to route by - otherwise all events would be bucketed under `PacketEvent` regardless of the inner packet type. --- ## Coroutine Scope and Lifetime Every module receives a `CoroutineScope` at creation. That scope defines when the module lives and dies: - Cancelling the scope cancels all coroutines - all behaviours launched inside it - No `close()`, `stop()`, or `dispose()` methods needed anywhere - A disconnected client, a dropped UDP connection, a closed serial port - all cleaned up by scope cancellation Blocking I/O goes on `Dispatchers.IO`. State updates and logic stay on the default dispatcher. Never use `runBlocking` inside an observer - it blocks the coroutine thread pool. --- ## State vs. Plain Data Not everything needs to be in a `StateFlow`. The rule: **put data in state only if other code needs to react to it changing**. - `VRServer.handleCounter` is an `AtomicInt` - nothing reacts to it, so a dispatch round-trip would be waste. - `UDPTrackerServer` has no `Context` at all. Its connection map is a `MutableMap` internal to the server loop. Nothing outside reads it. - Tracker config *is* in state because the SolarXR layer and the config autosave both react to body part assignments changing. --- ## Cross-Module Communication Modules don't call each other directly. A behaviour in one module subscribes to another module's `StateFlow` and dispatches into its own context (or another module's context) when something relevant changes. Two common patterns: **React to another module's state:** ```kotlin // Inside TrackerConfigBehaviour.observe() // When tracker state changes, persist the relevant fields to Settings receiver.context.state .distinctUntilChangedBy { stateToConfig(it) } .drop(1) .onEach { state -> settings.context.dispatch(SettingsActions.UpdateTracker(hardwareId) { stateToConfig(state) }) } .launchIn(receiver.context.scope) ``` **Dispatch into VRServer from a connection:** ```kotlin // Inside HandshakeBehaviour.observe() - a UDP connection registers a new device receiver.packetEvents.on { event -> val device = Device.create(...) receiver.serverContext.context.dispatch(VRServerActions.NewDevice(deviceId, device)) } ``` The key rule: behaviours own the subscription lifetime via `launchIn(receiver.context.scope)`. When the module dies, the subscription stops - no dangling listeners in foreign modules. --- ## IPC and Transport The server exposes four connection points: | Transport | Client | Protocol | |---|---|---| | Unix socket `SlimeVRRpc` | SolarXR (IPC path) | FlatBuffers | | WebSocket port 21110 | GUI / third-party (SolarXR) | FlatBuffers | **Why separate transport from protocol?** Platform files (e.g. `unix.kt`) own reading frames off a socket and produce a `Flow` + a `send` function. Protocol handlers (`protocol.kt`, `ipc.kt`) are plain `suspend fun`s that take those two things and know nothing about the specific transport being used. The same `handleSolarXRBridge` function runs on Unix domain sockets, and WebSocket. The WebSocket adapter in `ws-server.kt` converts Ktor frames to the same `Flow` + `send` abstraction. The handler never changes. **Why events for IPC message routing?** Same reason as UDP packets. The SolarXR protocol has dozens of RPC message types. Behaviours that handle firmware updates, skeleton config, data feeds, etc. each register their own listener on the `rpcDispatcher`. Adding a new RPC handler doesn't touch existing ones. ### Wire Framing (named sockets) All three named sockets use the same framing: a **LE u32 length** prefix (including the 4-byte header itself) followed by the raw payload bytes. ### UDP Packet Pipeline The UDP receive loop runs on `Dispatchers.IO`. It reads a datagram, parses the packet type and payload via `readPacket`, wraps the result in a `PacketEvent`, and pushes it into a `Channel>` per connection. A dedicated coroutine per connection drains the channel and calls `EventDispatcher.emit`. Pre-handshake packets are filtered at the channel drain step - a single guard in one place, not spread across every behaviour. --- ## Config Config is not just file I/O - it is a live state machine. The server supports runtime profile switching, so config data lives in a `StateFlow` like everything else. Code that needs to react to config changes (e.g. tracker body part assignment saving to disk) subscribes to the settings state flow. The config system has three layers: - **`AppConfig`** - global state: which user profile and settings profile are active - **`UserConfig`** - per-user data (body proportions, etc.) - **`Settings`** - per-profile settings (tracker assignments, port, VRC warnings); persists to disk Each is a full module with its own `Context`, behaviours, and JSON autosave. Migrations live in the module's `parseAndMigrate` function - add a `version < N` branch there. --- ## Testing The module pattern is designed to be testable at each layer independently. ### Testing reducers Create a context directly with the behaviours you want to test. No module class, no scope tricks: ```kotlin val context = Context.create( initialState = FirmwareManagerState(jobs = mapOf()), scope = this, behaviours = listOf(FirmwareManagerBaseBehaviour()), ) context.dispatch(FirmwareManagerActions.UpdateJob(...)) assertEquals(FirmwareUpdateStatus.UPLOADING, context.state.value.jobs["COM1"]?.status) ``` ### Testing observe behaviour Construct the module directly - bypassing `create()` - with only the behaviours relevant to the test. This avoids constructing unrelated dependencies: ```kotlin val serialServer = buildTestSerialServer(backgroundScope) val context = Context.create( initialState = ProvisioningManager.INITIAL_STATE, scope = backgroundScope, behaviours = listOf(ProvisioningManagerBaseBehaviour()), ) val manager = ProvisioningManager(context = context, serialServer = serialServer, scope = backgroundScope) manager.startObserving() manager.startProvisioning(buildTestVrServer(backgroundScope), "wifi", "pass", null) ``` For modules that need an `AppContextProvider` (e.g. `SolarXRBridge`), extend `TestAppContext` and override only what the test uses. Every other field defaults to `error("not used in test")`: ```kotlin val server = buildTestVrServer(backgroundScope) val skeleton = buildTestSkeleton(backgroundScope) val appContext = object : TestAppContext() { override val server = server override val skeleton = skeleton } val context = Context.create( initialState = SolarXRBridgeState(dataFeedConfigs = listOf()), scope = backgroundScope, behaviours = listOf(DataFeedInitBehaviour(server, skeleton)), ) val bridge = SolarXRBridge(id = 1, context = context, appContext = appContext, dataFeedDispatcher = EventDispatcher(), rpcDispatcher = EventDispatcher()) bridge.startObserving() ``` `TestAppContext` lives in `TestServer.kt`. When a new module is added to `AppContextProvider`, add a default stub there - all existing tests automatically get the default without changes. **The pattern:** only initialize what the test exercises. If a behaviour accesses a field that isn't overridden, it throws - that's intentional. It keeps tests focused and stubs minimal. ### Test helpers (`TestServer.kt`) `buildTestVrServer`, `buildTestSerialServer`, `buildTestUserConfig`, and `buildTestSkeleton` are available for constructing real lightweight instances of common dependencies. --- ## What Goes Where | Location | Purpose | |---|---| | `server/core` | Protocol-agnostic business logic | | `server/desktop` | Platform entry point, IPC wiring, HID, serial flash | | `context/context.kt` | `Context` and `Behaviour` primitives - no domain logic here | | `udp/` | UDP wire protocol: connection state, packets, behaviours, server loop | | `hid/` | HID tracker receiver: registration, rotation, battery, status | | `solarxr/` | `SolarXRBridge` + per-feature behaviour files (one per RPC area) | | `config/` | 3-tier config: `AppConfig`, `UserConfig`, `Settings` | | `firmware/` | OTA and serial flash; independent of UDP tracker protocol | | `trackingchecklist/` | Checklist steps as behaviours observing server/tracker/VRC state | | `skeleton/` | Skeleton solving, proportions, bone geometry | | `vrchat/` | VRChat config monitoring and recommended-value computation | --- ## Extending the Server ### Adding a New Module 1. **Define state and actions** in `module.kt`: ```kotlin data class MyState(val connected: Boolean) sealed interface MyActions { data object Connected : MyActions data object Disconnected : MyActions } typealias MyContext = Context typealias MyBehaviour = Behaviour ``` 2. **Define the module class** with a `create()` factory and a `startObserving()` method: ```kotlin class MyModule(val context: MyContext, val server: VRServer) { fun startObserving() = context.observeAll(this) companion object { fun create(ctx: Phase1ContextProvider, scope: CoroutineScope): MyModule { val context = Context.create( initialState = MyState(false), scope = scope, behaviours = listOf(MyCoreBehaviour()), ) return MyModule(context, ctx.server) } } } ``` 3. **Register in `AppContext`** and call `startObserving()` inside `AppContext.startObserving()`. 4. **Write behaviours** in `behaviours.kt` (or per-feature files for large modules). ### Adding a Behaviour to an Existing Module Add it to the `behaviours` list in `create()`. The behaviour's `reduce` and `observe` are automatically wired when `startObserving()` is called. Nothing else changes. ### Adding a New UDP Packet Type 1. Add the packet class and its `read` function in `udp/packets.kt` 2. Add an entry to the `PacketType` enum and a branch in `readPacket()` 3. Register a listener in a behaviour's `observe`: ```kotlin receiver.packetEvents.on { event -> receiver.context.dispatch(...) } ``` --- ## Style Conventions - **Prefer plain functions over classes.** A single-method interface should almost always be a function type (`() -> Unit`, `suspend (ByteArray) -> Unit`). When in doubt, write a function. - **Behaviours are always `class`, never `object`.** Even behaviours with no constructor arguments. `observe()` frequently captures mutable state (timers, counters, flags), and a singleton `object` would share that state across every module instance — a subtle, cross-connection bug. Instantiate every behaviour at the call site: `listOf(PacketBehaviour(), PingBehaviour())`. - **Prefer plain functions over extension functions.** Only use extensions when the receiver type is genuinely the primary subject. - **State data classes are all `val`.** Mutable fields in a state class are a design mistake - use `var` in a plain class if you need local mutability, never in state. - **Use `sealed interface` for actions**, not `sealed class` - no constructor overhead. - **Module creation lives in `companion object { fun create(...) }`.** - **Module observation wiring lives in `startObserving()`**, called via `context.observeAll(this)`. - **Never expose `MutableStateFlow` directly.** Expose `StateFlow` via `context.state`.