docs(architecture): ratify UI service boundary
This commit is contained in:
1 parent
80143e4869
commit
37225e032c
3 files changed
+256
-17
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user