docs(architecture): ratify UI service boundary

This commit is contained in:
sam committed 2026-09-07 18:29:42 +10:00
1 parent 80143e4869
commit 37225e032c
3 files changed
+256 -17

No files matched your search

+32
View File
@@ -106,6 +106,26 @@ The destination matrix MUST name the behaviour owner, target path, dependencies
to remove, state and contracts to preserve, migration prerequisites, and
deletion criteria.
**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**
The current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator
authentication, UI response projection, configuration reads and mutations,
task/control APIs, and direct adapters to State Store, channel, event/log,
memory, curator, workflow, forge, and Gateway runtime values. The target owner
is a standalone UI application process; `internal/webui` remains its HTTP
transport adapter, while Gateway, State Store, configuration, Work Intake,
Messaging, and other capability owners expose the contracts behind those
routes. The migration preserves retained route schemas, auth/CSRF behavior,
task/capture/mapping/binding/session continuity, SSE replay semantics, and
committed generated SPA assets. Prerequisites are the ratified UI boundary,
route-owner inventory, narrow remote adapters, configuration/auth/readiness
contracts, and process/conformance tests. Remove the shared live
`config.Holder`, direct event/log bus, daemon stopper, forge client, channel
manager, capability registries, composite store access, and in-process UI
listener only after the focused criteria in
[`docs/prds/ui-service-boundary.md`](../prds/ui-service-boundary.md) pass in
production composition. The old construction and listener are deleted in the
same cutover change; no second UI authority remains.
### 2. Session and Messaging migration
The existing session implementation is the migration baseline. The migration must
@@ -276,6 +296,18 @@ task container through scoped RPC services. The worker runs the workflow and
its worker-local ai-sdk loop; it does not receive forge credentials or direct
store access. See `docs/prds/embedded-nats.md`.
**UI Service boundary — RATIFIED (2026-09-07).** Phase 3 has a focused
authority record in [`docs/prds/ui-service-boundary.md`](../prds/ui-service-boundary.md).
The UI Service owns HTTP/SPA delivery, UI DTOs, browser authentication, and
its own endpoint/credential/readiness settings. It consumes Gateway and State
Store contracts and does not receive `config.Holder`, daemon pointers, SQL or
store implementations, workflow registries, forge/channel/model runtimes, or
resolved secrets. The current `internal/webui` implementation remains inside
`archied` until the ratified migration gates prove route parity, adapter
selection, failure/readiness behavior, and deletion of the shared-holder and
direct-access paths. The extraction cutover removes the in-process UI
listener in the same change; there is no dual-live UI authority.
### 7. Shared mechanics
The following cross-domain mechanics require exact contracts before dependent
+17 -17
View File
@@ -9,6 +9,11 @@
`/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`](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
@@ -30,7 +35,7 @@ boundaries.
| Service | Contract it owns | Existing code it replaces/wraps |
|---|---|---|
| UI Service | thin client only; talks to Gateway's contract | `internal/webui` (SPA hosting stays; API surface becomes a Gateway client, not a peer with direct access) |
| 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` |
@@ -80,23 +85,18 @@ either shape.
established that Archie's existing domain split already does what AWX's
service-decomposition post argues for -- boundaries exist. What doesn't
exist is deployability: `internal/webui` is not a passive frontend today.
Verified couplings that this decomposition must eliminate:
The original webui coupling inventory has been re-baselined against the current
checkout. Two earlier couplings are already removed; the remaining UI work is
recorded in [`ui-service-boundary.md`](ui-service-boundary.md).
- Telegram's task-action execution (pause/resume) currently routes through
`internal/webui`'s own HTTP handler in-process
(`chatTaskActorAdapter.ApplyChatTaskAction`,
`internal/app/archied/main.go:224-242`, dispatching into
`internal/webui/server.go:231`'s `handleTaskAction`). Under this PRD,
Messaging Service calls Gateway Service's contract directly -- no HTTP
detour through a UI process.
- `internal/webui/api_chat.go` calls `gateway.SessionStore`, `Router`, and
`TurnHistory` directly (lines 97, 142, 198, 256, 261) instead of through
a narrow interface. Under this PRD, UI Service only ever sees Gateway
Service's `ChatContract`.
- `bootstrap.go:1239` shares the daemon's live `config.Holder` with webui
rather than passing config. Under this PRD, each service owns its own
configuration surface; nothing shares a live in-process struct across a
service boundary because there is no longer a shared process.
- Telegram task actions now call Gateway's `ChatContract` directly through
`chatTaskActorAdapter`; the old Telegram-to-webui HTTP detour is historical.
- `internal/webui/api_chat.go` now holds `gateway.ChatContract`; direct
`SessionStore`, `Router`, and `TurnHistory` access is historical.
- The live `config.Holder` alias remains: `buildDaemon` assigns
`b.web.Cfg = b.d.Cfg`. UI extraction must remove that alias and also assign
owners/contracts for the State Store, channel manager, event/log feeds,
configuration mutations, webhook capture, and other current webui routes.
## Non-goals
+207
View File
@@ -0,0 +1,207 @@
# UI Service boundary and configuration ownership
**Status:** Ratified (rev. 1)
**Date:** 2026-09-07
**Beads issue:** `archie-core-8cda.5.1`
**Parent:** [`service-decomposition.md`](service-decomposition.md)
**Prerequisites:** Gateway contract extraction and State Store contract ratification
This document is the authority for Phase 3 UI Service implementation. It fixes
the process boundary, configuration ownership, client contracts, security
posture, readiness behavior, and migration evidence required by
`archie-core-8cda.5.2` and later UI extraction work.
## Decision
The UI Service owns the operator-facing HTTP surface and the compiled SPA. It
serves `ui/dist` and exposes UI-specific JSON DTOs for dashboard views and
actions. It does not own conversations, task state, workflow execution,
channel lifecycle, forge access, or the daemon's runtime configuration.
The UI Service consumes two typed remote capabilities:
- Gateway's `gateway.ChatContract` through the versioned Gateway gRPC
contract, for chat snapshots, messages, turns, streaming, persona changes,
cancellation, and Gateway task actions.
- State Store's narrow read/write contracts through the versioned State Store
gRPC contract, for task views, events, captures, mappings, bindings, and
configuration data explicitly projected for the dashboard.
The UI process may compose local adapters during the migration seam, but the
adapter implements the same wire-safe contract as the remote client. The
production extraction cutover removes the in-process adapter in the same
change; a dual-live UI authority is not permitted.
## Boundary and ownership
| Concern | UI Service owns | UI Service may consume | UI Service must not own or receive |
|---|---|---|---|
| HTTP and SPA | routes, auth middleware, UI DTOs, assets, HTTP lifecycle | contract results and health snapshots | domain entities or infrastructure handles |
| Chat | request validation and response projection | Gateway `ChatContract` | `gateway.Router`, `SessionStore`, turn runner, model/provider runtime |
| Task dashboard | query/action DTOs and HTTP status mapping | State Store narrow contracts and explicitly ratified task-action contract | `*store.Store`, SQL connections, workflow registry, daemon pointer |
| Configuration page | secret-free view and update request validation | a UI configuration contract owned by the configuration/application boundary | `config.Config`, `config.Holder`, secret registry, reload implementation |
| Readiness | UI process liveness and dependency readiness aggregation | bounded health results from Gateway and State Store | direct probing of private databases or providers |
Every value crossing the process boundary is a versioned DTO or scalar contract
value. `internal/webui` may retain temporary Go-side adapters while the
migration is in progress, but handlers must map Gateway/State Store values to
UI-owned response types at the HTTP edge. A constructor accepting a concrete
Gateway, State Store, daemon, or `config.Holder` is not an approved final
boundary.
The existing UI routes remain behaviorally compatible during extraction,
including task actions, SSE event delivery, config views, chat streaming,
capture intake, mappings, bindings, update reporting, and health endpoints.
Compatibility preserves status codes, authentication requirements, redaction,
pagination/limits, event ordering, and failure degradation unless a separately
ratified contract changes them.
The route families have these target owners. This is the required inventory for
the implementation children; a route without an owner is not eligible for
cutover.
| Route family | Target owner consumed by UI | Migration status |
|---|---|---|
| `/api/chat/*` | Gateway `ChatContract` and its versioned client | contract seam exists; DTO and stream parity remain |
| `/api/tasks/*`, `/api/workflows`, `/api/setup` | State Store read/action contracts plus an explicit execution/admin action contract | State Store adapter exists; UI-facing narrow surface remains |
| `/api/logs`, `/events` | State/event and log contracts with replay cursor and backpressure rules | local bus/feed only today; contract remains to define |
| `/api/captures`, `/api/mappings`, `/api/bindings` | State Store contracts, with webhook verification owned by Work Intake/Messaging | local adapter exists; remote UI surface remains to define |
| `/api/config` | daemon/config owner through a versioned admin contract | current app callbacks; shared holder must be removed |
| `/api/channels`, reload, curators, memory, skills, version/update | owning capability contract or an explicitly removed route | owner and failure semantics remain to define |
| `/`, `/healthz`, `/health`, `/health/detailed` | UI HTTP process; readiness consumes per-service health contracts | current HTTP behavior is the compatibility baseline |
## Configuration ownership
The UI Service owns only process-local settings:
- HTTP listen address and read/header/shutdown timeouts;
- UI asset source or build mode;
- UI authentication mode and token reference;
- Gateway endpoint and credential reference;
- State Store endpoint and credential reference;
- readiness endpoint and dependency timeout policy.
These settings are decoded into a UI-owned input DTO by the UI composition root.
The DTO contains endpoint references and secret references, never resolved
secret values or complete daemon configuration. The UI process resolves its
own credentials and builds its own clients. It does not read or mutate the
daemon's configuration file, runtime overlay, forge credentials, model catalog,
workflow routing, NATS settings, filesystem jail, or agent/container settings.
The dashboard configuration API is a separate capability. Its secret-free,
allowlisted field projections remain governed by
[`config-schema.md`](config-schema.md). During the transition the daemon may
continue to perform validate-persist-publish for those updates through a
narrow application contract. The UI process must never implement that policy
by holding or mutating a shared `config.Holder`.
The current daemon's `config.Holder` sharing is migration residue: `buildDaemon`
currently assigns `b.web.Cfg = b.d.Cfg`. It is removed only when the UI has a
configuration read/update contract and tests prove that the daemon and UI no
longer share a mutable holder.
For Phase 3, configuration ownership is split deliberately. The UI process
owns its listener, browser-auth, asset, dependency-target, and readiness
settings. The daemon/application configuration owner remains authoritative for
the dashboard's `/api/config` read, validation, persistence, overlay, reload,
and audit behavior; the UI calls that owner through a narrow admin contract.
The UI does not become the writer merely because it renders the configuration
page. A future dedicated Configuration Service may replace that owner through
the same contract without changing the UI boundary.
## Listen, authentication, and readiness
The extracted UI follows the current web UI security posture:
- loopback listeners may omit a dashboard token;
- non-loopback listeners require a non-empty token and fail closed when it is
absent;
- `/healthz` and `/health` are unauthenticated liveness probes;
- `/health/detailed` is authenticated and reports dependency readiness;
- capture webhooks retain their separately ratified source authentication and
rate-limit rules; they are not admitted by the dashboard token;
- Gateway and State Store credentials are service-to-service credentials, never
browser-visible dashboard tokens.
The UI is ready only when its HTTP server is serving and each mandatory remote
contract has passed its bounded readiness check. Each dependency must expose a
versioned health result or health endpoint that the UI can consume; the UI must
not inspect another service's concrete manager, registry, or database. Optional
dashboard sections may remain degraded with the current explicit
`503`/unavailable behavior. A successful liveness response must never imply
dependency readiness.
## Migration sequence and evidence
The implementation must complete these gates in order:
1. Define the UI input DTO, Gateway client surface, State Store client surface,
and UI response DTOs. Add compile-time contract assertions and mapping
tests. No handler may depend on a concrete remote implementation.
2. Make the current in-process web UI consume the same narrow adapters and
preserve the current route, auth, redaction, stream, SSE, and degradation
behavior. Add a composition test proving the selected adapter is the one
used by production wiring.
3. Remove direct `internal/gateway` session/router/runtime access from web UI
handlers. Remove direct `internal/store` implementation access, SQL access,
daemon pointers, and broad runtime callback bundles from the UI constructor.
4. Replace the shared `config.Holder` with the UI-owned configuration DTO and
narrow configuration application contract. Prove reload/update atomicity
remains owned by the configuration/application boundary.
5. Add the standalone UI process and deployment wiring. It must obtain Gateway
and State Store endpoints from its own configuration, authenticate each
client independently, start liveness/readiness endpoints, and shut down
clients and HTTP listeners in bounded order.
6. Run dual-adapter contract tests and an HTTP parity suite covering every
retained route. Test remote failures, missing credentials, malformed DTOs,
stream cancellation, stale State Store data, and readiness degradation.
7. Cut over the supported composition to the UI process. The old in-process
`webui.Run` path is deleted in the same change; no fallback or second HTTP
authority remains.
The deletion gate is objective: `go list -deps` from the UI process shows no
daemon, SQL/store implementation, workflow, forge, channel, model, or secret
runtime package; production composition contains one UI HTTP listener; and
architecture tests reject `config.Holder`, concrete `*store.Store`, concrete
Gateway runtime types, and direct SQLite imports in the UI service.
Rollback is a deployment composition change that points the operator at the
last validated UI binary and restores the previous endpoint configuration. It
must not restore a second writer or reintroduce shared-holder mutation. UI
state is either remote contract state or existing durable state owned by its
current service; no UI-specific database migration is introduced by this
boundary decision.
## Current evidence and known delta
Current code proves the following migration inputs:
- `internal/app/archied/bootstrap.go:setupObservability` constructs
`webui.Server` and wires store, channels, events, logs, and config-related
callbacks.
- `internal/app/archied/bootstrap.go:buildDaemon` replaces the initial holder
with `b.d.Cfg`, explicitly sharing the daemon's live configuration.
- `internal/webui/api_chat.go` calls the Gateway contract but still imports
Gateway-owned request/value types; handlers must finish the DTO projection.
- `internal/webui/server.go:Handler` owns the route set, SPA fallback, health
split, capture bypass, and token wrapper.
- `internal/app/archied/state_store.go:RunStateStore` owns the task SQLite
file and serves the State Store gRPC contract; the UI must use that contract
rather than opening the file.
- `internal/app/archied/gateway.go:RunGateway` serves Gateway gRPC and owns
Gateway session persistence; the UI must use `ChatContract` rather than
Gateway internals.
The current code therefore satisfies the upstream prerequisites but does not
yet satisfy this boundary. This document is the ratified target; the
implementation child must prove each migration gate before claiming Phase 3
complete.
## Non-goals and open work
This ratification does not define a new domain model, move the dashboard's
allowlisted configuration schema, redesign Gateway or State Store RPCs, choose
Kubernetes versus local discovery, or authorize unrelated package migration.
Those decisions remain in their existing authority documents. Any new UI
capability that requires a wider Gateway or State Store surface must amend that
service's contract before implementation.