docs(atlas): bootstrap architecture baseline

Atlas Architecture Baseline

This MR establishes the architecture baseline for OpenClaw Office, a single-service React application with 8 components and 5 primary interaction paths. All components identified with high confidence.

Tech Stack

Technology	Version	Confidence	Purpose
TypeScript	~5.9.3	high	Primary language for type-safe development
JavaScript	ES2020+	high	Runtime execution environment
React	19.2.0	high	Frontend UI framework for isometric office visualization
Vite	^7.3.1	high	Build tool and dev server with SSE middleware
Node.js	18+	high	Server runtime for Vite plugin and file I/O
pnpm	8+	high	Package manager for dependency management
Filesystem	N/A	high	JSON-based state persistence (~/.openclaw, .openclaw-office/replay)
localStorage	N/A	high	Browser-side persistence for preferences and workspace state
Vite Dev Server	^7.3.1	high	Local development server (127.0.0.1:5179)
Server-Sent Events	N/A	high	Real-time state streaming protocol
Vitest	^4.0.18	high	Unit testing framework
Playwright	^1.58.2	medium	End-to-end testing framework

Components

ID	Name	Type	Description	Source Path	Confidence
1	Frontend SPA	UI Application	Real-time React dashboard with isometric office visualization	src/	high
2	Vite Plugin API	Middleware	Embedded HTTP middleware serving SSE streams and REST endpoints	server/	high
3	Office State Builder	Service	Reads OpenClaw agent/subagent state from filesystem	server/office-state.ts	high
4	Stream Bridge	Service	Lifecycle event diffing and SSE backfill management	server/stream-bridge.ts	high
5	Snapshot Store	Service	Replay persistence with time-based indexing	server/snapshot-store.ts	high
6	OpenClaw Hub	UI Component	Project status dashboard with progressive disclosure	src/components/OpenClawHub.tsx	high
7	Command Palette	UI Component	Keyboard-driven command execution with rebindable shortcuts	src/components/CommandPalette.tsx	high
8	Alert Engine	Service	Rule-based signal evaluation with mute/snooze controls	src/lib/alerts.ts	high

Interactions

From	To	Protocol	Description
Browser	Vite Dev Server	HTTP/SSE	Real-time office state stream
Vite Plugin	Filesystem	File I/O	Reads ~/.openclaw/agents//sessions/.json
Stream Bridge	Frontend	SSE	Lifecycle events with cursor-based backfill
Frontend	Vite Plugin	REST	GET /api/office/snapshot, /api/office/metrics, /api/office/openclaw-hub
Snapshot Store	Filesystem	File I/O	Persists replay snapshots to .openclaw-office/replay/

System Architecture

Data Flow

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E8E8E8','primaryTextColor':'#333','lineColor':'#666','secondaryColor':'#F5F5F5'}}}%%
flowchart LR
    FS1["~/.openclaw/agents/*/sessions/sessions.json"]
    OSB[Office State Builder]
    OS[OfficeSnapshot]
    SB[Stream Bridge]
    LE[LifecycleEnvelope Array]
    SSE[SSE Stream]
    BE[Browser EventSource]
    UOS[useOfficeStream Hook]
    RS[React State]
    OC[OfficeStage Canvas]
    SS[Snapshot Store]
    FS2[".openclaw-office/replay/*.json"]
    LS[localStorage]
    BA[Batch Actions State]
    AP[Alert Preferences]
    WL[Workspace Layout]
    VP[Vite Plugin API]
    REST["/api/office/*"]

    FS1 -->|"File I/O"| OSB
    OSB -->|"JSON aggregation"| OS
    OS -->|"Diff snapshots"| SB
    SB -->|"Generate events"| LE
    LE -->|"Server-Sent Events"| SSE
    SSE -->|"event: snapshot, lifecycle"| BE
    BE -->|"Merge events"| UOS
    UOS -->|"Update state"| RS
    RS -->|"Render"| OC
    OS -->|"Time-indexed persistence"| SS
    SS -->|"Write JSON"| FS2
    BA -->|"JSON serialization"| LS
    AP -->|"JSON serialization"| LS
    WL -->|"JSON serialization"| LS
    BE -->|"HTTP GET"| REST
    REST -->|"REST endpoints"| VP
    VP -->|"Read state"| OSB

Ambiguities & Improvements

Ambiguities:

• OpenClaw runtime location (severity: low): Defaults to ~/.openclaw but configurable via OPENCLAW_STATE_DIR
• Production deployment strategy (severity: medium): README shows dev server only, no production hosting guidance
• Multi-user support (severity: low): Binds to 127.0.0.1 only, designed for single-user local operation
• Replay store eviction policy (severity: low): Snapshot retention limits not documented in code
• SSE reconnection strategy (severity: medium): Client-side reconnect logic not visible in provided files

Recommended Improvements:

• Document production build and deployment process (nginx/caddy reverse proxy, systemd service)
• Add SSE reconnection logic with exponential backoff in frontend
• Implement replay snapshot eviction policy (e.g., keep last 100 snapshots or 7 days)
• Add configuration documentation for OPENCLAW_STATE_DIR environment variable
• Consider adding health check endpoint for monitoring

Generated Files

• docs/architecture/TECH_STACK.md
• docs/architecture/ARCHITECTURE.md
• docs/architecture/DATA_FLOW.mmd
• docs/architecture/DEPLOYMENT_BOARD.puml
• docs/architecture/SEQUENCE_FLOW.puml
• docs/architecture/README.md (architecture overview)