Architecture Decisions (ADRs)

This section explains how Nexus works under the hood — the architecture, design decisions, and core concepts that power a secure, auditable AI gateway.

• Contributors who want to understand the system design before coding
• Security engineers evaluating Nexus for regulated environments
• Operators who need to understand how components interact
• Technical decision-makers reviewing architectural tradeoffs

Nexus is built as Rust microservices on an open-source data plane (Postgres, ClickHouse, S3-compatible storage, NATS, Redis). This section covers:

• How requests flow through the gateway, policy engine, and provider routing
• The multi-tenant identity model (workspaces, organizations, projects)
• How tamper-evident audit chains provide cryptographic proof of activity
• The policy decision point and how obligations are enforced
• Key architectural decisions recorded as ADRs (Architecture Decision Records)
• Technical terminology and concepts used throughout the codebase

If you’re new to Nexus internals, start with Architecture Overview for the big picture, then explore specific topics based on your interests.

#	Topic	Description
0000	Record architectural decisions as ADRs	Establishes MADR 3.0 Architecture Decision Records (ADRs) as the required format for documenting architectural choices, preventing the undocumented schema churn seen in reference implementations like Helicone.
0001	Rust microservices with axum + tonic for backend	Chooses Rust with axum for HTTP and tonic for gRPC as the backend language for all Nexus services, ensuring memory safety, FIPS compatibility, and shared-crate alignment with Aegis.
0002	Next.js App Router for the tenant console	Adopts Next.js with App Router and BFF API routes for the tenant console, keeping session tokens server-side and providing a single enforcement point for backend access.
0003	ClickHouse for tenant analytics (Tier 1 telemetry)	Selects ClickHouse as the dedicated analytics store for high-volume request telemetry, separating columnar analytical workloads from transactional Postgres control-plane state.
0004	OTLP for system telemetry (Tier 2)	Establishes OpenTelemetry Protocol (OTLP) for operator telemetry, maintaining a hard privacy boundary between tenant analytics (Tier 1) and system observability (Tier 2).
0005	OpenAI-compatible API as the gateway contract	Adopts OpenAI-compatible REST + SSE as the canonical gateway edge, enabling base_url swap compatibility with existing SDKs and tools while supporting provider-specific features through escape hatches.
0006	Two-phase BYOK-then-PTB attempt routing	Establishes two-phase routing that attempts BYOK credentials first, then PTB platform credentials only when explicitly enabled, maintaining clear billing boundaries and preventing surprise operator spend.
0007	Tamper-evident audit via per-tenant Merkle chains	Implements per-tenant Merkle chains with signed batch roots and WORM object storage anchors, enabling offline verification of audit events without trusting mutable database state.
0008	Data classification as a first-class request header	Introduces nexus-classification header with scope-configured vocabularies, enabling tenant-specific sensitivity taxonomies while keeping classification visible to policy evaluation and audit.
0010	NATS JetStream as the internal async event bus	Adopts NATS JetStream for async event delivery between services, decoupling gateway hot path from analytics/audit persistence with at-least-once delivery and tenant-scoped subject hierarchies.
0011	Apache 2.0 license policy and third-party license allowlist	Establishes Apache 2.0 as the project license with a strict allowlist for third-party dependencies, ensuring customer-friendly distribution rights and compatibility with air-gap deployments.
0016	Postgres-backed wallet escrows	Implements Postgres-backed wallet escrow system with row-level locking for PTB spend reservation, ensuring financial consistency under concurrent requests while supporting in-memory testing.
0017	Retry policy for gateway upstream attempts	Establishes header-driven retry budget per request with exponential backoff, enabling tenant-controllable retry behavior that composes with multi-provider fallback without duplicating streamed responses.
0018	Nexus-native agentic tracing	Implements Nexus-native trace backend with OpenTelemetry/OpenInference boundary compatibility, providing rich agent execution trees while preserving tenant data scoping and policy-governed payload capture.
0019	Deployment-wide OIDC federated sign-in	Adopts openidconnect crate with env-driven providers for deployment-wide SSO, enabling Google Workspace and Microsoft Entra ID authentication while reusing existing identity and session primitives.
0020	Narrow license allowlist additions for runtime data	Extends the license allowlist to include Unicode-3.0, 0BSD, CC-BY-4.0, and scoped CDLA-Permissive-2.0 for standard dependency stacks while maintaining strict copyleft and source-available prohibitions.
0021	FIPS build support behind a cargo feature	Implements optional FIPS 140-3 crypto support via cargo feature with mandatory boot self-check, enabling regulated deployments while keeping standard builds and musl-static images unchanged.