ARCHITECTURE / TWO RUNTIMES · ONE SOURCE OF TRUTH

Backend authority.Node experience.Replaceable infrastructure.

Cap2Layer deliberately separates the server that owns product rules from the server that renders the user experience.

RUNTIMES 02HEXAGONAL COREDIRECT UI→DB 00BOUNDARIES ENFORCED
REQUEST PATHAUTHORITY PATHEVIDENCE PATH
UX
01
EXPERIENCE SERVERNODE / NEXT

Conversation, Workbench, configuration and authorization experiences. The Knowledge Agent (KA) is the conversational layer that turns human intent into governed operations.

KA CHATWORKBENCHCONFIGPREVIEW
BACKEND-OWNED API
EXPLICIT AUTHORITY
READ MODELS + EVIDENCE
AUTH
GATE
CORE
02
AUTHORITY SERVERPYTHON BACKEND

Policy, identity, orchestration and the single source of operational truth.

INTERFACESAPPLICATIONDOMAINPORTS
DB
DATABASE ADAPTERSpersistence profiles
AI
LLM PROFILESprovider-backed workers
KEY
VAULT / OAUTHcredentials & authority

01 Product meaning flows inward 02 Infrastructure remains replaceable at the edges

SERVER 01

Python backend

Owns authentication, workspace/project scope, KA semantics, Workbench read models, preview/apply policy, MCP transport, OAuth, vault references, persistence profiles, LLM readiness and every persisted product rule.

  • Single source of operational truth
  • No business rules delegated to the browser
  • AI-correctable API and MCP responses
BACKEND-OWNED APIs
preview / apply / read models
←———→
SERVER 02

Node.js / Next UX

Owns the interaction surface: KA conversation, Workbench navigation, configuration dialogues, provider setup and human authorization experiences.

  • No direct database or provider access
  • No local invention of scope, OAuth or policy
  • Renders exactly what backend read models authorize
01

Interfaces

Hosted MCP, HTTP/UI, OAuth and future clients

Transport adapters enter through explicit contracts.
02

Application

Records, cuts, certified prompts and result certification. A Work Item is a unit of work with its scope and definition of done. A Step is an executable part of a Work Item. A cut is one bounded execution of a Step, on its own branch, limited to declared paths. A certified prompt is the exact instruction the AI programmer executes, bound to the authorized scope. Queueing for parallel work is in progress. A lease (in progress) is a reservation that will let parallel cuts avoid colliding.

Coordinates behavior without knowing engines or transports.
03

Domain

Records, identity, authorization, profiles, execution semantics and policy

Pure product meaning, independent from frameworks.
04

Ports

Persistence, LLM inference, vault, provider and repository capabilities

Stable contracts point outward without importing infrastructure.
05

Adapters

Supabase/Postgres, OpenAI-compatible inference, hosted MCP and provider integrations

Concrete engines implement ports and remain replaceable.
Persistence

Supabase/Postgres is first

Future: direct Postgres, Aurora, SQLite/local, object storage, Elasticsearch, Notion or Airtable through the same boundary.

LLM runtime

Provider registry + runtime profiles

Customer-configured providers, model compatibility probes, worker roles and safe credential references—no single hardcoded LLM.

Client surfaces

Node/Next today

Web, IDE, mobile, REST, gRPC or approval clients can call the same application services through new interface adapters.

Change the engine.
Keep the product meaning.

  • Core independence

    Domain and application never depend on Supabase, FastAPI, Next.js or a specific LLM SDK.

  • Explicit provider choice

    Multiple provider profiles are explicit; no silent fallback when several choices exist.

  • Secrets stay referenced

    Secrets remain behind vault references and never enter prompts, UI payloads or logs.

  • Boundaries are product rules

    Boundary violations are treated as product bugs, not stylistic disagreements.