Openclaw Web Technical Architecture

# OpenClaw Web Technical Architecture

Status: Draft  
Date: 2026-03-10  
Related: [openclaw-web-platform-spec.md](./openclaw-web-platform-spec.md), [openclaw-local-bridge-protocol-spec.md](./openclaw-local-bridge-protocol-spec.md), [../pi_agent_rust/docs/rpc.md](../pi_agent_rust/docs/rpc.md), [../pi_agent_rust/docs/openclaw-desktop-binding-protocol-spec.md](../pi_agent_rust/docs/openclaw-desktop-binding-protocol-spec.md)

## 1. Architecture Decision

OpenClaw Web will be built as a separate control-plane product.  
`pi_agent_rust` remains the execution runtime on the user machine or on linked cloud hosts.

That means:

- the web app is not a thin wrapper around the Rust CLI
- the source of truth for accounts, workspaces, billing, policies, and orchestration lives in a web control-plane database
- the local OpenClaw runtime is accessed through a dedicated bridge process
- bridge-to-runtime communication uses the existing Pi JSONL RPC surface instead of inventing a second local runtime protocol

## 2. Constraints From `pi_agent_rust`

Current facts from the codebase:

- `pi_agent_rust` is a local CLI/TUI application with headless RPC mode over stdin/stdout
- RPC transport is JSON Lines, not HTTP
- session persistence is local-first and currently supports JSONL plus optional SQLite
- binding definitions already exist in config for Telegram, QQ, Feishu Push, and Feishu Chat
- the desktop specs already assume explicit device linking, deterministic conversation mapping, and local/session ownership

Implication:

- the web platform must treat the local runtime as an attached worker, not as a web-native backend
- the bridge must own process lifecycle, session establishment, permission prompts, and RPC framing
- cloud execution should reuse the same runtime contract where possible so local and cloud remain operationally symmetric

## 3. Recommended Stack

### 3.1 Web application

- Framework: Next.js App Router with TypeScript
- Rendering: hybrid SSR + server actions + route handlers
- Styling: custom CSS tokens and component primitives, avoid template-driven generic UI
- Validation: Zod

Why:

- one codebase covers public site, authenticated app shell, and initial API surface
- SSR is useful for landing pages, docs, pricing, and authenticated dashboards
- route handlers are sufficient for the phase-1 and phase-2 control-plane APIs

### 3.2 Data layer

- Primary relational database: PostgreSQL
- Cache / queue coordination: Redis
- Artifact blob storage: S3-compatible object storage
- ORM: Prisma for schema clarity and initial delivery speed

Why PostgreSQL:

- workspace, membership, billing, orchestration, audit, and linking all need transactional consistency
- JSONB covers flexible metadata without collapsing the model into schemaless storage
- row-level filtering and strong relational modeling matter more than premature polyglot persistence

### 3.3 Deployment baseline

- App runtime: Dockerized Next.js service
- Background workers: separate container running the same codebase in worker mode
- Local dev infra: Docker Compose with Postgres, Redis, MinIO, Mailpit
- Production baseline: one web deployment, one worker deployment, managed Postgres, managed Redis, managed object storage

## 4. Logical Services

The first implementation can live in one repo and one deployable app, but the service boundaries should be explicit.

### 4.1 Web frontend

Responsibilities:

- public marketing pages
- authenticated product shell
- workspace dashboards
- artifact/result presentation
- task launch flows

### 4.2 Control-plane API

Responsibilities:

- identity/session handling
- workspace and membership APIs
- systems, tasks, artifacts, automations CRUD
- bridge/device linking APIs
- cloud host registration APIs
- audit trails

### 4.3 Orchestration worker

Responsibilities:

- task dispatch
- automation scheduling
- webhook handling
- artifact post-processing
- bridge timeout / retry state transitions

### 4.4 Bridge gateway

Responsibilities:

