ArchitectureCurrent Architecture

Current Architecture

Current Architecture

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
  • PostgreSQL as the primary system database
  • Redis Cache Layer for static data optimization
  • supporting sidecars for 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-db — PostgreSQL
  • 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. Document & Knowledge path

  1. User uploads documents or asks knowledge-base questions
  2. jorvis-api handles document ingestion, OCR, and knowledge-base retrieval
  3. Results are returned with source attribution

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
  • dated docs and snapshots are historical unless explicitly refreshed

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