/docs/architecture

Atlas Architecture

A governance and orchestration layer that controls how models access enterprise data -- enforcing policy, minimizing exposure, and producing audit trails.

Deployment:on-prem / private cloud / air-gapped

Auth:SAML / OIDC / LDAP

Observability:audit logs + metrics + traces

Integrations:Starfish, vLLM, Qdrant, OPA

System Layers

Clients

Web UICLIAPIAgents

Atlas Control Plane

AuthN/AuthZPolicy EngineRequest RouterRate LimitsAdmin Config

Atlas Data Plane

Retrieval OrchestratorCompliance TaggingRedaction/TransformsPrompt Builder

AI Runtime Layer

EmbeddingsVector DBLLM Inference

Data Sources

Starfish zones/collectionsFilesystemsObject StoresDBs

Observability

Immutable audit log streamMetricsTraces

request flow

Request Lifecycle

Every request follows a deterministic path through Atlas. No step is optional. If any stage fails, the request is rejected with a structured error and an audit event is emitted.

Client sends query + identity context

Request includes bearer token, tenant ID, and target collection scope. Wire format is JSON over mTLS.

Atlas authenticates via OIDC / SAML

Token validated against configured IdP. Session binding established. Failed auth returns 401 immediately.

Policy engine evaluates: user -> zone/collection -> allowed operations

OPA-compatible policy evaluation. Decision includes permission set, data classification ceiling, and operation whitelist. Decision ID assigned.

Retrieval orchestration selects approved collections only

Collection set filtered by policy decision. Denied collections are excluded before any vector search executes. No fallback to broader scope.

Vector search executed with filters (tags, sensitivity, tenancy)

Query embedding generated. Search runs against Qdrant with metadata filters enforced server-side. Results ranked and truncated to configured limit.

Context builder applies transforms

Redaction rules applied per classification tag. PII masking, field truncation, and citation injection. Output is the assembled prompt context.

Model gateway calls inference with enforced template + tool gating

Selected model receives prompt with system template. Tool/function calling gated by policy. Token budget enforced. Timeout applied.

Response streams back to client

Streaming response with server-sent events. Output filters applied inline. Response hash computed on completion.

Audit event emitted

Immutable record: query hash, retrieval set, policy decision ID, model ID, token count, latency, output hash, redaction flags.

Trust Boundaries

Inside Customer Environment

Atlas Control Plane + Data Plane

Vector DB (Qdrant)

Model Inference (vLLM / local)

Data Sources (Starfish, filesystems, DBs)

Audit Logs + Metrics Store

Policy Engine + Configuration

Secrets Store (Vault / K8s)

External

None by default

External model APIs (OpenAI, Anthropic, etc.) are supported but require explicit configuration per-zone. External connections are logged and subject to policy evaluation. No data leaves the environment without an auditable decision chain.

No data egress by default. External connections require explicit configuration, policy approval, and produce audit events on every call. Air-gapped deployments have no external network path.

Policy Model

Identity Binding

Identity

->Role

->Permission

Data Classification

GDPRPCICUIPIIHIPAAITARInternalPublic

Operation Controls

readretrievesummarizeexporttool-useagent-invoke

policy.rego

 1allow {
 2  input.user.role == "analyst"
 3  input.collection.id == "collection-a"
 4  input.operation in ["read", "retrieve", "summarize"]
 5  not input.document.tags["PCI-high"]
 6}
 7
 8allow {
 9  input.user.role == "legal"
10  input.zone.id == "zone-b"
11  input.operation == "agent-summarize"
12}
13
14deny {
15  input.model.id == "gpt-4"
16  input.zone.classification == "classified-research"
17}

Policies are evaluated on every request. No caching of authorization decisions across requests.

Failure Modes

Atlas defaults to closed on all failure paths. There is no degradation mode that silently bypasses policy or drops audit events.

Policy engine unavailable

Fail closed

All requests denied. No bypass. Alert fires to ops channel within 30s.

Vector DB degraded

Reduced retrieval + circuit breaker

Circuit breaker opens after configurable error threshold. Partial results returned with degraded flag. Automatic recovery probe.

Model overload

