docs: record the UI cutover and the archie-ui deployment story

- ui-service-boundary.md: the /api/captures|/mappings|/bindings row is
  resolved by the cutover; archie-ui composes the store contracts and
  mounts the captureintake receiver.
- event-capture-storage.md HTTP surface: the receiver mounts on the one
  process serving the dashboard; work intake stays with the daemon.
- config.example.toml: [web].listen is the archie-ui process's bind
  address; [capture] is projected by archie-ui.
- deployments: document running archie-ui alongside the other services
  and add its systemd unit; capabilities comments updated for the
  single-serving composition.
This commit is contained in:
sam committed 2026-09-10 01:03:40 +10:00
1 parent 27bc40332f
commit 27bdb53596
8 files changed
+90 -25

No files matched your search

+3 -2
View File
@@ -38,7 +38,7 @@ See `docs/architecture/organisation.md` for the target structure and
| `internal/store/` | Task store interface and SQLite implementation; RPC clients proxy it |
| `internal/events/` | In-process event bus: publish/subscribe for observability |
| `internal/infrastructure/` | Config loading, eventbus transport, model catalog |
| `internal/webui/` | SSE dashboard: live event stream, task status |
| `internal/webui/` | Shared dashboard HTTP layer served by the archie-ui process |
| `internal/gateway/` (18.7k LOC) | Persistent-connection layer between archie and its users (Telegram, web UI, etc.); shared CommandRouter for dispatch |
| `internal/tools/` (20.9k LOC) | Central tool subsystem: built-in tool implementations, approval, execution contract |
| `internal/memory/` (7k LOC) | Pluggable memory provider architecture |
@@ -247,7 +247,8 @@ Daemon-level TOML (`~/.config/archie/config.toml`):
- `[nats]` -- embedded or external broker deployment
- `[containers]` -- managed `archie-agent` image, limits, storage, and network
- `[budgets]` -- max steps, max tokens, wall clock, gate max failures
- `[web]` -- dashboard listen address
- `[web]` -- dashboard listen address, bound by the standalone archie-ui
process (the daemon runs no dashboard listener after the UI cutover)
- `[notify]` -- webhook URL for notifications
Secrets (forge token, provider API keys, channel tokens) are not embedded in
+12 -2
View File
@@ -196,10 +196,14 @@ class = "ollama"
listen = "127.0.0.1:8485"
# Web dashboard and API: task board, activity stream, chat, config,
# logs, memory, SSE events. Served as an embedded SPA with a full REST
# memory, SSE events. Served as an embedded SPA with a full REST
# and streaming API. Auth is token-based for non-loopback addresses;
# loopback binds (127.0.0.1, ::1, localhost) skip auth automatically.
# Set to "off" (or leave empty) to disable.
#
# From the UI cutover (archie-core-8cda.5.4) the dashboard is served by the
# standalone archie-ui process, not by archied: this listen address is what
# archie-ui binds, and archied runs no dashboard listener at all. Run
# `archie-ui -config <same config.toml>` alongside the other services.
[web]
listen = "127.0.0.1:8484"
# Trust X-Forwarded-Proto and X-Forwarded-Host headers when validating Origin
@@ -313,6 +317,12 @@ gate_max_failures = 5
# fan-out/replay machinery, and SQLite is available in every deployment
# shape unconditionally. All fields default when the section is absent;
# capture is on by default.
#
# From the UI cutover (archie-core-8cda.5.4) the receiver is mounted by the
# archie-ui process, which projects these same values from this file; the
# daemon's binding-dispatch loop consumes captures from the shared State
# Store. Leave this section here even if you do not edit it: both processes
# read it.
# [capture]
# retention = "168h" # 7 days; prune-on-write deletes anything older
# max_events = 5000 # row cap, pruned on every insert regardless of age
+20
View File
@@ -35,6 +35,7 @@ Edit API keys in `~/.config/archie/env` or directly in `config.toml`, then launc
```bash
archie-gateway -config ~/.config/archie/config.toml -listen 127.0.0.1:8585 &
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090 &
archie-ui -config ~/.config/archie/config.toml &
archied -config ~/.config/archie/config.toml
# or via systemd:
systemctl --user start archied
@@ -55,6 +56,25 @@ Docker bridge gateway address plus a matching bearer token (`target_token` /
`--token` / `STATE_STORE_TOKEN`), because a container cannot reach the host's
loopback.
## Running the dashboard
The dashboard is served by the standalone UI Service (`archie-ui`), not by
`archied` (UI cutover, `archie-core-8cda.5.4`; `docs/prds/ui-service-boundary.md`).
It reads the same `config.toml`, dials the Gateway and State Store targets
already configured there, and binds `[web].listen` (`127.0.0.1:8484` by
default). Start it after the Gateway and the State Store:
```bash
archie-ui -config ~/.config/archie/config.toml
```
A non-loopback `[web].listen` requires a dashboard token (`-token`, or
`-token-file` to mint and persist one); a loopback bind needs none.
`archied` runs no dashboard listener at all, so webhook capture
(`POST /webhooks/capture/{source}`) is received by archie-ui and the
binding-dispatch loop in `archied` consumes what arrives from the shared
State Store.
```bash
# loopback (host-only agent)
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090
+32 -6
View File
@@ -71,7 +71,33 @@ WantedBy=default.target
---
## 2. Enabling User Linger (`loginctl`)
## 2. UI Service Unit (`~/.config/systemd/user/archie-ui.service`)
The dashboard is served by the standalone UI Service, not by `archied`
(UI cutover, `archie-core-8cda.5.4`). It reads the same `config.toml`, dials
the Gateway and State Store targets already in it, and binds `[web].listen`.
A non-loopback bind requires a dashboard token (`-token`, or `-token-file` to
mint and persist one);
```ini
[Unit]
Description=Archie UI Service
After=network.target
[Service]
Type=simple
ExecStart=%h/.local/bin/archie-ui -config %h/.config/archie/config.toml
EnvironmentFile=-%h/.config/archie/env
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=default.target
```
---
## 3. Enabling User Linger (`loginctl`)
By default, systemd terminates user services when you log out of SSH. Enabling **linger** allows your `archied` service to run continuously 24/7 across reboots and logouts:
@@ -87,7 +113,7 @@ loginctl show-user "$USER" | grep Linger
---
## 3. Service Commands
## 4. Service Commands
Reload systemd daemon files:
```bash
@@ -96,7 +122,7 @@ systemctl --user daemon-reload
Enable and start the service immediately:
```bash
systemctl --user enable --now archie-gateway archied
systemctl --user enable --now archie-gateway archie-ui archied
```
Check service status:
@@ -117,7 +143,7 @@ systemctl --user stop archied
---
## 4. Default: Native Daemon, Embedded NATS, Managed Containers
## 5. Default: Native Daemon, Embedded NATS, Managed Containers
Embedded NATS is the default. The systemd service runs `archied` natively, so
interactive chat keeps the host access the operator configured, while every
@@ -158,7 +184,7 @@ fall back to a host model loop.
---
## 5. Pinning the archie-agent Image
## 6. Pinning the archie-agent Image
`ghcr.io/samcharles93/archie-agent:latest` is a moving target: every push to
`main` that touches the runtime's package closure re-publishes it (see
@@ -197,7 +223,7 @@ check. A custom image reference is therefore supported directly in
`config.toml`; `ARCHIE_AGENT_IMAGE` is only an override for deployments that
cannot make that configuration file available to the update command.
## 5. Optional: External Compose NATS
## 7. Optional: External Compose NATS
External NATS changes only broker deployment. It does not change the worker
executor. Start the optional service and configure the pinned Compose gateway:
+7
View File
@@ -113,6 +113,13 @@ dashboard in a given deployment; no new port/host config surface is added,
and no new claim about public reachability is made beyond what already
exists for the dashboard.
Amended 2026-09-10 by the UI cutover (`archie-core-8cda.5.4`): the one
process serving the dashboard is now the standalone archie-ui service, so
the receiver mounts there, composed from the UI process's own State Store
client. The binding-dispatch loop that turns captures into tasks stays in
the daemon, consuming the same store, so the HTTP front door moved without
moving work intake.
`GET` listing/inspection endpoints (`t2db.2`) stay behind `requireToken` like
every other `/api/*` route -- captured payloads are visible only to an
authenticated operator, per the security decision's point 5 visibility rule.
+1 -1
View File
@@ -66,7 +66,7 @@ cutover.
| `/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 |
| `/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/captures`, `/api/mappings`, `/api/bindings` | State Store contracts, with webhook verification owned by Work Intake/Messaging | RESOLVED (cutover, `archie-core-8cda.5.4`): the UI process composes CaptureStore/MappingStore/BindingStore and mounts the `captureintake.Receiver` from its own State Store client; the daemon's binding-dispatch loop keeps consuming captures from the same store |
| `/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 |
+8 -8
View File
@@ -5,18 +5,18 @@ import "net/http"
// handleCapabilities reports which dashboard sections this process can
// actually serve.
//
// The dashboard is served by two different compositions: the daemon, which
// holds every runtime handle, and the UI process, which holds two remote
// contracts and nothing else. Sections whose capability lives only in the
// daemon still answer -- with an empty list, a "disabled" marker, or a 501 --
// and the page cannot tell that apart from a deployment where nothing has
// happened yet. Rather than have every page guess, the server says which
// sections it can back, and the browser hides the rest.
// The dashboard is served by the extracted UI process, which holds two remote
// contracts (Gateway ChatContract and the State Store) and nothing else.
// Sections whose capability lives only in the daemon still answer -- with an
// empty list, a "disabled" marker, or a 501 -- and the page cannot tell that
// apart from a deployment where nothing has happened yet. Rather than have
// every page guess, the server says which sections it can back, and the
// browser hides the rest.
//
// A section is reported available when the handle behind it is wired, which
// is the same condition its handler already uses to decide between real data
// and its degraded answer. Sections backed by the task store are absent from
// this list: the store is mandatory in both compositions.
// this list: the store is mandatory.
func (s *Server) handleCapabilities(w http.ResponseWriter, _ *http.Request) {
writeJSON(w, map[string]any{
"sections": map[string]bool{
+7 -6
View File
@@ -1,11 +1,12 @@
// Which dashboard sections the serving process can actually back.
//
// The dashboard is served by two compositions: the daemon, which holds every
// runtime handle, and the extracted UI service, which holds two remote
// contracts. A section with nothing behind it still answers -- an empty list,
// a "disabled" marker, a 501 -- and the browser cannot tell that from a quiet
// deployment. GET /api/capabilities says which sections are backed here, and
// the nav drops the rest (archie-core-8cda.5.4).
// From the UI cutover the dashboard is served by one composition: the
// extracted UI service, which holds two remote contracts (Gateway ChatContract
// and the State Store) and no daemon runtime handles. A section with nothing
// behind it still answers -- an empty list, a "disabled" marker, a 501 -- and
// the browser cannot tell that from a quiet deployment. GET /api/capabilities
// says which sections are backed here, and the nav drops the rest
// (archie-core-8cda.5.4).
// hiddenRoutes returns the paths whose section the server reported it cannot
// serve. An unreported section stays visible: a page that says "unavailable"