Jorvis Architecture - Hermes-Led Live Surface

Architecture View Only

Public supporting references live in Runtime Overview, Current Architecture, and Model Policy Current.

1. System Shape

Current

flowchart LR U["User"] --> W["Open WebUI"] W --> B["Jorvis API"] W --> O["OpenClaw bridge / openclaw_agent"] O --> C["jorvis-openclaw"] B --> D["PostgreSQL / data sources"] B --> V["Voice gateway"] B --> M["MCP / internal tools"] C --> X["OpenClaw memory-search lane"] C --> A["Admin-copilot read-only context"] B --> L["Local fallback lane"] O -. "ENABLE_GUARD_CORE_COMPAT" .-> CP["Compat pre-flight"] CP -. gated .-> C B -. depends .-> FC["jorvis-forecast"]

Live surface

Open WebUI is the main user-facing web surface and auth/UI layer.

System-of-record backend

Jorvis API owns routing, contracts, SQL guardrails, and internal services.

Assistant subsystem

OpenClaw stays a bounded copilot layer; Hermes is the self-evolving layer that grows memory, skills, delegation, and browser work.

Fallback path

Local fallback remains a separate lane from OpenClaw embedding/search policy.

Compat bridge (gated)

PR #443 added a bounded compat pre-flight path behind ENABLE_GUARD_CORE_COMPAT (default off).

Service dependency

jorvis-forecast must start before jorvis-api. See Task-POST-MERGE-PROD-SYNC-HARDENING.

2. Current Production Topology

Current

Service	Role	Canonical reference
jorvis-webui	Open WebUI surface	Operations Overview
jorvis-api	NestJS backend and internal control surface	Current Architecture
jorvis-openclaw	Assistant/copilot runtime	OpenClaw Runtime Operations
jorvis-db	Primary PostgreSQL and app data	Current Architecture
jorvis-voice-gateway	Voice/STT/TTS edge	Current Architecture
ops/grafana + ops/prometheus	Observability access surfaces	Operations Overview

This visual intentionally avoids pinning transient container counts, ad hoc KPIs, or release labels. Use operational docs for deploy-specific verification.

3. Current Request Paths

Current

Text2SQL / analytics path

User -> Open WebUI -> Jorvis API -> SQL guardrails / provider routing -> data source.

Hermes assistant path

User -> Open WebUI `openclaw_agent` -> bridge -> role/memory/admin-context derivation -> `jorvis-openclaw` -> assistant response.

Local fallback path

Jorvis can fall back to a local model lane while Hermes keeps session continuity and memory without conflating it with OpenClaw embeddings.

Compat pre-flight path (gated)

Bridge → compat pre-flight endpoint → jorvis-openclaw. Gated by ENABLE_GUARD_CORE_COMPAT (default off).

4. Subsystem Boundaries

Current

Open WebUI is the UI/auth surface, not the backend source of truth.
Jorvis API owns internal contracts, SQL guardrails, internal services, and control surfaces.
OpenClaw is an assistant/copilot runtime with its own chat lane and embedding/search lane.
Observability is an operational surface, not a blanket product-health badge.
Historical phase plans are not current platform truth.

5. Related Canonical Docs

Current

Current Architecture

Canonical text summary of the current platform shape.

Model Policy Current

Chat lane, memory-search lane, and local fallback separation.

OpenClaw Runtime Operations

Current runtime truth, parity checks, and common failure classes.

OpenClaw Control Plane Visual

Dedicated visual for assistant, memory, and planned control-plane expansion.

Agent Ops Architecture Visual

Human-role model, SSOT flow, and memory guardrails.

Docs and RAG Pipeline Visual

Documentation sources, publishing, KB ingest, and CI validation.

Hermes-led Product Overview

Live product story, safety gates, and Hermes-powered evolution.