Gabriel Kaszewski
6ad76b98a2
CONTEXT.md: domain model with entities (WidgetConfig, DataSource, LayoutPreset), value objects (Layout, LayoutNode, KeyMapping, WidgetState, Sizing), architecture decisions (CQRS, static dispatch, postcard), client domain model, and design constraints.
27 lines
1.1 KiB
Markdown
27 lines
1.1 KiB
Markdown
# 0003 — postcard over FlatBuffers
|
|
|
|
**Status:** accepted
|
|
**Date:** 2026-06-18
|
|
|
|
## Context
|
|
|
|
Need a binary serialization format for the TCP protocol between server and ESP32 clients. Must be compact (bandwidth-constrained), ideally `no_std` compatible for future bare-metal targets.
|
|
|
|
## Decision
|
|
|
|
Use `postcard` with `serde` derives instead of FlatBuffers.
|
|
|
|
## Alternatives considered
|
|
|
|
**FlatBuffers** — zero-copy reads, schema-driven. But requires external codegen toolchain (flatc), `no_std` support is limited, and zero-copy is overkill for our small messages (a handful of widgets).
|
|
|
|
**Custom binary protocol** — maximum control, zero deps. But significant implementation effort for serialize/deserialize code, error-prone, and postcard already solves this.
|
|
|
|
## Consequences
|
|
|
|
- `no_std` protocol crate out of the box — future-proof for bare-metal targets.
|
|
- No codegen step — types are normal Rust structs with serde derives.
|
|
- Compact wire format via varint encoding.
|
|
- No zero-copy reads — messages are deserialized into owned types. Acceptable for our message sizes.
|
|
- Adds `serde` and `postcard` as dependencies to the protocol crate.
|