Architecture Overview

Keeptrusts is an AI governance platform that sits between your applications and AI providers. Every AI request flows through a policy gateway that enforces guardrails, injects curated knowledge, controls spend, records decisions, and routes escalations — all before anyone sees the response.

Use this page when

• You need to understand how Keeptrusts components connect before deploying or integrating.
• You are deciding whether to run a local gateway, a hosted gateway, or both.
• You need to explain the trust model and data flow to a security reviewer or compliance auditor.
• You want to understand which component owns which concern (policy enforcement, persistence, user access).

Primary audience

• Primary: Technical Leaders
• Secondary: Technical Engineers, AI Agents

System Components

Component Roles

Component	Role	Technology
Gateway	Intercepts AI traffic, enforces policies, injects knowledge, reserves wallet spend, emits events	Rust binary (kt gateway run)
API	Control plane — auth, events, escalations, exports, configurations, agents, knowledge, wallets, connectors, audit log	Rust (Axum), PostgreSQL
Console	Management dashboard — events, escalations, agents, knowledge base, configurations, templates, gateways, wallets, settings	Next.js, server-side BFF
Chat workbench	Governed AI chat with knowledge-grounded responses, wallet integration, and conversation history	Next.js
CLI	Gateway operation, policy authoring, knowledge mining, event queries, declarative config management	Rust binary (kt)
Background workers	Export jobs, config sync, lifecycle retention, webhook delivery	Rust binaries

Boundaries and Trust Model

Keeptrusts separates concerns into three boundary zones:

Boundary	What lives here	Trust model
Data plane	Gateway, policy chains, provider connections	Runs in your infrastructure or as a hosted gateway service. Enforces policies locally. Never stores persistent state.
Control plane	API, PostgreSQL, background workers	Authoritative source of truth for configurations, events, wallets, knowledge, escalations, and audit log.
User surfaces	Console, chat workbench, CLI	The browser never holds upstream API tokens. Console uses a server-side BFF proxy. Chat authenticates through a PKCE handoff from the console.

Request Flow

Every AI request passes through the gateway where policies are evaluated, knowledge is injected, and spend is controlled:

Policy Execution Model

Policies are defined in a declarative YAML configuration and execute as an ordered chain:

policies:
  chain:
    - prompt-injection      # Input: detect injection attacks
    - pii-detector          # Input: redact personal data
    - hipaa-phi-detector    # Input: redact protected health info
    - quality-scorer        # Output: evaluate response quality
    - human-oversight       # Output: escalate uncertain responses
    - audit-logger          # Audit: log all decisions

Input policies run before the request reaches the AI provider. They can block, redact, or allow the request.

Output policies run after receiving the AI provider's response. They can score, escalate, rewrite, or block the response.

Audit policies run at all phases and capture structured evidence for compliance.

Data Flow

Data	Source	Destination	Purpose
Decision events	Gateway	API → PostgreSQL	Full audit trail of every AI request
Knowledge assets	Console / CLI / Git	API → Gateway (recall)	Curated context injected at runtime
Knowledge citations	Gateway	API → PostgreSQL	Record of which assets were recalled per request
Wallet reservations	Gateway	API → PostgreSQL	Cost control — reserve before, settle after
Configurations	CLI / Console / Git	API → Gateway (reload)	Policy enforcement rules
Escalations	Gateway events	API → Console	Human review queue with claim/resolve workflow
Conversation history	Gateway	API → PostgreSQL	Session-attributed request/response pairs
Learned knowledge	History sessions	API → Knowledge Base	Condensed conversation insights promoted to runtime context
Connector capabilities	MCP servers	API → PostgreSQL	External tool metadata for governed access
Exports	API	CSV / JSON / S3	Compliance evidence packets
Audit log	All control-plane writes	API → PostgreSQL	Tamper-resistant change tracking

Agent Governance Model

Agents are first-class identities in Keeptrusts. Each agent represents a distinct AI system whose traffic flows through the gateway.

Feature	How agents participate
Identity tracking	Gateway attributes every request to the linked agent
Knowledge injection	Only knowledge assets bound to the requesting agent are recalled
Connector access	Only connectors bound to the agent are available for tool calls
Policy targeting	Policies can target specific agents via scope selectors
History capture	Conversation history is attributed to the agent
Escalation routing	Escalations can be routed based on agent configuration
Usage constraints	Credit ceilings and token limits per agent prevent runaway spend

Knowledge Lifecycle

Knowledge assets flow through a governed lifecycle from creation to runtime recall:

Create (draft) → Review → Promote (active) → Bind to agent → Recall at runtime → Citation recorded

Assets can be static (manually authored), upload (file-based), git_sync (repository-backed), or learned_session (synthesized from conversation history). Only active assets with an agent binding are eligible for gateway recall.

