> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goantiai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Architecture

> How Oculus is architected, its infrastructure dependencies, and the operational constraints you need to know before deploying to production.

Oculus is built on a small set of infrastructure components. Understanding their roles — and their failure modes — is essential for a reliable production deployment.

## Components

**PostgreSQL** is the source of truth for all persistent state: agents, policies, tokens, audit logs, and tenant data. Row-Level Security (RLS) is enforced at the database layer so tenant data is isolated even if application-level checks are bypassed. Oculus currently requires a single primary Postgres instance. Read replicas are supported via `DATABASE_READ_URL` but writes always go to the primary. There is no built-in sharding or multi-primary support.

**Redis** is used for rate limiting (sliding window counters) and short-lived caches (dashboard metrics, token revocation propagation). Redis is treated as a best-effort dependency — if it is unavailable, rate limiting fails open (requests are allowed through). This is a deliberate availability trade-off. If you require strict rate limiting guarantees, ensure Redis is highly available.

**OPA (Open Policy Agent)** evaluates every token issuance and policy simulation request. Oculus pushes Rego policies to OPA via its REST API and queries it synchronously on the hot path. OPA must be reachable for token issuance to succeed. Run it as a sidecar container alongside the backend — the default `docker-compose.yml` includes this configuration.

**ARQ Worker** runs background jobs: credential expiry, billing resets, and audit chain verification. Without the worker running, these jobs silently do not execute. The `worker` service in `docker-compose.yml` points at `backend/app/worker.py` — ensure it is included in your deployment.

## Failure modes summary

| Component       | Failure behaviour                                             |
| --------------- | ------------------------------------------------------------- |
| Postgres down   | All API requests fail (503)                                   |
| Redis down      | Rate limiting fails open; caches stale or empty               |
| OPA down        | Token issuance fails; policy simulation unavailable           |
| ARQ worker down | Background jobs stop silently; no immediate user-facing error |

## Production checklist

* Set `DATABASE_URL` to a managed Postgres instance with automated backups
* Set `REDIS_URL` to a managed Redis instance (ElastiCache, Upstash, etc.)
* Run OPA as a sidecar — do not expose it publicly
* Run the ARQ worker as a separate process or container
* Set `OAUTH_SIGNING_KEY_PEM` to a persistent RSA key (not auto-generated per process)