- device registration
- bridge session token issuance
- command fan-out to local devices or cloud hosts
- heartbeat ingestion
- capability and policy enforcement

## 5. Deployment Topology

### 5.1 Local development

- `web`: Next.js application
- `worker`: background job runner
- `postgres`: primary data store
- `redis`: queues, rate limits, transient coordination
- `minio`: artifact/object storage
- `mailpit`: email capture for auth flows

### 5.2 Production

- CDN in front of the web app
- Next.js app instances behind a load balancer
- worker instances separated from request-serving nodes
- managed PostgreSQL with backups and PITR
- managed Redis
- S3-compatible object storage
- secret manager for billing/provider/bridge secrets

## 6. Data Ownership Model

### 6.1 PostgreSQL is authoritative for

- users
- workspaces
- memberships
- plans and billing entitlements
- systems metadata
- linked devices
- linked cloud hosts
- task definitions and run metadata
- artifact metadata and access control
- automation definitions
- integration configs metadata
- audit logs

### 6.2 Object storage is authoritative for

- rendered artifacts
- logs too large for relational storage
- exported site bundles
- snapshots explicitly approved for sync

### 6.3 Local runtime is authoritative for

- local session transcript state
- local vault content when local-only mode is enabled
- secrets that must remain machine-local
- execution details that were never approved for upload

## 7. Database Design Principles

### 7.1 Modeling rules

- every multi-tenant record carries `workspaceId`
- high-sensitivity records track both `createdByUserId` and `lastUpdatedByUserId`
- policy-controlled objects have explicit visibility and sync modes
- run records are append-friendly and audit-friendly

### 7.2 Tenancy rules

- workspace is the main tenant boundary
- user-level records exist only for identity and personal preferences
- device/cloud-host records belong to a workspace but may be user-linked for ownership review

### 7.3 Query rules

- artifact bodies stay out of hot relational queries
- dashboards query summaries and counts from relational tables
- long logs and outputs are fetched from object storage by signed URL or internal proxy

## 8. Integration Model

## 8.1 Local bridge

Flow:

1. user signs into web
2. web creates a short-lived linking challenge
3. local bridge redeems the challenge and receives a device session
4. bridge launches or attaches to `pi_agent_rust --mode rpc`
5. bridge maps web commands into Pi RPC commands
6. bridge streams status/events back to control plane

### 8.2 Cloud host

Flow:

1. cloud host agent registers with control plane
2. host receives scoped runner credentials
3. orchestration worker dispatches queued jobs to the host
4. host runs the OpenClaw runtime and reports heartbeat, queue depth, run events, and artifacts

### 8.3 Shared execution contract

The same logical run model should apply to both local and cloud execution:

- `taskRun` created in control plane
- selected `executionTarget` is `local` or `cloud`
- runtime streams status and result references
- artifact body upload is conditional on policy

## 9. Security Model

- bridge sessions are revocable and short-lived
- bridge never receives full workspace authority; only scoped device/session permissions
- secrets are encrypted at rest in the control plane
- local-only systems can block artifact content upload entirely
- remote launch requires explicit per-system permission
- audit logs are written for linking, task dispatch, publish, restore, and automation changes

## 10. Phased Delivery

### Phase 1

- public site
- auth
- workspace shell
- device linking
- control-plane schema baseline

### Phase 2

- systems
- tasks
- artifacts
- result pages
- website development launcher

### Phase 3

- cloud host linking
- scheduling
- webhook-triggered automations
- publish pipelines

## 11. Non-Goals For The First Cut

- full microservice split
- hard real-time collaboration
- cloud-only replacement of the local runtime
- remote shell access into user devices

## 12. Immediate Engineering Tasks

1. Finalize auth provider and billing provider choice.
2. Implement bridge linking handshake and revocation model.
3. Build database migrations for workspace, device, system, task, artifact, and automation domains.
4. Create task run state machine and worker queue contracts.
5. Add the first real integration path from bridge to `pi_agent_rust` RPC.