ArchitectureCurrent Architecture

Current Architecture

Current Architecture

Canonical markdown page for this topic. Rendered reference version: current-architecture.

Last Updated: 2026-03-22 Status: Active current-state overview

This document is the slim, current-state architecture overview for Jorvis.

Use it together with:

System Shape

Jorvis is a production AI analytics platform with:

  • Open WebUI as the main user-facing web surface
  • a NestJS backend (jorvis-api) as the authoritative application layer
  • OpenClaw as the assistant / copilot subsystem
  • PostgreSQL as the primary system database (with Dual Write v1/v2 mechanism for embedding migration)
  • Redis Cache Layer for static data optimization
  • supporting sidecars for forecasting, pipelines, voice, and an optional local llama.cpp fallback profile

Current Production Topology

Primary services in deploy/docker-compose.prod.yml:

  • jorvis-webui — user-facing web UI
  • jorvis-api — main NestJS backend
  • jorvis-openclaw — assistant / copilot runtime
  • jorvis-db — PostgreSQL
  • jorvis-forecast — forecast sidecar
  • voice-gateway — voice/STT/TTS integration
  • jorvis-pipelines — pipeline sidecar
  • jorvis-local-llm — optional local llama.cpp runtime (profile-gated)
  • jorvis-local-llm-heartbeat — optional keep-warm process for the local model

Primary Request Paths

1. Text2SQL / analytics path

  1. User interacts through jorvis-webui
  2. WebUI calls jorvis-api
  3. jorvis-api handles guardrails, orchestration, data access, and response shaping
  4. Results are returned to WebUI

2. OpenClaw assistant path

  1. User selects or invokes the OpenClaw surface from WebUI
  2. The WebUI function bridge mediates access to jorvis-openclaw
  3. Admin-safe enrichment and policy logic are applied before returning the response
  4. OpenClaw memory and admin-copilot surfaces remain internal, guarded routes

3. Local fallback path

  1. Primary hosted model path is used first
  2. Optional local llama.cpp fallback remains available through the configured chain when the local-llm profile is enabled
  3. jorvis-local-llm-heartbeat keeps the local model warm only when that optional profile is intentionally enabled

Current Architecture Principles

  • jorvis-api is the authoritative backend for SQL, guardrails, internal routes, and operational policy
  • Open WebUI is the presentation/auth surface, not the system-of-record for backend logic
  • OpenClaw is integrated as an assistant/copilot layer, not as merge/release authority
  • project-local AIM KG (location="project", context="jorvis") is the shared live memory layer for agent coordination
  • dated docs and snapshots are historical unless explicitly refreshed

Current High-Value Engineering Focus

The current runtime follow-up is docs corpus refresh and KB/RAG validation against the verified baseline.

Recent completed runtime work:

  • PR #410 — OpenClaw bridge typed capability consumption (Phase 2); secret guard ordering fix; express-rate-limit CVE-2026-30827 resolved
  • PR #407 — OpenClaw typed capability surface (Phase 1): NestJS service + controller + 29 tests
  • PR #400 — build-aware prod sync remediation

Current implication:

  • the next package should start from docs refresh, KB sync, and embedding-v2 validation against the verified baseline

Current OpenClaw state:

  • runtime memory-search truth is correct and verified
  • internal search-config contract is normalized in code and on prod
  • typed capability surface is live; bridge consumes it with fallback
  • secret-exfiltration guard runs before typed capability resolution
  • behavior remains non-mutating/advisory in the current production boundary

Boundaries

This file should describe:

  • what is currently deployed or intentionally active
  • the main runtime components and request paths
  • current architectural constraints that matter for execution

This file should not become:

  • a full feature matrix
  • a roadmap backlog
  • a replacement for ADRs
  • a release log