Architecture
This document describes the Tavrik system architecture. It is a living document; significant changes are recorded as ADRs in docs/decisions/.
Update note (M0): Architecture extended to reflect the four-surface coverage decision (ADR-0007). The original API gateway path remains intact; browser extension, endpoint agent, and ecosystem connector framework are now first-class peers.
Update note (M5.A): Vertical-pack framework (ADR-0042) introduces per-tenant, per-vertical recognizer + connector bindings. The healthcare vertical (M5.A.2-M5.A.11) is the first concrete consumer: HL7 v2.x / FHIR R4 / DICOM / healthcare-identifier recognizers plus EHR-adjacent connectors (HL7 v2.x ARV over Mirth MLLPS; FHIR R4 AuditEvent over HTTPS) per ADR-0043. Future verticals (financial services, defense, legal) inherit the pattern.
High-level diagram
┌─────────────────────────────────────────────────────────────────────────────┐│ CLIENT LAYER ││ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ ││ │ Customer │ │ User browser │ │ User desktop │ │ Microsoft 365, │ ││ │ apps + SDKs │ │ (extension) │ │ (endpoint │ │ Google WS, │ ││ │ (OpenAI- │ │ │ │ agent) │ │ Salesforce, │ ││ │ compatible) │ │ │ │ │ │ etc. │ ││ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └────────┬───────┘ │└─────────┼─────────────────┼─────────────────┼───────────────────┼───────────┘ │ │ │ │ │ TLS 1.3 │ TLS 1.3 │ TLS 1.3 │ Platform │ (mTLS opt.) │ │ │ APIs ▼ ▼ ▼ ▼┌─────────────────────────────────────────────────────────────────────────────┐│ COVERAGE SURFACES (per ADR-0007) ││ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ ││ │ API gateway │ │ Browser │ │ Endpoint │ │ Ecosystem │ ││ │ │ │ extension │ │ agent │ │ connectors │ ││ │ services/ │ │ agents/ │ │ agents/ │ │ connectors/ │ ││ │ gateway │ │ browser │ │ endpoint │ │ <platform> │ ││ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └────────┬───────┘ │└─────────┼─────────────────┼─────────────────┼───────────────────┼───────────┘ │ │ │ │ └─────────────────┴────────┬────────┴───────────────────┘ │ All four surfaces hit the same core ▼┌─────────────────────────────────────────────────────────────────────────────┐│ GOVERNANCE CORE ││ ││ AuthN/AuthZ · Tenant resolution · Rate limiting ││ │ ││ ▼ ││ INBOUND POLICY & SECURITY PIPELINE ││ Input validation → PII/PHI scan → Redact/Tokenise → ││ Prompt-injection detection → OPA policy eval → Audit log entry ││ │ ││ ▼ ││ ROUTING ENGINE ││ Cost · Capability · Industry pack · Latency · Residency · Policy ││ Semantic cache check · Fallback chain · A/B + shadow eval ││ │ ││ ▼ ││ MODEL ADAPTER LAYER ││ Claude · OpenAI · Gemini · Bedrock · Azure OAI · Ollama · vLLM · custom ││ │ ││ ▼ ││ OUTBOUND POLICY & SECURITY PIPELINE ││ Jailbreak detection · PII leak scan · Citation validation · ││ Tokenise back / restore redactions · Audit log completion ││ │ ││ ▼ ││ OBSERVABILITY & FINOPS ││ OpenTelemetry traces · Metrics · Cost ledger · Usage analytics │└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐│ COMPLIANCE & TRUST LAYER (cross-cutting) ││ Tenant isolation · Data residency router · Append-only audit ledger ││ BYOK broker · Right-to-erasure orchestrator · Model card recorder ││ Policy version manager · Evidence collector │└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐│ CONTROL PLANE (separate from data plane) ││ Tenant mgmt · Licensing · Billing · Policy authoring · Pack marketplace ││ Admin console · Trust centre │└─────────────────────────────────────────────────────────────────────────────┘The defining property: all four coverage surfaces enforce the same policy and write to the same audit log. This is the consistency guarantee the wedge depends on.
Service decomposition
| Service | Language | Purpose |
|---|---|---|
gateway | Go | API ingress. Auth, rate limiting, tenant resolution, request orchestration. |
router | Go | Routing engine. Decides which model handles a given request. |
policy | Go + OPA | Evaluates inbound and outbound policies; manages versions. |
adapters | Go | Per-provider client libraries. |
console | TypeScript (Next.js) | Web UI for admins, devs, compliance, finance. |
billing | Go | Cost ledger, FinOps analytics, chargeback. |
agents/browser | TypeScript (WebExtensions) | Cross-browser extension enforcing policy on web AI tools (M4-M5). |
agents/endpoint | Go | Per-OS endpoint agent (Windows, macOS, Linux) for desktop AI (M6+). |
connectors/<platform> | Go | Ecosystem connectors (Microsoft Purview, Copilot Studio, Google Workspace, etc.). Generic framework + per-platform implementations. |
Data stores
Unchanged from original architecture. See ADR-0003.
| Store | Purpose |
|---|---|
| PostgreSQL | Tenant metadata, policies, licences, RBAC. RLS for tenant isolation. |
| ClickHouse | Telemetry, cost events, usage analytics, audit hot tier. |
| Redis / Valkey | Rate limit counters, session cache, semantic cache index. |
| pgvector / Qdrant | Semantic cache vectors. |
| S3-compatible | Audit cold tier, opt-in archives, exports. Object lock for tamper evidence. |
Coverage surfaces — what they actually do
API gateway (services/gateway)
The original front door. Customer apps and agents call it directly. Status: M1.
Browser extension (agents/browser)
A WebExtension installed on user browsers (Chrome, Edge, Firefox, Safari). Hooks into known AI tool URLs (ChatGPT, Claude, Gemini, Copilot web, Perplexity, plus a maintained list of long-tail tools). Before submission, evaluates the request against tenant policy via the Tavrik control plane. Blocks, redacts, or allows. Logs to the same audit ledger.
Deployable via MDM (Intune, Jamf, Workspace ONE) for managed devices; published to Chrome Web Store / Edge Add-ons / Firefox AMO / Safari for unmanaged use cases.
Status: targeted M4-M5.
Endpoint agent (agents/endpoint)
A small native agent (Windows MSI, macOS pkg, Linux deb/rpm) that sees AI usage the browser extension can’t. Clipboard inspection (policy-controlled), local AI tool detection (Cursor, Ollama, ChatGPT desktop, Claude desktop, Cowork, etc.), IDE plugin observation, network observation for AI-bound traffic.
Status: targeted M6+.
Ecosystem connectors (connectors/<platform>)
Bidirectional integrations with platforms that have their own AI surfaces and their own governance signals. Each connector pulls relevant policy/signals upstream and pushes audit events downstream.
Initial connectors (in landed / roadmap order):
connectors/sentinel— Microsoft Sentinel via HTTP Data Collector API (M3.9, ✅ shipped).connectors/hl7mirth— HL7 v2.x ARV via Mirth MLLPS (TLS 1.3) — bound to the healthcare vertical pack (M5.A.8, ✅ shipped per ADR-0043).connectors/fhiraudit— FHIR R4 AuditEvent via HTTPS (TLS 1.3) — bound to the healthcare vertical pack (M5.A.9, ✅ shipped per ADR-0043).connectors/microsoft-purview— sensitivity labels in, audit events out (M5+).connectors/microsoft-copilot-studio— agent template using Tavrik as routing/governance (M5+, per ADR-0006).connectors/google-workspace— DLP labels in, audit out (M7+).connectors/splunk— audit events out (M7+).connectors/servicenow-grc— evidence and policy lifecycle integration (M7+).connectors/slack— workspace AI usage governance (M7+).
Custom connectors via the framework documented in connectors/README.md. EHR-adjacent connectors (hl7mirth, fhiraudit) extend the ADR-0036 framework with healthcare-specific abstractions (internal/connectors/ehr/auditformat/ + internal/connectors/ehr/transport/ + per-connector ConfigValidator for the validate-before-connect seam).
Vertical packs (ADR-0042, M5.A)
Vertical packs are per-vertical bundles of recognizers + connector references. A pack defines:
- Recognizers: per-category detection patterns (e.g., HL7 v2.x message-shape detection, FHIR R4 resource-fragment detection, DICOM identifier detection).
- Connectors: connector implementations that ship audit events to vertical-specific aggregation infrastructure (e.g., HL7 integration engines, FHIR audit endpoints).
Packs are operator-enabled per-tenant via tenant_vertical_pack_policies (M5.A.1). The pack binding is metadata-only — operators still configure per-tenant connector policies explicitly per ADR-0036 §6.
The healthcare pack (M5.A.2-M5.A.5 recognizers + M5.A.7-M5.A.9 connectors) is the first concrete consumer. Future packs (financial services, defense, legal) inherit the framework.
Critical cross-cutting concerns
Multi-tenancy, audit log, encryption, residency, right-to-erasure
Unchanged from the original architecture. See ADR-0003, ADR-0004, ADR-0005. The four-surface coverage doesn’t relax these — every surface must respect them.
Policy distribution to surfaces
A new concern introduced by ADR-0007. The policy engine emits OPA-compiled bundles consumed by:
- The gateway (in-process OPA).
- The browser extension (delivered via control-plane API at startup, refreshed periodically; bounded TTL cache).
- The endpoint agent (same pattern as browser).
- The connector layer (per-connector bundle subset).
Bundle distribution uses OPA’s standard bundle service pattern. Bundles are signed; surfaces verify signatures before applying.
Audit log convergence
All four surfaces write to the same hash-chained audit ledger via a small audit-emit API exposed by the control plane. Every event includes the originating surface as a tagged field so customers can filter/audit per surface or aggregate across.
Request lifecycle (happy path) — multi-surface
The original API path remains. Browser and endpoint paths are new and worth documenting:
Browser surface:
- User types or pastes content into a known AI tool (e.g. ChatGPT).
- Browser extension intercepts the submit event.
- Extension calls Tavrik policy evaluation API with request context (tool, user, content fingerprint).
- Policy decision returned: allow / redact / block / warn.
- If redact, extension transforms the content before submission.
- If block, extension prevents submission and surfaces a tenant-configurable explanation to the user.
- Audit event written.
Endpoint surface:
Similar pattern, applied to clipboard pastes into known AI applications, file uploads through AI tool client apps, and observed network connections to known AI APIs from non-managed processes.
Ecosystem connector surface (Microsoft Copilot Studio example):
- User invokes a Copilot Studio agent that has been built using the Tavrik Copilot Studio template.
- The agent calls the Tavrik API with the user’s request.
- Tavrik applies policy, routes to the customer-configured model (which may be a sovereign / local model), returns response.
- Audit event written. Microsoft 365 audit log also receives a record via the Purview connector.
Failure modes
Unchanged from original; the new surfaces respect the same fail-closed defaults.
Deployment topology
- SaaS: Kubernetes (EKS/GKE/AKS), per-region clusters. Browser extension and endpoint agent talk to the SaaS control plane.
- On-prem: Helm chart + air-gappable container images. Browser/endpoint agents talk to the customer’s on-prem control plane.
- Sovereign-cloud: dedicated regional deployments. Single-tenant where required.
- Single-binary appliance build: for small on-prem deployments and the future hardware appliance path (ADR-0008).
- Licence enforcement (on-prem and appliance): signed JWT.
What’s deliberately not in v1
- Mobile-native AI surface coverage (iOS/Android apps) — deferred until clear customer demand.
- Voice/audio AI coverage — deferred; text + vision + documents only.
- Third-party connector marketplace — first-party only initially.
- Training or fine-tuning — out of product scope.
- Hosted vector DB — we integrate with customers’ existing.