Contributing / Contributing

Architecture

Aurora's architecture � dependency wiring, request flow, and design decisions.

Browse docs

Aurora follows a clean layered architecture with clear separation of concerns.

Diagram

HTTP Server � Echo framework handles routing, middleware, and HTTP lifecycle
Middleware Stack � Auth, model validation, workflow resolution, audit logging, caching
Handler � Route-specific business logic (chat completions, embeddings, etc.)
Gateway Orchestrator � Coordinates provider selection, request translation, retries, fallbacks
Provider Layer � Provider-specific implementations (OpenAI, Anthropic, Ollama, etc.)
Upstream � External AI provider API

Diagram

Postel's Law � Be conservative in what you send, liberal in what you accept
Twelve-Factor App � Config via environment, stateless processes, disposability
Good Defaults � Sensible defaults that work out of the box

Package	Responsibility
`internal/server`	HTTP handlers, middleware, routing
`internal/core`	Domain types, canonical JSON codecs, carrier context
`internal/gateway`	Request orchestration, workflow execution
`internal/providers`	Provider registry, routing, OpenAI/Anthropic implementations
`internal/httpclient`	HTTP client factory with connection pooling
`internal/auditlog`	Audit logging and request snapshots
`internal/cache`	Response caching (exact + semantic)

Architecture Decision Records (ADRs) document key design decisions:

Contributing / Contributing

Aurora's architecture � dependency wiring, request flow, and design decisions.

Browse docs

Aurora follows a clean layered architecture with clear separation of concerns.

Diagram

HTTP Server � Echo framework handles routing, middleware, and HTTP lifecycle
Middleware Stack � Auth, model validation, workflow resolution, audit logging, caching
Handler � Route-specific business logic (chat completions, embeddings, etc.)
Gateway Orchestrator � Coordinates provider selection, request translation, retries, fallbacks
Provider Layer � Provider-specific implementations (OpenAI, Anthropic, Ollama, etc.)
Upstream � External AI provider API

Diagram

Postel's Law � Be conservative in what you send, liberal in what you accept
Twelve-Factor App � Config via environment, stateless processes, disposability
Good Defaults � Sensible defaults that work out of the box

Package	Responsibility
`internal/server`	HTTP handlers, middleware, routing
`internal/core`	Domain types, canonical JSON codecs, carrier context
`internal/gateway`	Request orchestration, workflow execution
`internal/providers`	Provider registry, routing, OpenAI/Anthropic implementations
`internal/httpclient`	HTTP client factory with connection pooling
`internal/auditlog`	Audit logging and request snapshots
`internal/cache`	Response caching (exact + semantic)

Architecture Decision Records (ADRs) document key design decisions: