docs/development/ holds one page per kind of change (settings, State Store and persistence, task lifecycle, workflows and steps, event automation, dashboard, agent execution and containers, processes and wiring, merging work), each naming every layer the change must reach and pointing at the document that owns the design. The docs build puts them in the development set; docs/index.md and CLAUDE.md link them. Also adds the container-profile case to the validator agreement test, the check the profiles work skipped.
2.3 KiB
2.3 KiB
Processes and wiring
Authority: docs/architecture/organisation.md (layers, process boundaries),
docs/architecture/dependencies-and-contracts.md (dependency direction, wire
contracts) and docs/architecture/plugins-and-extensions.md (the plugin engine
rule).
Placing new code
- Domain logic, entities and the interfaces it needs go in
internal/domain/<area>/, which imports no infrastructure or app package. - Implementations of those interfaces go in
internal/infrastructure/<service>/. - Construction and wiring go in
internal/app/<application>/;cmd/only parses flags and calls it. logging,events,eventbus,policyandtaskstateimport no internal package. There is noshared/,utils/orcommon/package.- A behaviour has one authoritative path. Before adding a second way to do something, remove or redirect the first.
Adding a capability to a process
- Decide which process owns it. A new binary is justified only when the surface must fail, scale or run somewhere independently.
- Wire it at that process's composition root. An optional capability degrades: a missing provider logs a warning and marks health degraded rather than stopping the process (MCP providers are the model).
- Every process that reaches the capability through the State Store gets it
through a
storecontractinterface asserted on the client (State Store and persistence). - The architecture tests (
cmd/archie-ui/architecture_test.go,cmd/archie-messaging/architecture_test.go,TestOpenStoresNeverOwnsTaskDB) pin what each binary may link. A failure there means the placement is wrong, not the test.
Adding a plugin engine
Satisfy every invariant in "Plugin engine rule (strict)" in
plugins-and-extensions.md: typed domain contract, an owning manager,
lifecycle and health, narrow host access, and an explicit trust boundary.
internal/plugin/architecture_test.go checks the parts that can be checked.
Adding a channel or a NATS subject
- Channel rules (Telegram's pending-update drop, command scopes) are in
CLAUDE.mdunder Per-Package Invariants. - A subject is part of the wire contract. Its payload type belongs to the domain that defines its meaning, and the transport code lives in infrastructure.