docs(architecture): make the dashboard configuration page read-only for Phase 3

archie-core-ymut. The ratified boundary assumed one narrow admin contract
carrying both the configuration read and the write. It splits.

Read: webui.ConfigView is already a UI-owned, secret-free value projection
(ProviderView carries the API key's env var name and a Configured bool, never
a value; RepoView is metadata only) and is already the exact shape the browser
receives. The daemon publishes it, plus provenance, reload status and the
overridden-key list, as a snapshot the UI reads over two new State Store RPCs.
Nothing is designed, only moved.

Rejected a config admin service on archied. That would make the daemon a gRPC
server for the first time: grpc.NewServer appears only in RunGateway and
RunStateStore, which are the standalone binaries' entry points, not the
daemon's, so it costs a new listener, port, token and interceptor.

Write: PATCH /api/config, POST /api/config/reset and the repo-field route
answer 503 in the UI process, and the SPA hides the controls. This is a
deliberate feature reduction. The update policy is daemon-local
(installUpdateConfigHandler denies non-runtime-tunable keys, applies a dotted
overlay to a clone, validates the materialised config, writes overlay rows and
rebuilds provenance); contracting it verbatim would build a Configuration
Service inside a migration bead. Revisit with archie-core-1786637498420-327,
where it is a feature rather than migration residue.

Implementation is assigned to archie-core-8cda.5.4, the cutover that removes
the daemon's dashboard. Nothing is built here.
This commit is contained in:
sam committed 2026-09-09 03:00:56 +10:00
1 parent ffc64a2c5d
commit d6fc2b3f1e
2 files changed
+63 -5

No files matched your search

+51
View File
@@ -356,6 +356,57 @@ Revisit only if sub-second feed latency becomes a requirement, or if a second
consumer needs the same stream, at which point the fan-out belongs in the State
Store process behind a `SubscribeEvents` RPC and this record is superseded.
**Dashboard configuration page — DECIDED (2026-09-09, `archie-core-ymut`).**
The configuration page becomes read-only in the UI process for Phase 3. Reads
cross the boundary as a published snapshot; writes are descoped, not
contracted. This amends the ratified boundary, which assumed a single admin
contract carrying both.
**Reads.** `webui.ConfigView` is already the whole answer. It is a UI-owned,
secret-free value projection built in `handleConfig`: `ProviderView` carries
the API key's environment variable name and a `Configured` boolean, never a
value, and `RepoView` is repository metadata only. It is already the exact
shape the browser receives. So the daemon publishes that projection, plus
provenance, reload status and the overridden-key list, as a snapshot the UI
reads; nothing new has to be designed, only moved. Two State Store RPCs carry
it, a `PutConfigSnapshot` restricted to the administrative token and a
`GetConfigSnapshot` the UI calls. The daemon republishes on boot and after
each successful reload, which is precisely when the projection changes.
The State Store is the right holder because a published configuration snapshot
is shared state, it is already dialled by the UI, and it costs no new listener,
port, token or interceptor. The alternative, a config admin service on
`archied`, would make the daemon a gRPC server for the first time. Today it is
purely a client of Gateway and State Store; `grpc.NewServer` appears only in
`RunGateway` and `RunStateStore`, which are the standalone binaries' entry
points, not the daemon's.
**Writes.** `PATCH /api/config`, `POST /api/config/reset` and
`PATCH /api/config/repos/{owner}/{name}` answer 503 in the UI process, and the
SPA hides those controls rather than offering a button that fails. Editing is
`config.toml` plus reload, which is already the only path for every setting
outside the runtime-tunable allowlist.
This is a deliberate feature reduction and worth naming as one. The write path
is not hard because of the transport; it is hard because the policy is
daemon-local and stays that way: `installUpdateConfigHandler` denies
non-runtime-tunable keys, applies a dotted overlay to a clone of the published
config, validates the materialised result, writes overlay rows, and rebuilds
provenance. Contracting that means either moving the policy, which the
boundary forbids, or exposing it verbatim as remote procedure calls, which
builds a Configuration Service inside a migration bead. Neither is work this
phase should be doing to keep one page's buttons alive.
Revisit when dashboard configuration editing is picked up as a feature in its
own right (`archie-core-1786637498420-327`, still open). At that point it gets
an admin contract designed as a feature, and the Configuration Service this
document already anticipates is its natural owner. Until then the UI renders
configuration and does not write it, which is what the boundary always said
about ownership even when it assumed a wider contract.
Implementation belongs to `archie-core-8cda.5.4`, the cutover that removes the
daemon's own dashboard. Nothing here is built yet.
### 7. Shared mechanics
The following cross-domain mechanics require exact contracts before dependent
+12 -5
View File
@@ -67,7 +67,8 @@ cutover.
| `/events` | State Store `EventsSince`, polled by one UI-process pump feeding `Server.Broadcast` | RESOLVED (`archie-core-za9f`): see migration-decisions, "Dashboard live event delivery". No new RPC; replay cursor and drop-recovery are the existing `since` watermark in `sse.go` |
| `/api/logs`, `/api/logs/stream` | daemon diagnostic feed, host-local | unresolved: `logging.Feed` is in-process on the daemon host and has no contract |
| `/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/config` (read) | daemon-published `ConfigView` snapshot, read over the State Store contract | RESOLVED (`archie-core-ymut`): see migration-decisions, "Dashboard configuration page" |
| `/api/config` (write), `/api/config/reset`, `/api/config/repos/*` | none; descoped for Phase 3 | RESOLVED (`archie-core-ymut`): 503 in the UI process, SPA hides the controls, editing is config.toml plus reload |
| `/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 |
@@ -105,10 +106,16 @@ 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.
and audit behavior. The UI does not become the writer merely because it
renders the configuration page.
Amended 2026-09-09 by `archie-core-ymut`: this section previously assumed one
narrow admin contract carrying both the read and the write. It does not. The
read crosses as a daemon-published `ConfigView` snapshot over the State Store
contract, and the write is descoped for Phase 3 rather than contracted, on the
reasoning recorded in migration-decisions under "Dashboard configuration
page". A future dedicated Configuration Service is the natural owner of a
write contract, and designing one is that feature's work, not this migration's.
## Listen, authentication, and readiness