Skip to main content

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.

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

ComponentFailure behaviour
Postgres downAll API requests fail (503)
Redis downRate limiting fails open; caches stale or empty
OPA downToken issuance fails; policy simulation unavailable
ARQ worker downBackground 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)