Architecture

Athena’s public API is a single HTTP server. Requests pass through three layers — auth, rate limiting, and the workflow engine — before producing a response.

---

System Components

Component	Role
API Server	HTTP server — auth, rate limiting, routing, request validation
Workflow Engine	BFS state-graph executor — drives every agent execution
Intelligence Service	LLM dispatch — 15 providers, circuit breaker, fallback, prompt caching
Credit System	Three-bucket ledger (active / frozen / inactive) — pre-deduct before LLM calls, reconcile after
File Storage	S3-compatible — signed URLs, multipart uploads, thumbnails
Worker	Background jobs — media generation recovery, stale execution cleanup
Primary datastore	Durable storage for agents, executions, conversations, knowledge embeddings, and cold checkpoints
Cache layer	Hot path — auth tokens, rate-limit counters, execution checkpoints, pub/sub for streaming

---

Request Pipeline

Every agent execution passes through three layers:

API Handler
  → rate_limit_middleware  (per-agent / per-customer / per-workspace)
  → auth_middleware        (JWT / API key → workspace context)
  → workspace_middleware   (workspace resolution + capabilities)
  ↓
ExecutionService
  → credit pre-check
  → execution record created
  ↓
WorkflowEngine  (BFS loop over node queue)
  → enforce_budget (token + cost caps)
  → credit_pre_deduct per AI node
  → execute_node (dispatches to node type handler)
  → credit_reconcile after AI node
  → checkpoint after every node
  ↓
IntelligenceService  (per AI node)
  → CircuitBreaker.should_allow(provider)
  → LLM call
  → hooks: tracing, cost tracking, rate-limit check, tool policy
  → fallback if 429 / 5xx and node has fallback configured

---

Execution States

State	Trigger
Queued	Record created before engine starts
Running	Engine loop started
Completed	BFS queue drained
Failed	Timeout, budget exceeded, or unrecoverable error
AwaitingApproval	HumanGate node paused — waiting for a human decision
WaitingForExternalEvent	MediaGeneration node submitted — waiting for Fal.ai webhook
AwaitingClientTool	LLM emitted a client tool call — waiting for your app to fulfil
Cancelled	Cancelled via API

---

Workflow Node Types

The engine supports 11 node types:

Node	Purpose
Trigger	Entry point — emits initial parameters
Ai (LLM)	LLM call — streaming or sync, with output-schema validation retry
Router	Branch selection — rules, round-robin, random, or LLM-based
Parallel	Fan-out — run sub-graphs concurrently under a semaphore
Join	Merge parallel results — concat, select_best, aggregate, llm_judge
Memory	Recall (hybrid retrieval) or Learn (async episode queue)
HumanGate	Human-in-the-Loop pause — execution resumes on decision
Action	HTTP / webhook call with SSRF protection
AgentInvocation	Nested agent execution (max depth 3)
Logic	Conditionals, loops, variable mutation, schema validation
MediaGeneration	Fal.ai image/video generation — async, resumes via webhook

---

LLM Providers

All 15 providers are routed through a single dispatch layer with per-provider circuit breaking and per-node fallback.

Provider	Modalities
OpenAI	chat, vision, tools, streaming
Anthropic	chat, vision, tools, streaming, prompt caching
Google (Gemini)	chat, vision, tools, streaming
Groq	chat, tools, streaming
Cohere	chat, tools, streaming
Perplexity	chat, streaming
xAI (Grok)	chat, tools, streaming
OpenRouter	chat, tools, streaming (model-dependent)
DeepSeek	chat, reasoning, tools, streaming
Mistral	chat, tools, streaming
MiniMax	chat, tools, streaming
Moonshot (Kimi)	chat, tools, streaming
ZAi (GLM)	chat, tools, streaming
XiaomiMimo	chat, tools, streaming
Fal.ai	media generation only

Note

Provider API keys are stored as workspace secrets. They are resolved at execution time and never returned via the API or written to logs.

---

Auth Model

Token type	Prefix	Lifetime	Use
Access token	— (JWT)	1 hour	Browser sessions
Refresh token	— (JWT)	30 days	Single-use rotation
Workspace API key	wak_	Long-lived	Server-to-server
Ephemeral API key	eak_	1 min – 24 h	Client-side, agent-scoped

Key lookup order in middleware:

1. Authorization: Bearer <JWT> — user session
2. X-API-Key: wak_... or X-API-Key: eak_... — API key path

SHA-256 hashes are stored. The raw key is returned once at creation.

---

Data Model

Table	Tenant	Key relationship
workspace	—	root tenant
user	—	platform account
agent	workspace	has inline workflow JSON
execution	workspace	belongs to agent + optional external customer
conversation	workspace	optional scope for executions
external_customer	workspace	your end-user, owns credit ledger
credit_transaction	workspace	per-deduct / reconcile / grant rows

The workspace is the isolation boundary. Nearly every table carries workspace_id. Soft-deletes use deleted_at.

---

Checkpointing

Tier	Store	TTL	Compression
Hot	Cache layer	24 hours	zstd-3
Cold	Primary datastore	30 days	—

On resume, the hot checkpoint is tried first. Cold is the fallback.

---

Related Docs

• Workflows — BFS loop, node types, and execution limits
• Intelligence — provider matrix, circuit breaker, fallback
• Credits — three-bucket ledger, RevenueCat integration, plan-change proration
• Integrate: Execute — execution endpoints for client apps