Page Structure & Information Architecture¶

Overview¶

This document defines the information architecture for the v0.5.0 web dashboard rebuild. It was validated against the backend API surface (23 controllers, 9 WebSocket channels) and the design decisions from #762 (Mission Control direction, 4 differentiators) and #765 (Warm Ops identity).

Guiding principle: every page maps to a real backend domain with live data. No user-facing placeholder pages or "Coming Soon" stubs. ProjectController and ArtifactController have full persistence backends (v0.5.3, #612) and dashboard pages (v0.5.4, #946).

Page List¶

Primary Navigation¶

High-frequency destinations, always visible in the sidebar.

Dashboard (/)¶

Org overview: department health indicators (green/amber/red), recent activity widget, budget snapshot with sparkline, active task summary, agent status counts, approval badge count. The central "is the company healthy?" view.

API endpoints: GET /analytics/overview, GET /analytics/forecast, GET /budget/config, GET /departments, GET /departments/{name}/health, GET /activities WS channels: tasks, agents, budget, system, approvals (all -- aggregated into health indicators and activity feed)

Org Chart (/org)¶

Living org visualization with real-time agent status. Two view modes toggled via toolbar:

• Hierarchy view (default): Dagre-based hierarchical layout with CEO, departments, teams, agents with status dots and health overlays. Supports drag-drop agent reassignment between departments (optimistic update with rollback on API failure, ARIA live announcements, drop zone highlight with accent border).
• Communication view: Force-directed layout (d3-force) showing inter-agent communication patterns. Edge thickness encodes message volume, animated dashes encode frequency. Data sourced from GET /messages with client-side aggregation. Smooth 400ms animated transition between views.

Click agent nodes to open Agent Detail panel.

"Edit Organization" button enters form-based edit mode (/org/edit) with sub-tabs: General (name, autonomy level, monthly budget, communication pattern), Agents (card grid with add/edit/delete), Departments (card grid with CRUD and read-only teams summary; nested teams/reporting/policies editing is deferred). This is the former Company page merged into the Org Chart -- same data domain, one destination.

API endpoints: GET /company, GET /company/departments, GET /departments, GET /departments/{name}, GET /departments/{name}/health, GET /agents, GET /agents/{name}, GET /messages (communication view), PATCH /agents/{name} (drag-drop reassignment in hierarchy view). Edit mode adds: PATCH /company, POST /departments, PATCH /departments/{name}, DELETE /departments/{name}, POST /company/reorder-departments, POST /agents, DELETE /agents/{name}, POST /departments/{name}/reorder-agents (stub -- backend not yet implemented). WS channels: agents (status changes, hired/fired). Communication view uses REST polling for message data (not WS).

Task Board (/tasks)¶

Kanban view (default) and list view toggle. Filter by status, assignee, department. Task cards show title, assignee, status, priority. Click opens task detail with full context, state transition buttons, and "Coordinate" action (triggers multi-agent coordination via /tasks/{id}/coordinate).

Project filter dropdown available. Dedicated Projects page added in v0.5.4 (#946).

API endpoints: GET /tasks, GET /tasks/{id}, POST /tasks, PATCH /tasks/{id}, POST /tasks/{id}/transition, POST /tasks/{id}/cancel, DELETE /tasks/{id}, POST /tasks/{id}/coordinate WS channels: tasks

Budget (/budget)¶

P&L management dashboard -- not a billing tab. Current period spend vs budget, per-agent cost breakdown, per-department rollups, trend lines, cost anomaly highlights. Forecast sub-view (/budget/forecast) shows projected spend trajectories from the analytics engine.

API endpoints: GET /budget/config, GET /budget/records, GET /budget/agents/{id}, GET /analytics/overview, GET /analytics/trends, GET /analytics/forecast WS channels: budget

Approvals (/approvals)¶

Pending decisions queue -- agents are blocked waiting for human action, so this is the highest-urgency page. Risk-level grouping with collapsible sections, urgency countdown indicators, batch select with approve/reject actions, detail drawer with approval timeline and metadata, filter bar with URL-synced state. Sidebar badge shows live pending count.

API endpoints: GET /approvals, GET /approvals/{id}, POST /approvals/{id}/approve, POST /approvals/{id}/reject WS channels: approvals

Secondary Navigation¶

Lower-frequency destinations in a collapsible "Workspace" section.

Agents (/agents)¶

Agent profiles as card grid. Each card shows name, role, department, status dot, hire date. Filtering by department, level, status. Search by name/role. Sort by name, department, level, status, hire date. Click navigates to the Agent Detail page at /agents/{agentName}.

Agent Detail page (/agents/{agentName}) -- single scrollable page with these sections:

• Identity header: Large avatar, name, role, department badge, level badge, status with pulse, autonomy level badge, hire date
• Prose insights: 1-3 generated narrative sentences from performance data (e.g. "Success rate of 94% across 127 completed tasks")
• Performance metrics: 2x2 grid of MetricCards (tasks completed, avg completion time, success rate, cost per task) with sparklines
• Tool badges: Horizontal flex-wrap of permitted tools
• Career timeline: Vertical timeline with colored dots (hired=green, promoted=blue, demoted=yellow, fired=red)
• Task history: Gantt-style horizontal bars sorted by time, type-colored, pulse on in-progress tasks, duration labels
• Activity log: Paginated chronological event list with type icons, descriptions, timestamps

Deferred to future iteration: Collaboration score/calibration endpoints, autonomy editing, spending breakdown, and tabbed layout (Access tab).

API endpoints: GET /agents, GET /agents/{name}, GET /agents/{name}/performance, GET /agents/{name}/activity, GET /agents/{name}/history WS channels: agents, tasks (detail page)

Projects (/projects)¶

Project list with card grid, search, and status filter. "Create Project" button opens a slide-in drawer with name, description, team (tag input), lead, deadline, and budget fields. Each card shows status badge, description, task count, budget, team size, and deadline.

Detail page (/projects/{projectId}) shows project header with status badge and key metrics, team section with avatar grid and lead badge, and a linked task list with status indicators.

Features:

• Card grid: responsive 3/2/1 column layout with hover effects, stagger animation
• Search: client-side filtering by name, description, and ID
• Status filter: dropdown filtering by project status (planning, active, on_hold, completed, cancelled)
• Create drawer: 6-field form with validation, optimistic state update
• Team section: avatar grid with links to agent detail pages, lead badge
• Task list: linked tasks with status indicators and assignee display

API endpoints: GET /projects, GET /projects/{id}, POST /projects WS channels: projects, tasks

Artifacts (/artifacts)¶

Artifact list with card grid, search, and filters for type, content type, agent, task, and project. Each card shows path, type badge, content type badge, file size, creation time, and creator.

Detail page (/artifacts/{artifactId}) shows metadata grid (type, size, content type, path, task, creator, project), inline content preview (text via CodeMirror with syntax highlighting, images as blob URLs), download button, and delete with confirmation dialog.

Features:

• Card grid: responsive 3/2/1 column layout with hover effects, stagger animation
• Search: client-side filtering by path, description, and ID
• Type filter: dropdown for artifact type (code, tests, documentation)
• Content type filter: dropdown for MIME type prefix (text, image, JSON, PDF, application)
• Agent/task/project filters: text inputs for filtering by creator, task ID, and project ID
• Content preview: text content in CodeMirror (JSON/YAML syntax highlighting), image content as inline preview, other types show "Preview not available" with download action
• File size display: human-readable size on cards and detail page, "No content" for 0 bytes
• Download: blob download with filename derived from artifact path
• Delete: confirmation dialog, toast notification, redirect to list

API endpoints: GET /artifacts, GET /artifacts/{id}, POST /artifacts, DELETE /artifacts/{id}, GET /artifacts/{id}/content, PUT /artifacts/{id}/content WS channels: artifacts

Messages (/messages)¶

Channel-filtered message feed for inspecting agent-to-agent communications. Two-column layout: channel list sidebar on the left, main message feed on the right. This is an investigative tool -- users examine delegation chains, audit coordination, debug inter-agent communication. Not a chat interface.

Features:

• Channel sidebar: grouped by type (topic/direct/broadcast), unread badge per channel, active channel highlight
• Message feed: sender avatar + name, message type badge, priority indicator (high/urgent), relative timestamps
• Timestamp grouping: messages grouped by date with "Today"/"Yesterday"/date dividers
• Threading: messages with the same task_id grouped visually with expand/collapse
• Client-side filtering: type, priority, and text search with URL-synced filter pills
• Detail drawer: right-side panel showing full message metadata (channel, sender, task/project links, token usage, cost, extra key-value pairs, attachments)
• Real-time: WebSocket-driven new message arrival with auto-scroll-to-bottom (when user is near bottom)
• Pagination: "Load earlier messages" button for fetching older messages

URL params: ?channel={name}, ?type={messageType}, ?priority={level}, ?search={query}, ?message={id} (detail drawer). All filter params are optional and combinable independently -- channel is not required for type/priority/search filters.

API endpoints: GET /messages, GET /messages/channels WS channels: messages

Meetings (/meetings)¶

Meeting history list with status/type filters. Click opens meeting detail (/meetings/{id}) with transcript and outcomes. "Trigger Meeting" action creates event-based meetings.

API endpoints: GET /meetings, GET /meetings/{id}, POST /meetings/trigger WS channels: meetings

Providers (/providers)¶

LLM provider management. CRUD cards for configured providers with health status display (up/degraded/down/unknown) and 24-hour health metrics (average response time, error rate percentage, call count, total tokens, cost). Connection test button. Preset-based creation flow with subscription auth support requiring ToS acceptance for applicable providers. Model auto-discovery with capability badges (tools, vision, streaming) per model. Provider list supports filtering and sorting by health status, name, and model count. Provider detail/edit at /providers/{name}.

No WebSocket subscription -- provider changes are low-frequency admin operations. TanStack Query polling is sufficient.

API endpoints: GET /providers, GET /providers/{name}, GET /providers/{name}/models, GET /providers/{name}/health, POST /providers, PUT /providers/{name}, DELETE /providers/{name}, POST /providers/{name}/test, GET /providers/presets, POST /providers/from-preset, POST /providers/{name}/discover-models, POST /providers/probe-preset, GET /providers/discovery-policy, POST /providers/discovery-policy/entries, POST /providers/discovery-policy/remove-entry

Workflows (/workflows)¶

Workflow definition list with card grid, search, and type filter. "Create Workflow" button opens a creation flow. Each card shows name, description, node count, edge count, creation time, and last-modified time. Actions per card: duplicate, delete (with confirmation dialog). Click navigates to the Workflow Editor at /workflows/editor?id={workflowId}.

API endpoints: GET /workflows, POST /workflows, DELETE /workflows/{id} WS channels: (none)

Workflow Editor (/workflows/editor)¶

Visual workflow designer -- a DAG-based editor for creating and editing workflow definitions that orchestrate multi-step agent pipelines. Operators build workflows by placing nodes on a canvas, connecting them with edges, and configuring each node's properties via a side drawer.

Key features:

• 7 node types: start, end, task, agent_assignment, conditional, parallel_split, parallel_join
• 4 edge types: sequential, conditional_true, conditional_false, parallel_branch
• Undo/redo: full history stack for node/edge additions, deletions, moves, and config changes
• YAML preview: live read-only YAML export of the current workflow graph
• Bidirectional YAML editing: toggle between visual and YAML editor modes; parse YAML back into the visual graph with inline error/warning display and position preservation
• Validation: client-side structural validation with inline error display
• Minimap: pannable/zoomable overview of the full graph for navigation in large workflows
• Copy/paste: clipboard operations for selected node groups with ID remapping and internal edge preservation
• Condition builder: structured expression editor (Builder mode with field/operator/value rows and AND/OR/NOT logical operators, Advanced mode with free-text) for conditional nodes
• Workflow selector: switch between saved workflow definitions from the editor toolbar
• Multi-workflow support: "Save as New" duplicate action, quick-switch between workflows

No WebSocket subscription -- workflow definitions are persisted via REST and do not require real-time collaboration.

API endpoints: GET /workflows, POST /workflows, GET /workflows/{id}, PATCH /workflows/{id}, DELETE /workflows/{id}, POST /workflows/{id}/validate, POST /workflows/{id}/export WS channels: (none)

Settings (/settings)¶

Configuration for 7 namespaces: api, memory, budget, security, coordination, observability, backup. Navigation uses a horizontal namespace tab bar across the top of the settings page, with each namespace as a clickable tab. Within each namespace, settings are displayed in a single-column layout with sub-group headings, basic/advanced mode, GUI/Code edit toggle (JSON/YAML within Code mode). Each namespace is URL-addressable (/settings/{namespace}) for deep linking from other pages (e.g. Dashboard budget warning links to /settings/budget).

The Code edit mode uses a split-pane diff editor view: the left pane shows the current persisted configuration (read-only), and the right pane is an editable CodeMirror editor for composing changes. This allows operators to see exactly what will change before saving.

Enabling advanced mode for the first time shows a confirmation dialog warning about misconfiguration risk. The warning is deduplicated per session via sessionStorage. Advanced mode preference persists in localStorage.

Dependency indicators are driven by a frontend-maintained SETTING_DEPENDENCIES map in web/src/utils/constants.ts (not by backend schema). When a controller setting is disabled, its dependent settings display in a muted state.

The observability namespace includes a dedicated Sinks sub-page (/settings/observability/sinks) for managing log sink configuration. The sinks page displays all active sinks (console and file) as cards showing identifier, log level, format, rotation policy, and routing prefixes. Operators can edit sink overrides and define custom sinks with a test-before-save workflow.

The coordination namespace includes a dedicated Ceremony Policy sub-page (/settings/coordination/ceremony-policy) for managing ceremony scheduling configuration. The page displays strategy selection (8 strategy types with descriptions and velocity unit indicator), velocity-calculator selection (paired to strategy via defaults), strategy-specific config panels, auto-transition toggle and threshold, department overrides with inherit/override toggles, per-ceremony overrides, and a strategy change warning banner. A resolved-policy view (populated from GET /ceremony-policy/resolved) annotates each field with a PolicySourceBadge showing the origin level (project, department, or default). Department overrides are read and written through GET /departments/{name}/ceremony-policy and PUT /departments/{name}/ceremony-policy, which store data in the dept_ceremony_policies JSON setting and resolve against the project-level policy.

The backup namespace will include backup management CRUD (trigger, list, restore, delete) in a future iteration, consolidating the BackupController under the Settings page. The current implementation covers backup configuration settings only (schedule, retention, path).

System-managed settings (e.g. api/setup_complete) are hidden from the GUI. Environment-sourced settings display as read-only.

API endpoints: GET /settings/_schema, GET /settings/_schema/{ns}, GET /settings, GET /settings/{ns}, GET /settings/{ns}/{key}, PUT /settings/{ns}/{key}, DELETE /settings/{ns}/{key}, GET /settings/observability/sinks, POST /settings/observability/sinks/_test, GET /ceremony-policy, GET /ceremony-policy/resolved?department=, GET /ceremony-policy/active, GET /departments/{name}/ceremony-policy, PUT /departments/{name}/ceremony-policy, DELETE /departments/{name}/ceremony-policy, POST /admin/backups, GET /admin/backups, GET /admin/backups/{id}, DELETE /admin/backups/{id}, POST /admin/backups/restore WS channels: system (restart-required notifications)

Documentation (/docs/)¶

Served as static MkDocs HTML by nginx -- not a React page. The /docs/ nginx location block serves pre-built documentation directly, bypassing the SPA's try_files fallback. The sidebar "Docs" link renders a plain <a href> (full-page navigation) instead of a React Router <NavLink>. MkDocs Material's own search, navigation, and dark mode function independently of the React app. Theme colors are customized via docs/overrides/extra.css to match the dashboard design system.

API endpoints: (none -- static HTML served by nginx) WS channels: (none)

Standalone Pages¶

Not in sidebar navigation.

Login (/login)¶

Full-page authentication. JWT-based. On success, redirects to / (Dashboard) or /setup if setup is not complete (based on GET /setup/status).

API endpoints: POST /auth/setup, POST /auth/login, GET /setup/status, GET /auth/sessions, DELETE /auth/sessions/{session_id}, POST /auth/logout

Setup Wizard (/setup)¶

Multi-step first-run flow. After account creation (conditional), a mode selection gate asks the user to choose Guided Setup (recommended, full wizard) or Quick Setup (minimal: company name + provider, configure rest later in Settings). Guided mode steps: account (conditional), mode selection, template selection, company creation, provider setup, agent configuration, theme customization, and completion. Quick mode steps: account (conditional), mode selection, company creation, provider setup, and completion. Providers are configured before agents so model assignment is available. Each step is URL-addressable (/setup/{step}). The mode selection step is hidden from the progress bar. Redirects to / if setup is already complete.

API endpoints: GET /setup/status, GET /setup/templates, POST /setup/company, POST /setup/agent, GET /setup/agents, PUT /setup/agents/{agent_index}/name, PUT /setup/agents/{agent_index}/model, PUT /setup/agents/{agent_index}/personality, POST /setup/agents/{agent_index}/randomize-name, GET /setup/personality-presets, GET /setup/name-locales/available, GET /setup/name-locales, PUT /setup/name-locales, POST /setup/complete

Overlays¶

Not pages -- triggered by user interaction, rendered over current page.

Command Palette¶

Trigger: Cmd+K (macOS) / Ctrl+K (Windows/Linux) Global search overlay: navigate to any page, search agents by name, search tasks, jump to settings namespaces. Built with cmdk library.

Notifications Panel¶

Trigger: Bell icon in sidebar bottom + unread badge Slide-in drawer aggregating system notifications: budget alerts, approval arrivals, agent status changes, system errors. Sources from WS system, approvals, and budget channels.

Agent Detail Page¶

Trigger: Click agent in Agents list, Org Chart node, or any agent name link Navigates to a dedicated full page at /agents/{agentName}. Single scrollable page with sections: Identity header, Prose insights, Performance metrics, Tool badges, Career timeline, Task history, Activity log. See the Agents section above for the full layout description.

Navigation Hierarchy¶

SIDEBAR (220px expanded / 56px icon rail)
|
+-- [Logo / Brand mark]
|
+-- PRIMARY
|   +-- Dashboard          [LayoutDashboard]     /
|   +-- Org Chart          [GitBranch]           /org
|   +-- Task Board         [KanbanSquare]        /tasks
|   +-- Budget             [DollarSign]          /budget  [amber dot when >85% spent]
|   +-- Approvals          [ShieldCheck]         /approvals  [badge: pending count]
|
+-- WORKSPACE (collapsible label)
|   +-- Agents             [Users]               /agents
|   +-- Projects           [FolderKanban]        /projects
|   +-- Workflows          [Workflow]            /workflows
|   +-- Artifacts          [Package]             /artifacts
|   +-- Messages           [MessageSquare]       /messages  [badge: unread count]
|   +-- Meetings           [Video]               /meetings
|   +-- Providers          [Cpu]                 /providers
|   +-- Docs               [BookOpen]            /docs/  (external -- static HTML, not SPA)
|   +-- Settings           [Settings]            /settings
|
+-- BOTTOM
    +-- [Collapse toggle]
    +-- [Notifications bell + badge]
    +-- [Cmd+K hint]
    +-- [Connection status dot from /health]
    +-- [User avatar / role badge / logout]

Icon source: Lucide React (already a project dependency).

Visual separators: Thin border lines between Primary, Workspace, and Bottom sections. No section headers for Primary -- items speak for themselves. "Workspace" label for secondary section, hidden when sidebar is collapsed to icon rail.

Badge behaviors:

• Approvals: Live count of pending approvals from WS approvals channel. Red badge. Disappears at zero.
• Messages: Unread message count from WS messages channel. Muted badge. Disappears at zero.
• Budget: Amber dot (no number) when budget exceeds 85% threshold. Source: WS budget channel alerts.
• Notifications bell: Aggregate unread count from system + approvals + budget alerts. Disappears at zero.

URL Routing Map¶

Application Routes¶

Route Guards¶

WebSocket Channel Subscription Map¶

Single WebSocket connection per session, established after login. Each page subscribes only to the channels it needs (see table below). Events are dispatched client-side to Zustand stores based on channel.

Global subscriptions (active regardless of current page):

• system: Connection status, shutdown notices
• approvals: Badge count for sidebar
• budget: Threshold alert for sidebar indicator
• messages: Unread count for sidebar badge

Responsive Scope¶

Desktop-first with minimal tablet support. No mobile layout for v0.5.0.

At tablet (768-1023px), the sidebar hamburger trigger is rendered in the StatusBar (top bar), not in the sidebar itself (which is hidden at that breakpoint). The overlay sidebar uses the shared Drawer component (role="dialog", aria-modal="true") with a blurred semi-transparent backdrop and auto-closes on navigation.

The density system (Dense/Balanced/Medium/Sparse from Brand & UX) provides additional user control over information density at any breakpoint.

Resolved Questions¶

Activity feed: Dashboard widget (not global drawer)¶

The activity feed is a Dashboard widget, not a persistent global element. Rationale:

• A persistent drawer competes with page content for attention (violates principle #3: "navigation recedes, content shines")
• The Dashboard is the natural home for activity summaries -- users who want more detail click through to the relevant page (principle #5: progressive disclosure)
• Linear, Vercel, and Grafana all use dashboard widgets for activity, not persistent drawers
• The Dashboard already subscribes to all WS channels for its health indicators -- the activity widget is a natural aggregation

Messages: Own page (not drawer)¶

Messages have a dedicated API (/messages + channel filtering) and WebSocket channel -- this is a first-class domain. Agent-to-agent communications require investigation (delegation chains, coordination audits), which needs filters, scrolling, and context that a drawer cannot provide. The channel filtering model maps naturally to a page with a channel sidebar and message feed.

Org Chart + Company: Merged with mode separation¶

Both deal with the same data domain (departments, teams, agents, reporting lines). The default is an interactive visualization with two view modes: hierarchy (dagre, with drag-drop agent reassignment as an inline mutating action) and communication (d3-force). An "Edit Organization" button enters form-based edit mode using the sub-tab structure (General, Agents, Departments) as a panel overlay for bulk configuration changes.

Controller-to-Page Map¶

Every backend controller has a home in the page structure. No orphans.

Design Principle Compliance¶

How this page structure supports the 10 design principles from #762:

Reference Materials¶