Customers who want to extend the library had two paths: read the
1200-line apps/secs_server.cpp and guess at conventions, or read
every store header and infer the shape. Neither is reasonable.
ARCHITECTURE.md walks the five layers (apps → Router+Model →
stores → FSMs → transport+codec) with a worked extension recipe
per layer:
- New SECS-II message (YAML edit + Router handler — no core code)
- New state machine (lift from ept_state.hpp or process_job_state.hpp)
- New store (paste-and-adapt from alarms.hpp or process_jobs.hpp)
- New persistence backend (mirror enable_persistence pattern)
- New transport (mirror Connection's contract)
Explains the design choices that look unusual:
- Spec-as-data — every behavioural rule in YAML, C++ is the engine
- I/O-free FSMs — transport classes own asio, everything else is pure
- Single-threaded by design + no locks anywhere
- No DI framework, no singletons, no shared_ptr-everywhere
- Exceptions only for programmer-error / corrupt-input paths
Documents the persistence magic-byte registry (0xC4-0xC9 + 0xE5)
so the next contributor doesn't collide; documents the codegen
pipeline (messages.yaml → gen_messages.py → messages.hpp); maps
"you want to understand X" → "read these files in order" for the
twelve most common entry points.
Doc map in README already points at ARCHITECTURE.md from the prior
commit.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
