Design Notes
Per-slice deep-dive design documentation.
Purpose
These docs explain how each implemented slice actually works in code — the class shapes, runtime flows, lifecycle states, and load-bearing decisions that the spec intentionally abstracted. They're reference material for anyone modifying or extending an existing slice's surface area.
The audience is a future maintainer who needs to understand "if I touch this code tomorrow, what hangs together" — not a reviewer evaluating whether to ship the slice (specs cover that), and not a Copilot agent executing the implementation (tasks cover that).
When to read which doc
| Situation | Read |
|---|---|
| Modifying the multi-tag pipeline, adding a new tag, changing emit cadence | SLICE-1.1 design |
| Learning the multi-tag flow as an app scenario and C#/.NET walkthrough | SLICE-1.1 telemetry deep dive |
| Touching frame allocation, the WriteableBitmap renderer, LOH pressure | SLICE-1.2 design |
| Learning the frame flow from run start to WPF preview and GC behavior | SLICE-1.2 frame pipeline deep dive |
| Working on the encoder pipeline, timer-resolution issues, channel back-pressure | SLICE-1.3 design |
| Tuning chaos parameters, adding a fault-injection mode, the FlakySdk decorator | SLICE-1.4 design |
| Modifying the FlaUI capture rig, scenario classes, the PowerShell orchestrator | SLICE-1.6 design |
Document template
Each design doc follows the same 7-section structure so future maintainers can scan them consistently:
- Quick reference — key types, files, tests, metrics
- Class shape — ASCII class diagram of the slice's main types
- Lifecycle — state diagram if the slice owns state, otherwise omitted
- Runtime flow — ASCII sequence diagram(s) for the main path(s)
- Decisions made during implementation — design choices that aren't in the spec ("why this shape")
- Invariants and traps — load-bearing facts a future maintainer must know before changing things
- Test surface — what's covered, what isn't, and why
Companion docs
- SLICE-1.1 telemetry deep dive — scenario-first walkthrough of the multi-tag flow, configuration knobs, and C#/.NET techniques
- SLICE-1.2 frame pipeline deep dive — scenario-first walkthrough of camera streaming, payload allocation, bounded frames, and WPF rendering
- Phase 1 Retrospective — cross-slice synthesis, the three measurement-criterion amendments, Phase 2 prioritization
- Phase 1 Measurements — captured row blocks per slice
- Roadmap Progress — per-slice status table + chronological session log
- Architecture overview — cross-cutting structural docs (system context, layer map, runtime sequences)
Coverage
Phase 1 (5 slices, all completed):
- ✅ SLICE-1.1 — multi-tag telemetry
- ✅ SLICE-1.2 — real frame payloads
- ✅ SLICE-1.3 — encoder-rate motion
- ✅ SLICE-1.4 — storm & soak profiles
- ✅ SLICE-1.6 — FlaUI capture rig
SLICE-1.5 / 1.5.1 were superseded mid-phase and have no design notes; their architectural choices live in their specs (linked from the Roadmap Progress page).
Phase 2: not yet implemented. SLICE-2.0 (store allocation profiling) is the next slice to land; design notes will follow once the implementation is merged.