Rathvan · architecture review

One kernel, three gates, every integration behind a port

Prepared 2026-08-13, from the code on main. Every count below is a measured test result, not a claim: kernel 428/428, service 97 (0 failed), CLI 13, all run in CI with testCounts — a task that cannot report success without running.

System context

The console and CLI are clients; the builder service hosts the kernel; every external system sits behind a port with a stub beside each live adapter.

flowchart LR
  subgraph Clients
    C[Console
build.rathvan.com]:::c
    CLI[rathvan CLI]:::c
    AG[Agents via MCP/DCR]:::c
  end
  subgraph Builder["Builder service (Java 21, no framework)"]
    OPS["14 named operations
login · workflows · mcpTools
assistant · registerClient"]:::b
    ID["Identity
operator token → user creds
SAML · Google · DCR"]:::b
    BUD[TokenBudget]:::b
  end
  subgraph Kernel["Kernel (library, adopted by products)"]
    K["capabilities · gates · RLS-forced schema
AiRouter · FieldCipher · PiiScan
AutoRemediation · Impersonation"]:::k
  end
  PG[(Postgres
23 additive migrations)]:::d
  GH[GitHub
draft PRs]:::a
  JR[Jira
gate mirror]:::a
  WA[WhatsApp
notifications]:::a
  AN[Anthropic
models]:::a
  C & CLI & AG --> OPS --> ID
  OPS --> BUD --> AN
  OPS --> K --> PG
  K -.SourceControlPort.-> GH
  K -.WorkTrackerPort.-> JR
  K -.NotificationChannelPort.-> WA
  classDef c fill:var(--card),stroke:var(--pass-weak),color:var(--ink-2)
  classDef b fill:var(--line),stroke:var(--accent),color:var(--ink)
  classDef k fill:var(--card),stroke:var(--gate-line),color:var(--gate)
  classDef a fill:var(--card),stroke:var(--line-2),color:var(--ink-3)
  classDef d fill:var(--sunk),stroke:var(--line-2),color:var(--ink-3)

The pipeline: thirteen stages, three human gates

flowchart LR
  S[Sentence] --> I[Intake] --> P[PRD] --> G1{{"◆ Gate 1
agreement"}} --> D[Design] --> B[Build]
  B --> V[Verify] --> G2{{"◆ Gate 2
staging"}} --> G3{{"◆ Gate 3
readiness"}} --> PR[Production]
  G1 & G2 & G3 -. every decision mirrors to Jira,
actor recorded .-> J[(tracker)]
  style G1 fill:var(--gate-weak),stroke:var(--gate-line),color:var(--gate)
  style G2 fill:var(--gate-weak),stroke:var(--gate-line),color:var(--gate)
  style G3 fill:var(--gate-weak),stroke:var(--gate-line),color:var(--gate)

Identity: five doorways, one revocable registry

flowchart LR
  OP[Operator
BUILDER_TOKEN] --> M[mint]
  SA[SAML assertion
pinned cert, single-use] --> R[rotate + mint]
  GO[Google OIDC
JWKS-verified] --> R
  DCR[RFC 7591 DCR
CLOSED by default] --> CL[client credentials]
  M & R --> REG[(UserRegistry
hashes only · revoke by prefix
server-asserted actor)]
  REG --> W[workflow actions
audited, double-attributed
impersonation time-boxed]

Layered adoption model

Layer	Holds	Retrofit cost
L0 foundations	identity · tenancy · RLS · audit · money-minor-units · flags	very high — must exist in migration 1
L1 capabilities	auth · profile · notification · storage · ports/registry	high
L2 relationship	client/professional · payments seam · email · approvals · integrations	moderate
L3 verticals	the actual product (e.g. CRM funnel — PROPOSED until Gate 1)	low — scaffolded per product

Invariants — enforced by tests and DDL, not by review

Invariant	Enforcement
RLS enabled and forced on every user-data table	gate test scans every migration for the pair
Migrations additive only, contiguously numbered	checksummed; gate test fails on a gap
Feature flags default OFF and registered	registry map; unregistered = permanently inert
Money is an integer in the smallest unit	DDL + kernel types; no float path exists
PII never logged or sent to a model	`PiiScan` (masked findings, `redact()`) + `FieldCipher` (AES-GCM, column-bound)
Production branch unreachable by machines	`SourceControlPort` refuses main at construction
AI spend bounded	`TokenBudget` is a meter decorator — no call site can skip it
A test count below known-good fails the build	`testCounts`; a shrunken suite renders FAILED in evidence reports

Deliberate seams (port exists, adapter is BYO): search, queue/messaging, payments gateways, observability backend. Deliberately refused: docs rendering, SDK generation, a Backstage-rivaling catalogue, A/B testing.

Live demo — a real first run, nothing mocked

Recorded from Chrome: one sentence starts the intake, 23 gated questions, sign-in with a personal revocable credential, and a workflow honest about what was simulated. This is the system above, operating.

Second cut, narrated (2 min), covering the pipeline and this release's capabilities:

Presentation deck

Six slides for the review itself — present full-screen; each fills the viewport.

1 / 6 · the problem

Most code is now written by agents. Nothing makes it follow your method.

Prompt-to-app tools are fast to a demo and silent on production. Portals catalogue what exists and cannot create it. The gap: a control plane where agents build inside the rules — reuse enforced, security structural, humans at the gates.

2 / 6 · the approach

The method is data. The rules are tests.

13 stages, 3 human gates — encoded in manifest.yaml, rendered everywhere from one source
The ~10k-line foundation is scaffolded, not generated: 91 files, 0 model tokens
Every invariant is a gate test or DDL constraint — review checks judgment, not compliance

3 / 6 · architecture

One kernel, adopted by products. Every integration behind a port.

Kernel: capabilities registry, RLS-forced schema, AiRouter, FieldCipher, PiiScan
Live adapters: GitHub (draft PRs, can’t target main), Jira (gate mirror), WhatsApp, Anthropic
Deliberate seams: search, queues, payment gateways — ports with stubs, BYO adapters

4 / 6 · identity & security

Five doorways. One revocable registry.

Operator token → minted per-user credentials (hashes only, revoke by prefix)
SAML (pinned cert, wrapping/XXE/replay closed) and Google OIDC — each sign-in rotates the token
RFC 7591 DCR for machines, CLOSED by default · impersonation time-boxed and double-attributed
AES-GCM field encryption, column-bound · PII scanner whose findings are masked

5 / 6 · verification

428 + 97 + 13 tests. Counted, never assumed.

testCounts, never bare test — a shrunken suite fails the build and renders FAILED in evidence
CI runs the 18 Postgres integration tests for real · CodeQL weekly · Dependabot on 5 ecosystems
Every claim in this deck is a test result or a live smoke test from this repo

6 / 6 · roadmap

Free & open source. The enterprise tier is the control plane.

Shipped: MCP surface, agent catalogue, token budgets, auto-remediation, evidence exports
Next: hosted try-it sandbox · runtime-tenant console · perf gates in CI · A2A/ACP adapter
Refused on purpose: docs rendering, SDK gen, catalogue wars, A/B testing