Technical Philosophy

1. The Principle of Least Astonishment

Design the system so that the behavior is the one that most users will expect.

Aurora sits between clients and providers that speak different dialects of the same API. The same request body might need to reach Anthropic, an OpenAI-compatible host, or an Azure deployment — each with slightly different field names, header requirements, and response shapes. The gateway absorbs that complexity so the client's expectations are always met.

This is not abstract. Every provider integration in the codebase follows the same pattern:

Predictable behavior

• Consistent interface. A request with max_tokens for a reasoning model gets the field transparently renamed to max_completion_tokens on the upstream call. The client never changes. See Chat Completions.
• Header normalization. Whether the upstream wants anthropic-version, OpenAI-Organization, or custom provider headers, Aurora absorbs those differences. The client sends standard OpenAI headers and gets standard results back.
• Unified response shape. What comes back to the client is always a clean OpenAI or Anthropic shape, never a hybrid. The client is never surprised by a response format that differs from the one it requested.

Clarity in operation

• No magic. The same field name does the same thing on the way in and the way out. If you set a token budget, it applies exactly as described in the documentation.
• Fail fast, fail clear. If a provider drops an unsupported parameter or returns a malformed response, Aurora catches it early. The error reported back to the user is clear, actionable, and reflects what actually happened, rather than a generic upstream failure.
• Stable abstractions. Switching model providers, adding pools, or turning on guardrails never changes the client-side code. The gateway does the work to keep the interface stable, so your application code stays clean and predictable.

2. Good defaults

A gateway should be useful with minimal setup. If a user has to read a 200-page manual before they can call /v1/chat/completions, the gateway has failed.

How the defaults are designed:

• OpenAI-shape on the wire. Every provider gets translated to OpenAI or Anthropic. The client side is always the same.
• SQLite by default. No database to install for local development. The same binary works on a laptop and in a 100-node cluster.
• No auth required by default. The master key is empty until you set AURORA_MASTER_KEY; the admin UI is on but unauthenticated. The first thing a new user sees is a working gateway, not a login wall.
• Discoverable providers. Set OPENAI_API_KEY and an OpenAI provider appears. Set ANTHROPIC_API_KEY and an Anthropic provider appears. The model list is the union.
• Sensible-but-not-aggressive cache. The exact response cache is off by default (so first-time users do not see "why am I getting a stale response"). Turn it on with one env var when you want it. See Cache.
• Token budget by default. USAGE_ENABLED=true is on from the start. The dashboard Usage page is useful on day one.

Configuration is not a maze. The Configuration page is the full reference; the Quick Start gets you to a working request without reading it.

3. Peter Parker Principle

With great power comes great responsibility.

Operating an AI gateway means every request that passes through is an opportunity for something to go wrong — a misrouted request, a leaked credential, a budget blown on a runaway loop. The gateway has to make the right thing the easy thing for operators, not the other way around.

What this looks like in code:

• Secure by default where it matters. The master key is empty by default so new users can start without friction, but the admin API enforces authentication once you set it. Provider keys in transit and at rest are masked in logs, never exposed in error messages, and never serialized into debug dumps. See Security.
• Budget enforcement is baked in. Usage tracking, token budgets, and per-scope rate limits are first-class features — not afterthoughts. If the gateway is responsible for preventing cost surprises, it needs the tools to do so. See Usage & Budgets.
• Logging is audit-grade. Every request, every cache hit, every guardrail intervention — structured, timestamped, and attributable. When something goes wrong, the log is the source of truth, not a developer's memory. See Observability.
• Defaults that protect the operator. Caching is off by default to prevent stale-response surprises. Token budgets are on by default. Workflows default to passthrough. Every toggle is deliberate: you turn features on when you understand what they do.

What this means for operators

• Local dev matches prod. What you run on your laptop is the same binary that runs in your cluster. The differences are config and persistence, not runtime.
• Stateless is enforced. No background queues, no in-process caches you have to drain, no warmup ritual. Restart and the gateway is back.
• Config is portable. A config.yaml from dev works in staging works in prod. Override only what differs.
• Auditable by default. Every request, every decision, every intervention is logged. If you are responsible for the gateway, you have the data to explain what it did.

What this means for users

• One OpenAI-shaped client forever. Switching model providers, adding pools, turning on guardrails — none of it changes the client code. The gateway does the work.
• No magic. The same field name does the same thing on the way in and the way out. The same response header means the same thing. The same env var toggles the same feature.

Related

• Who We Are — the team and community
• Our Values — the values that drive these decisions
• Configuration — the full env-var reference
• Architecture — how the codebase is organized