Commit bb579b7
docs: rewrite ARCHITECTURE.md for the current core/adapter/compose/client shape
The previous version described the pre-refactor runtime topology almost
verbatim (a known gap flagged in PR #20's description) — barely touched since
before the hexagonal rewrite despite the whole runtime changing underneath it.
Rewritten to cover:
- The five rings (core/adapter/compose/client/cmd) and the dependency rule
that holds them apart, with a mermaid diagram.
- Rationale: why core/ is import-restricted (archtest's actual forbidden
list), what that buys in practice (testability, one-command-core/N-transports,
real embedded targets, config/protocol separation), and why compose/ and
client/ are their own rings rather than living under cmd/ and adapter/.
- A full directory map (core/, adapter/, compose/, client/, cmd/) with a
one-line role for every subpackage.
- Runtime composition (config -> registry -> cross-wire -> supervisor) and a
concrete data-flow walkthrough (an AFP read over EtherTalk vs. over DSI),
both as mermaid diagrams.
- A new client-architecture section: the client/afp.Session interface as the
client-side mirror of the server's CommandHandler/CommandCircuit split, the
redial-as-injected-closure reconnect design, and why the fork backend
differs by scheme — none of this was in the doc before.
- Control-plane/web-UI split (brief; full depth stays in docs/web-ui.md).
- Embedded targets: cmd/cs-tinygo (the real, passing, narrow core subset) vs.
hardware/{esp32,pico} (the full desktop stack, not yet green) and the
established !tinygo/tinygo split pattern for OS-API gaps.
- Testing structure overview.
- A "how to expand" section with concrete recipes (new port, new DDP service,
new session transport, new fs backend, new client scheme, new control
front-end, new config section), each pointing at a real existing example.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>1 parent 76bcb8a commit bb579b7
1 file changed
Lines changed: 570 additions & 111 deletions
0 commit comments