Files
archie/docs/development/wiring.md
T
sam 173e059bc8 docs(development): organise the guides by area
One page per area: frontend UI, agent, workflows, daemon (task lifecycle and
event automation together), State Store, control plane and settings, and
processes and wiring, with merging work kept separate.
2026-09-24 21:05:29 +10:00

49 lines
2.2 KiB
Markdown

# 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`, `policy` and `taskstate` import no internal
package. There is no `shared/`, `utils/` or `common/` 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
1. Decide which process owns it. A new binary is justified only when the
surface must fail, scale or run somewhere independently.
2. 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).
3. Every process that reaches the capability through the State Store gets it
through a `storecontract` interface asserted on the client
([State Store](state-store.md)).
4. 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.md` under 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.