Queue, backpressure, rate limiting

Request queued with TTL. Per-tenant rate limits enforced. 429 returned when queue depth exceeds threshold. Priority lanes for critical tenants.

Audit sink unavailable

Buffer + alerts, fail closed

Audit events buffered to local WAL. If buffer fills, requests are rejected. No silent audit gaps.

Additional Safety Controls

Retry with exponential backoffIdempotency keys on all writesRequest IDs propagated end-to-endDistributed tracing via OpenTelemetryHealth check endpoints per componentGraceful shutdown with drain period

Deployment Topologies

Single-Node Dev

Atlas + embedded DB + local model

-SQLite for metadata, embedded Qdrant

-Local GGUF model via llama.cpp

-Self-signed TLS for local development

-Single binary distribution

-No external network dependencies

HA Production

Atlas replicas + external Postgres + Qdrant cluster + model pool

-Minimum 3 Atlas replicas behind load balancer

-Postgres with streaming replication

-Qdrant cluster with sharding + replicas

-vLLM model pool with health checks

-TLS termination at ingress, mTLS internal

-Secrets via Vault or K8s secrets

-Rolling upgrade with canary validation

Air-Gapped

Offline artifact distribution + local model hosting + no external connections

-OCI-compliant artifact bundle for offline install

-Local model weights, no download at runtime

-Internal CA for certificate management

-Upgrade via signed artifact transfer

-Rollback to previous version within 60s

-No DNS, NTP, or package manager calls

Operational Notes

TLS

All internal and external traffic encrypted. mTLS between Atlas components. Configurable cipher suites.

Secrets

Vault integration or K8s secrets. No secrets in environment variables or config files. Rotation without restart.

Upgrades

Rolling upgrades with automatic rollback on health check failure. Schema migrations are forward-compatible.

Audit Schema

Every request produces an immutable audit record. These records are append-only, tamper-evident, and exportable to external SIEM systems. The schema below covers the core fields emitted per request.

audit_event schema

field	type	description
request_id	uuid	Unique identifier for the request
timestamp	timestamptz	Server-side wall clock, UTC
user_id	text	Authenticated user principal
tenant_id	text	Tenant isolation boundary
policy_decision_id	uuid	Reference to evaluated policy decision
collection_ids	text[]	Collections accessed during retrieval
retrieved_doc_ids	text[]	SHA-256 hashes of retrieved documents
model_id	text	Model identifier + version string
token_count	integer	Total tokens consumed (prompt + completion)
latency_ms	integer	End-to-end request latency
output_hash	text	SHA-256 of complete model response
redaction_applied	boolean	Whether any redaction transform executed
redaction_types	text[]	Classification tags that triggered redaction

Retention period configurable per tenant. Default: 365 days. Exportable as JSON-lines or CEF.

Integration Points

Starfish

required

Zone/collection metadata ingest + manifest sync

Starfish provides the data organization layer. Atlas reads zone definitions, collection metadata, and classification manifests. Sync is pull-based on configurable interval.

Vector DB

required

Upsert / search / filter contract

OpenAPI-compatible vector operations. Primary support for Qdrant. Filter expressions enforce tenancy and classification at query time. Batch upsert for ingestion pipelines.

Inference

required

OpenAI-compatible API / vLLM endpoints

Chat completions and embeddings endpoints. vLLM for self-hosted models. Model registry tracks available models, versions, and capability tags.

Identity Provider

required

OIDC / SAML mapping

Standard OIDC discovery or SAML metadata import. Group-to-role mapping configurable via admin API. Supports multi-IdP for federated environments.

SIEM

optional

Audit export via syslog, webhook, or file

Structured audit events exported in CEF or JSON. Supports syslog (TCP/TLS), webhook POST, or local file rotation. Configurable export filters.

Policy Engine

optional

OPA-compatible policy evaluation

Built-in policy engine for standard RBAC. Optional OPA sidecar for complex Rego policies. Policy bundles versionable and auditable.

See Atlas in your environment

We deploy Atlas on your infrastructure, with your identity provider, against your data sources. No SaaS dependency. No data egress.

Request Demo Explore Atlas