The audit this PRD-class doc carried (archie-core-6pg1) was superseded by the ratified UI boundary and the shipped phase, but the doc still read as though UI extraction were pending: the open-questions heading called itself blocking before implementation, the coupling inventory said UI extraction "must remove" the config.Holder alias, and Q3 still described the State Store as defaulting local with a not-yet-extracted caveat (Phase 2 deleted every local fallback and made an empty target a startup error). State what is true: three phases shipped, the third coupling is closed, the remaining holder alias is daemon-internal (archie-core-ml30) rather than a cross-service coupling, and the open questions are historical record.
14 KiB
Service decomposition -- decision
Status: Proposed -- not yet approved for implementation
Progress: Phases 1 (Gateway), 2 (State Store) and 3 (UI) shipped; Phase 4
(Messaging) is ready, Phase 5 (Execution/Runner/Scheduler) and Phase 6
(Curator, optional) remain chained behind it.
Date: 2026-09-05
Beads epic: archie-core-8cda
Prior art: docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md,
docs/inspiration/module-reference-awx-decomposition-vs-archie.md,
docs/inspiration/service-discovery-research-2026-09-05.md,
/work/artefacts/archie-core-current-state-archify.html,
/work/artefacts/archie-core-ideal-state-archify.html
The Phase 3 UI boundary and configuration decision is ratified in
ui-service-boundary.md. That focused document is
the implementation authority for archie-core-8cda.5.2; this parent remains
the broader service-distribution proposal.
Decision
archie-core moves from one Go binary (archied) hosting every domain
in-process to a set of independently deployable services, each exposing
exactly one typed contract. Consumers depend on the contract; they never
reach into another service's internal types, session state, or config.
gRPC is the synchronous transport; NATS remains for asynchronous fan-out
(status, telemetry) rather than being replaced.
This is a distribution decision, not a rewrite of Archie's domain
model. The six-domain split already approved in
docs/architecture/index.md and docs/architecture/organisation.md
(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;
this PRD is about how the processes running that domain logic get
packaged, contracted, and discovered -- not about redrawing domain
boundaries.
Target services
| Service | Contract it owns | Existing code it replaces/wraps |
|---|---|---|
| UI Service | thin client only; talks to Gateway and State Store contracts | internal/webui (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |
| Gateway Service | routing / turn / session contract | internal/gateway |
| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | internal/channels |
| Curator Service | curator contract; optional, installs as a Gateway plugin | internal/domain/curator |
| Scheduler Service | cron/ticker contract | internal/domain/scheduling |
| Execution Environment | execution-dispatch contract | internal/domain/workflow, task dispatch paths |
| Runner | isolated worktree/container execution | internal/container, internal/agentexec, internal/worktree |
| State Store | state-access contract | internal/store |
Discovery
Per docs/inspiration/service-discovery-research-2026-09-05.md:
-
Primary: Kubernetes-native discovery (Service + headless-Service/DNS
- EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator, on k3s for single-host installs and a real cluster for multi-host or a hosted offering.
-
Fallback: NATS-based discovery (micro
$SRVannounce + JetStream KV registry) for no-K8s single-host installs, with a custom gRPC resolver readinghost:portfrom the KV bucket. -
Both implementations sit behind one internal interface:
type ServiceRegistry interface { Resolve(service string) []Endpoint Watch(service string) <-chan Event // join/leave } -
An optional service (Curator today; others later) that is not installed must resolve to a distinct
NotInstalledoutcome, never aDown/Unhealthyone. Under K8s this falls out of DNS returning no record; under the NATS fallback it requires an explicit "installed" marker in the KV registry, not just absence-implies-down.
Distribution model this supports
Both self-hosted (customer runs the Helm chart or the NATS-fallback binaries themselves) and a managed/hosted offering (we run the same Helm chart) are in scope -- this is the RHEL / Ansible Automation Platform model: one architecture, sold both ways. This PRD does not decide the business model; it decides that the architecture must not foreclose either shape.
Why this shape
docs/inspiration/module-reference-awx-decomposition-vs-archie.md
established that Archie's existing domain split already does what AWX's
service-decomposition post argues for -- boundaries exist. What didn't
exist was deployability: internal/webui was not a passive frontend. That is
now resolved; the re-baselined coupling inventory is below, and the ratified
boundary is ui-service-boundary.md.
- Telegram task actions now call Gateway's
ChatContractdirectly throughchatTaskActorAdapter; the old Telegram-to-webui HTTP detour is historical. internal/webui/api_chat.gonow holdsgateway.ChatContract; directSessionStore,Router, andTurnHistoryaccess is historical.- The third coupling is closed. UI extraction shipped (
archie-core-8cda.5, closed 2026-09-11):cmd/archie-uiserves the dashboard against remote Gateway and State Store contracts, holds noconfig.Holder, and relinks no daemon runtime (cmd/archie-ui/architecture_test.goenforces that on everytask check). Theb.web.Cfg = b.d.Cfgalias left inbuildDaemonis now inside the daemon's own process -- it renders the publishedConfigViewsnapshot and holds the readiness probes -- so it no longer crosses a service boundary. That cleanup isarchie-core-ml30(P2); the UI boundary is ratified inui-service-boundary.md.
Non-goals
- Redesigning the domain model (Identity/Agent/Messaging/Workflow/Work Intake/Plugin boundaries are settled elsewhere and unchanged).
- Replacing NATS. It remains the async transport; this PRD only adds gRPC for synchronous request/response and (optionally) K8s-native discovery.
- Deciding the business model (self-hosted vs. managed vs. both). Kept open deliberately; the architecture must serve either.
- Config relocation (
config.toml-> ConfigMaps/Secrets) is real work implied by a K8s-native deployment but is its own decision, not decided here. Flagged in the discovery research as a phased concern. - Any concrete adoption of Pi (or another external agent harness) as an
execution runner. Raised in conversation alongside this decomposition,
but it is a separate decision (agent execution as a strict data
boundary,
ARCHITECTURE.md) and does not gate or get gated by this PRD.
Open questions
All ten are resolved; each carries its resolution inline. Three phases have since shipped against them (Gateway, State Store, UI), so the framing here is historical record rather than an outstanding gate.
-
Extraction order. Which service gets pulled out of the monolith first? The webui entanglement findings above suggest Gateway Service's
ChatContractshould exist before UI Service is extracted, since UI is the most entangled consumer today. Not yet sequenced.RESOLVED (2026-09-05). Gateway Service first, then State Store, then UI, then Messaging, then Execution/Runner/Scheduler, then Curator (optional) — preceded by an in-process "contract seams" (modular monolith) phase. Confirms the hypothesis and strengthens it: the Gateway is already store-decoupled (it uses narrow contract adapters, not
internal/store) and already owns an isolated session SQLite, so it is both the stickiest capability and the one with a ready seam and isolated data — extractable alone, first. Full phase list and reasoning:docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#1. -
Contract definition mechanism. Protobuf/gRPC service definitions need a home (a new
proto/orcontracts/tree, versioning scheme, codegen wiring intoTaskfile.yml). Not yet designed.RESOLVED (2026-09-05). buf v2 driving
protoc-gen-go+protoc-gen-go-grpc(grpc-go, not connect-go — connect-go's net/http client breaks the discovery research's gRPC resolver plumbing for K8s DNS and NATS-KV). One committedproto/<service>/v1/tree, generated Go committed tointernal/contracts/<service>/v1/, directory versioning (breaking change -> newvN, enforced bybuf breakingin the gate), andtask proto:generate/proto:lint/proto:checkwired intotask checkand mirrored into.github/workflows/deploy.yml(CI does not runtask check). Full toolchain comparison, layout rationale, and scratch-verifiedbuf/buf breaking/connect-goresults:docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#2. -
In-process vs. out-of-process during migration. Whether services can run multiplexed inside one binary behind the same
ServiceRegistryinterface during a transition period (so extraction is incremental and testable) or whether each service must be a separate binary from day one. Strongly recommend the former for a solo maintainer, but not decided here.RESOLVED (2026-09-05). Multiplexed in-process is the migration default -- this is
docs/architecture/organisation.md's standing "Process boundaries" rule, not a new lean. Mechanism: one wire-safe Go contract interface per service; a local adapter and a generated gRPC client adapter, both satisfying the same interface via a compile-time assertion (thevar _ workflow.Store = (*Client)(nil)idiom;store.WorkflowStoreis superseded by the consumer-ownedworkflow.Store); composition (notServiceRegistry, which stays network-only) picks the adapter by the presence of a[services.<name>].targetaddress -- empty = local (in-process) adapter, set = dial the remote gRPC client. This replaced the earliermode = "inproc" | "remote"enum, which was dropped (see the gateway'sservices.gateway.target). The adapter is chosen by presence of the target; Phase 2 then deleted every local fallback, so remote is now the only mode and an empty[services.state].targetis a startup error (docs/prds/state-store-contract.md §12 step 7). A per-contract conformance suite runs against both adapters overbufconn; the flip to a real process is a same-commit deletion of the in-process path, no dual-live window. Consequence: Gateway's Phase 0 (ChatContractseam) ships in-process first, with the network protocol staying out of the production path until Phase 1 -- no amendment to Q1's phase list needed. Full mechanism and evidence:docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#3(the State Store's concrete ratified config shape isdocs/prds/state-store-contract.md§10). -
State Store's contract shape. Whether every service gets its own storage (true microservice isolation) or several services share the State Store service's contract (less isolation, less migration risk). Not yet decided.
RESOLVED (2026-09-05). One State Store service owns the existing single SQLite file behind narrow typed contracts (
TaskStore,CaptureStore,MappingStore,BindingStore,WorkflowStore) over gRPC. (Ratified 2026-09-06: the workflow contract is now the domain-ownedworkflow.Store, which supersedesinternal/store'sWorkflowStore. See note below anddocs/prds/state-store-contract.md.) No physical database-per-service: the solo-maintainer / team- topology rule of thumb plus the low value of per-service autonomy for one person rule it out, and one store means no distributed-transactions problem. The Gateway keeps its own already-separate session SQLite. Concrete migration path (generalisestorerpc, swap consumers one contract at a time, stand up the store service, split the file only on evidence):docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#4.RATIFIED (2026-09-06, beads archie-core-8cda.4.1). The authoritative contract boundary & transport design for this is fixed in
docs/prds/state-store-contract.md(rev. 2c): oneStateStoregRPC service, 42 RPCs; ownership split — consumer-ownedworkflow.Store+workflow.Task/Status/Sourcein the workflow domain (dependency rules #2/#7), producer-owned daemon/webui store surfaces ininternal/store; theTask/Status/Source+ interface relocation is a Phase 2 prerequisite pulled from migration-decisions §4 (store.Task → WorkflowExecution);RecordDispatchdrops*sql.Tx;Closeoff-wire; structured gRPC error codes with sanitised details; explicit agent State Store gRPC handoff (STATE_STORE_URL/STATE_STORE_TOKEN); loopback+bearer transport-security boundary; presence-based[services.state].targetdefaulting local; migration orderworkflow.Store -> archie-state-store -> Capture -> Mapping -> Binding -> TaskStore..4.2and.4.3implement against that doc. -
Helm chart / Operator ownership. Net-new work with no existing analog in this repository (
deployments/currently holds TOML profiles and adocker-compose.yml, not Kubernetes manifests). Scoping not yet started.RESOLVED (2026-09-05). Three charts: an
archie-librarychart (shared Deployment/Service templates, named ports), anarchiechart for the 7 core services, and anarchie-curatorchart + Curator Operator (CRD, controller, RBAC). The Curator reconciler is a level-triggered loop that fetches the CR, builds Deployment + Service, sets owner refs, applies idempotently (CreateOrUpdate), watches viaOwns(), and reports aReadystatus condition. Smallest real milestone (M1): install a Curator CR → Operator creates Deployment + Service → CoreDNS servescurator→ Gateway's resolver flips it fromNotInstalledto Installed with no redeploy; uninstall flips it back. Full scoping and first bead-issue list:docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#5.
Completion criteria
Not applicable yet -- this PRD records the target shape and the discovery
decision. It does not authorize implementation. Before work begins: file
a beads epic, resolve the open questions above (at minimum #1-#3), and
get explicit go-ahead given the scale of this change relative to
AGENTS.md's "smallest workable change" default for this solo project.