Architecture Guide Map

Athena’s root docs/ folder contains the deep technical write-ups behind the platform. This page mirrors those files inside the docs app and explains what each guide covers, who should read it, and when it becomes relevant.

How to use this page

• Start with the overview and end-to-end guides if you are new to Athena.
• Jump to the subsystem-specific guides when debugging one slice of the system.
• Use the operations and observability guides during incidents, performance work, and production hardening.

Core system narratives

docs/architecture_overview.md

The shortest introduction to Athena’s architecture. Read this first if you need the high-level mental model before going deeper.

docs/architecture_internals_end_to_end.md

The full boot-to-request narrative: startup, AppState, HTTP server wiring, routing, drivers, and background workers. This is the best single file for onboarding engineers who need to understand how Athena behaves as a running system.

docs/architecture_unified_all.md

A broad cross-cutting architecture summary that ties multiple subsystems together. Useful when you need to understand how independent concerns interact, rather than focusing on one module.

docs/architecture_layered_core.md

Explains Athena’s internal layering and boundary expectations. Read this when refactoring or introducing new core modules so you preserve separation between API, data access, and operational concerns.

Gateway and query execution

docs/architecture_gateway_routing.md

Describes how Athena resolves X-Athena-Client, wildcard hosts, JDBC overrides, and Supabase header overrides. This is the routing-source-of-truth document for request targeting.

docs/architecture_gateway_query_bundler.md

Explains query bundling behavior and execution-shape decisions for gateway requests. Useful when optimizing handler overhead or reducing duplicated backend round-trips.

docs/architecture_gateway_execution_windows_draft.md

Documents the execution-window concept for insert batching and pacing. Treat this as design context for the insert-window subsystem and future performance work.

docs/architecture_pipeline_etl.md

Explains the source → transform → sink pipeline engine and how it reuses gateway primitives. Read this when working on pipelines, simulation mode, or step logging.

docs/architecture_websocket_and_cdc.md

Documents the WebSocket and CDC model, including the /wss surface and change-stream-related behavior. Best for contributors touching real-time transport or the CDC server.

Clients, config, and runtime state

docs/architecture_client_registry_and_pooling.md

Explains how file-backed and database-backed client definitions merge into the runtime registry, and how SQLx pools are created and reused. This is essential for debugging “client not found”, connection lifecycle, and pool-resolution issues.

docs/architecture_cache_and_invalidation.md

Documents in-memory caching, optional Redis write-through, and invalidation windows. Use this when tracking stale reads, cache misses, or write/read coordination.

docs/architecture_auth_and_tenant_context.md

Explains API key enforcement, tenant/client scoping, and request context propagation. This is the right guide for auth failures, rights mismatches, and tenant-bound routing behavior.

docs/architecture_deployment_and_runtime.md

Focuses on process startup, configuration loading, environment overrides, and production runtime assumptions. Read this when deploying Athena or debugging environment-specific behavior.

Deferred execution, admission, and resilience

docs/architecture_deferred_and_admission.md

Explains the admission limiter, deferred queue, persistence model, and retry/defer decisions. This is the primary reference for deferred execution and request shedding behavior.

docs/architecture_gateway_pool_starvation.md

Describes how shared logging/auth pools can saturate under bursty telemetry and lock contention, surfacing as 503s or auth timeouts. Read this during incidents involving pool timed out while waiting for an open connection.

docs/architecture_gateway_client_stats_batcher.md

Explains the client_statistics batcher, the shared logging-task limiter, and the trade-offs used to keep telemetry from monopolizing the logging pool. This is the companion guide to pool-starvation investigations.

Observability, tooling, and operators

docs/architecture_observability_and_audit.md

Documents request logs, operation logs, metrics, audit-style operational records, and how operators correlate them. Useful when building dashboards, alerts, or forensic workflows.

docs/architecture_frontend_and_tools.md

Explains the Web Explorer, CLI helpers, docs tooling, and related developer/operator UX layers. Read this when changing the front-end or auxiliary toolchain.

Suggested reading paths

New contributor path

1. docs/architecture_overview.md
2. docs/architecture_internals_end_to_end.md
3. docs/architecture_layered_core.md
4. docs/architecture_client_registry_and_pooling.md

Performance / incident path

1. docs/architecture_gateway_pool_starvation.md
2. docs/architecture_gateway_client_stats_batcher.md
3. docs/architecture_cache_and_invalidation.md
4. docs/architecture_observability_and_audit.md

Platform extension path

1. docs/architecture_gateway_routing.md
2. docs/architecture_pipeline_etl.md
3. docs/architecture_deferred_and_admission.md
4. docs/architecture_websocket_and_cdc.md

Related docs-app pages

• platform/architecture for the shorter platform summary
• reference/configuration-options for the full runtime and environment reference
• reference/documentation-status for docs coverage and verification workflow