Product architecture

Agent Access Manager is one deployable — a modular monolith with enforced module boundaries — in front of PostgreSQL, with optional OpenSearch, Valkey, and AI sidecars switched on by edition. This page explains the four ideas that make the rest of the docs make sense.

The big picture

                          ┌────────────────────────────────────────────────┐
  Application ──sk-key──▶ │  DATA PLANE   /v1/chat/completions /v1/messages │
                          │  auth → budget gate → guardrails → routing      │──▶ OpenAI
                          │       → provider adapter → screen → audit       │──▶ Anthropic
                          ├────────────────────────────────────────────────┤──▶ Gemini / Vertex
  Admin ──SSO/Basic─────▶ │  ADMIN PLANE  /admin/** + dashboard             │──▶ Ollama / vLLM /
                          │  orgs · keys · catalog · budgets · guardrails   │     anything OpenAI-
                          │  rate limits · usage · reports · SIEM · SOAR    │     compatible
                          └───────┬───────────────┬───────────────┬────────┘
                             PostgreSQL      OpenSearch        Valkey
                          (system of record) (SIEM + audit,  (counters +
                                              Pro and up)     broadcasts,
                                                              Distributed)

Idea 1 — the canonical pivot (N + M, not N × M)

The OpenAI chat shape is the single internal interchange format. Each inbound surface (/v1/chat/completions, /v1/responses, /v1/messages, /v1/embeddings) maps the client's format to canonical; each outbound adapter maps canonical to a vendor's wire format. So supporting N client formats and M vendors costs N + M adapters, not N × M translations.

A provider's protocol selects the outbound adapter:

When the inbound format matches the upstream's native wire (an Anthropic-shaped request to an Anthropic deployment, an OpenAI Responses request to an OpenAI deployment), the body is relayed verbatim — which is why tools like Codex and Claude Code work unchanged. Cross-format requests are translated through the canonical shape, so any client format can be served by any backend. Details in Gateway API.

Idea 2 — one pipeline governs everything

Every data-plane request, whatever its surface, runs the same sequence:

1. Authenticate — resolve the virtual key (SHA-256 lookup) to its principal and scope chain.
2. Budget gate — check accumulated spend and rate limits at every scope level; deny with 429 before any vendor is called.
3. Request guardrails — extract the prompt text and screen it; allow, flag, redact, or block per policy.
4. Route — resolve the alias to candidate deployments, order them (load balancing, health, per-deployment budget headroom), and try them in order with fallback.
5. Execute — the provider adapter injects the decrypted vendor credential and makes the call. Applications never hold real provider keys, so every request is meterable by construction.
6. Response guardrails — screen the model's output, inline for streams.
7. Audit — read token usage from the response (including cached-token breakdowns), compute cost from deployment pricing, and record the call.

Idea 3 — governance is event-driven

Every proxied call publishes a durable event — written transactionally with the work via an outbox, so an audit record can never be lost — and every governance feature is a consumer of that one stream:

Consumers run off the hot path: a slow analytics query or an OpenSearch outage adds zero latency to the call your application made. It is also why Audit & usage, Budgets, Reports, and SIEM always agree — they read the same stream.

Idea 4 — storage follows the tier

The modules

The application is split into modules with enforced boundaries; each admin feature you see in the dashboard corresponds to one:

• gateway — the data plane: inbound surfaces over the shared pipeline.
• providers — outbound vendor adapters on a shared retry-aware HTTP client.
• routing — orders candidate deployments; a per-deployment circuit breaker cools failing backends and retries them as half-open probes.
• iam — virtual keys, the data-plane auth filter, and the admin security chains (Basic, OIDC Bearer, browser session/SSO).
• directory — organizations, teams, projects, memberships, invitations, and the role/capability model.
• catalog — per-org providers, deployments, aliases, encrypted credentials, and pricing.
• guardrails — detectors (pattern and AI-classifier) plus scoped, directional policies.
• billing — budgets and RPM/TPM rate limits across the scope chain.
• analytics — consumes call events into the audit store and serves the usage/spend/activity queries.
• notifications — email, HMAC-signed webhooks, and in-app alerts routed off the event stream.
• reports — on-demand and scheduled reports rendered to HTML/CSV/JSON/PDF via the object store.
• siem / soar — the opt-in OpenSearch projection, detections, Sigma rules, UEBA, and automated containment.

Security posture in one paragraph

Vendor master keys are AES-256-GCM encrypted at rest under a master key generated at install time. Virtual keys are stored only as SHA-256 hashes and shown once. The admin plane is SSO-first: humans authenticate at your IdP, the gateway validates tokens (signature, issuer, expiry, audience) and holds no passwords; the local Basic admin remains as a break-glass credential. The dashboard is a session backend-for-frontend with CSRF protection. Everything an admin does is auditable as ConfigChanged events.

Related pages

• Routing & failover — how a request picks a vendor.
• Audit, usage & reports — the read side of the event stream.
• Scale from one box to a cluster — the stateless-data-plane payoff.