Technical Reference

This section is for developers who want to understand how Aira works under the hood, evaluate the architecture, or self-host the backend.

What aira-agent is

aira-agent is the open-source backend service that powers Aira. It's a Python application built on:

FastAPI — Async HTTP framework, 45+ route modules under /api/v1
LangGraph — Stateful multi-agent orchestration (2 graphs: main pipeline + quality gate)
PostgreSQL 16 — The only datastore. No Redis, no BigQuery, no graph database.
SQLAlchemy — Async ORM with 32+ database models
Pydantic — Request/response validation and structured LLM outputs
asyncpg — Async PostgreSQL driver

Codebase stats: ~40,000 lines of Python, 32 DB models, 45+ API route modules, 6 agents, 32 assistant tools, 16+ Alembic migrations.

aira-web vs aira-agent

Component	Role	Open source
aira-agent	Backend: API, agents, knowledge ledger, database	Yes
aira-web	Frontend: Next.js app + API proxy layer	Private

The browser never communicates with aira-agent directly. All traffic flows through the Next.js proxy:

Browser → Next.js (app.aira.pro) → API proxy → FastAPI (aira-agent) → PostgreSQL

High-level architecture

flowchart TD
    subgraph CLIENTS["Clients"]
        A["Next.js Web App<br/>(app.aira.pro)"]
        B["Slack / Telegram<br/>(webhooks)"]
        C["MCP Clients<br/>(Claude, ChatGPT)"]
    end

    subgraph FASTAPI["FastAPI Application — Port 8000"]
        D["Auth Layer<br/>JWT · API Keys · Passkeys"]
        subgraph ROUTES["45+ Route Modules"]
            E["/chat · /sources · /features<br/>/tasks · /knowledge · /mcp<br/>... and 40 more"]
        end
        F["Background Workers<br/>Heartbeat · Webhooks · Notifications"]
    end

    subgraph PIPELINE["LangGraph Agent Pipeline"]
        G["Supervisor (Router)"]
        H["Analyst"]
        I["Planner"]
        J["Assigner"]
        K["Reporter"]
        L["Assistant<br/>ReAct · 32 tools"]
        G --> H & I & J & K & L
        H & I & J & K & L -->|requires_review| G
    end

    subgraph QG["Quality Gate Graph (separate LangGraph)"]
        M["Init"] --> N["Evaluator"]
        N -->|pass| O(["END"])
        N -->|fail| P["Reviser"]
        P --> N
    end

    PG["PostgreSQL 16<br/>32+ tables · JSONB · asyncpg"]
    CT["Cost Tracking & LLM Registry<br/>Anthropic · OpenAI · xAI · Groq · Fallbacks"]

    CLIENTS -->|"HTTPS REST + SSE<br/>Webhooks<br/>MCP/HTTP"| FASTAPI
    FASTAPI --> PIPELINE
    FASTAPI --> QG
    FASTAPI --> PG
    PIPELINE --> PG
    QG --> PG
    PIPELINE --> CT

Key technology choices

Choice	Why
PostgreSQL only	One datastore to operate. JSONB for flexible fields, full-text search for retrieval, advisory locks for concurrency. No Redis, no BigQuery, no graph DB.
LangGraph for multi-agent	Stateful graph execution with conditional routing. Each `ainvoke()` creates isolated state — the compiled graph is a thread-safe blueprint.
Structured outputs, not markdown parsing	Agents return Pydantic models via `with_structured_output()`. No regex, no markdown parsing, no brittle extraction.
asyncpg for async DB	Non-blocking I/O matches FastAPI's async model. Concurrent graph runs share the event loop.
SSE for streaming	Unidirectional server→client. Works through all proxies and CDNs. Auto-reconnect built into the browser API.
API-layer tools	The assistant's tools call REST endpoints via httpx (localhost), not the DB directly. Every tool operation goes through validation, auth, and event logging.

Guides

Agentic Flow — Start here. The full end-to-end flow: how sources become atoms, how atoms become artifacts, the iterative generation loop, the quality gate, the continuous intelligence loop, and the Team Ledger. Grounded in the actual implementation.
Agent Pipeline — The LangGraph multi-agent system in detail
Knowledge Ledger — The Project Knowledge Ledger architecture
Self-Hosting — Running aira-agent yourself (includes local Ollama setup)
API Reference — Key API endpoints
Agentic Principles — Design philosophy