See Knowledge Base and Knowledge Lifecycle for the full guide.

Wallet and Spend Control

The gateway makes a synchronous reserve call before every request and settles the actual cost on response. The balance cascade walks user → team → organization wallets in priority order:

Request arrives → Resolve wallet scope → Reserve estimated cost → Forward to provider → Settle actual cost → Release surplus

If no wallet has sufficient balance, the gateway issues a cost ticket (HTTP 402) and the caller must top up before retrying. PayPal self-service top-up is available from both the console Wallets page and the chat workbench.

See Wallets and Cost and Spend for the full guide.

Chat Workbench

The chat workbench is a governed AI assistant that routes through the Keeptrusts gateway. It supports:

• Auth handoff: Users authenticate through the console via a PKCE flow. The browser never sees the upstream API token.
• Knowledge-grounded responses: Bound knowledge assets are injected as runtime context.
• Wallet integration: Balance is displayed in the sidebar; insufficient-balance triggers self-service top-up.
• Conversation history: Every session is captured and attributed to the agent for audit and learning.
• Connector-backed tools: Bound connectors expose governed read-only tool access.

Multi-Provider Fallback

The gateway supports multiple upstream AI providers with automatic failover:

pack:
  name: architecture-providers-2
  version: 1.0.0
  enabled: true
providers:
  targets:
  - id: openai-primary
    provider: openai
    model: gpt-4o
    base_url: https://api.openai.com
    secret_key_ref:
      store: OPENAI_API_KEY
  - id: anthropic-fallback
    provider: anthropic
    model: claude-sonnet-4-20250514
    base_url: https://api.anthropic.com
    secret_key_ref:
      store: ANTHROPIC_API_KEY
    provider_type: anthropic
    format: anthropic
policies:
  chain:
  - audit-logger
policy:
  audit-logger:
    immutable: true
    retention_days: 365
    log_all_access: true

Security Model

• Authentication: All API access requires an API key or JWT token. JWT supports key rotation via kid header.
• BFF proxy: The console browser never contacts the API directly. All authenticated traffic goes through server-side BFF routes.
• Chat auth handoff: Chat authenticates through the console via a PKCE flow with a single-use handoff token.
• Token types: Access Keys authenticate application traffic. Gateway Keys authenticate hosted runtime instances. Both are filtered views over a shared token table.
• Secrets at rest: Git access tokens and webhook secrets are AES-GCM-SIV encrypted.
• Zero Data Retention: ZDR mode routes traffic only to compliant providers and suppresses content capture.
• RBAC: Role-based access control with team scoping, MFA, passkeys, and SSO (OIDC/SAML).
• Tenant isolation: All data paths enforce explicit tenant scoping. Cross-tenant access is architecturally impossible.

For AI systems

• Canonical terms: Keeptrusts architecture, data plane, control plane, user surfaces, gateway, API, console, chat workbench, BFF proxy, wallet reserve/settle, knowledge recall, policy chain.
• Key components: Gateway (Rust kt gateway run), API (Rust Axum + PostgreSQL), Console (Next.js BFF), Chat (Next.js), CLI (kt), Background Workers.
• Trust model: Data plane (stateless enforcement), Control plane (persistent state), User surfaces (no direct API token exposure).
• Related pages: Gateway Runtime Features, Config-First Workflow, Console Overview, Security Settings.

For engineers

• The gateway is stateless — it enforces policies locally and emits events to the API. No persistent state lives on the gateway.
• The console BFF proxy means the browser never contacts the API directly. Authentication and token management are server-side.
• Wallet reserve/settle adds ~5–15 ms latency before forwarding to the provider. This is synchronous and mandatory when wallets are enabled.
• To verify the architecture is working end-to-end: send a request through the gateway, check Events in the console, and confirm the decision event includes policy verdicts and cost attribution.
• For multi-provider failover, configure providers.targets[] with fallback.triggers in policy-config.yaml.

For leaders

• The gateway runs in your infrastructure or as a managed service — you control where AI traffic flows and where evidence is stored.
• Tenant isolation is architectural: all data paths enforce explicit org scoping, and cross-tenant access is impossible.
• The BFF security model means a browser compromise cannot exfiltrate upstream API tokens.
• Wallet integration provides hard financial controls at the request level, preventing runaway AI spend before it happens.
• Multi-provider fallback with cost-based routing (max_price) lets you optimize cost without sacrificing availability.
• The full audit trail (events + audit log + wallet transactions) supports SOC 2, HIPAA, and EU AI Act compliance evidence requirements.

Next steps

• Console Overview — Full feature inventory of the management console
• Customer Journeys — Task-oriented workflows across the platform
• Gateway Runtime Features — Policy chains, routing, caching, and runtime behavior
• Declarative Config Reference — Full YAML configuration specification