# airweave-ai/airweave architecture

> Architecture diagram of the GitHub repository airweave-ai/airweave, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/airweave-ai/airweave
- Repository: https://github.com/airweave-ai/airweave

## Overview

##### Project Type and Purpose
- Airweave is a self-hosted, full-stack context-retrieval platform for AI agents.
- It comprises:
- A React/TypeScript frontend (dashboard/UI)
- A FastAPI Python backend (REST API + business logic)
- Supporting microservices/workers (Temporal workflows, Redis pub/sub)
- Data stores (PostgreSQL for metadata, Qdrant for vector embeddings)
- An optional MCP server (Node.js) and a connector toolkit (Monke)

##### High-Level Architecture Components
a. Frontend
- React/TypeScript app served via Docker (port 8080)
- Connects to backend REST API for user actions, visualization, and live API docs
b. Backend API
- FastAPI service (port 8001)
- Exposes v1 endpoints: collections, source connections, sync, search, billing, auth
- Implements business logic layers (core/, crud/, schemas/, search/, billing/, analytics/)
c. Worker/Orchestration Layer
- Temporal workers execute long-running sync workflows
- Redis for pub/sub (sync triggers, rate limiting, context caching)
d. Data Stores
- PostgreSQL: metadata tables (collections, users, auth, sync jobs) managed via Alembic
- Qdrant: vector store for semantic embeddings
e. External Integrations
- “platform/sources” connectors for 30+ apps (Slack, GitHub, Google Drive, etc.)
- “integrations” clients (Stripe, Auth0)
- Entity extraction, chunking, embedding using embedders (OpenAI, FastEmbed)
f. SDKs & MCP
- Python/TS SDKs wrap REST calls
- MCP microservice (Node.js) offers an alternative GraphQL-like interface
g. Monke
- Connector-generation CLI/framework (Python + its own frontend/backend)

##### Interactions and Data Flow
1. User → Frontend (HTTP) → Backend API
2. Backend API → PostgreSQL (CRUD) for metadata
3. Backend API triggers syncs → Redis pub/sub → Temporal workflows
4. Workflows fetch data via connectors → chunk/transform → embed → store in Qdrant
5. User/API queries → Backend search service → Qdrant ● optional reranking → return results
6. SDKs or MCP server also consume the same API or directly interface with the backend

##### Architectural Patterns & Principles
- Layered architecture: UI / API / Business Logic / Data Access / Storage
- Micro-worker pattern: Temporal + Redis for async/background tasks
- Pluggable connectors: strategy pattern for sources, embedders, destinations
- Multi-tenant via OAuth2, API keys, and per-collection isolation
- Incremental sync via cursors, hashing, rate limiting

##### Elements
- Clear labels: service names, ports, DB types

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User
    User["User"]:::external

    %% Frontend
    Frontend["Frontend UI<br/>(React/TS)"]:::service

    %% Backend API and Business Logic
    BackendAPI["Backend API<br/>(FastAPI)"]:::service
    subgraph "Business Logic"
        CoreBL["Core"]:::service
        CrudBL["CRUD"]:::service
        SchemasBL["Schemas"]:::service
        SearchBL["Search"]:::service
        BillingBL["Billing"]:::service
        AnalyticsBL["Analytics"]:::service
    end

    %% Worker/Orchestration
    subgraph "Workers/Orchestration"
        PubCore["Core Pub/Sub"]:::worker
        PubSync["Sync Pub/Sub"]:::worker
        Temporal["Temporal Workflows"]:::worker
    end

    %% Data Stores
    Postgres["PostgreSQL<br/>Metadata"]:::db
    Redis["Redis<br/>Pub/Sub"]:::db
    Qdrant["Qdrant<br/>Vector Store"]:::db

    %% External Integrations & Connectors
    Integrations["Integrations<br/>(Stripe, Auth0)"]:::service
    Connectors["30+ Connectors"]:::service

    %% SDK & MCP & Monke
    SDK["SDKs (Python/TS)"]:::external
    MCP["MCP Server<br/>(Node.js)"]:::service
    Monke["Monke Toolkit"]:::service

    %% Connections
    User -->|"HTTP 8080"| Frontend
    Frontend -->|"HTTP 8001"| BackendAPI

    BackendAPI --> CoreBL
    BackendAPI --> CrudBL
    BackendAPI --> SchemasBL
    BackendAPI --> SearchBL
    BackendAPI --> BillingBL
    BackendAPI --> AnalyticsBL

    BackendAPI -->|"CRUD"| Postgres
    BackendAPI -->|"Pub/Sub"| Redis
    Redis -->|"gRPC"| Temporal
    BackendAPI -->|"invoke connectors"| Connectors
    Connectors -->|"data fetch"| Temporal
    Temporal -->|"store embeddings"| Qdrant

    BackendAPI --> Integrations
    SDK -->|"REST API"| BackendAPI
    MCP -->|"REST API"| BackendAPI
    Monke -->|"CLI"| Connectors

    %% Click Events
    click Frontend "https://github.com/airweave-ai/airweave/tree/main/frontend/"
    click BackendAPI "https://github.com/airweave-ai/airweave/tree/main/backend/airweave/api/"
    click CoreBL "https://github.com/airweave-ai/airweave/tree/main/backend/airweave/core/"
    click CrudBL "https://github.com/airweave-ai/airweave/tree/main/backend/airweave/crud/"
    click SchemasBL "https://github.com/airweave-ai/airweave/tree/main/backend/airweave/schemas/"
    click SearchBL "https://github.com/airweave-ai/airweave/tree/main/backend/airweave/search/"
    click BillingBL "https://github.com/airweave-ai/airweave/tree/main/backend/airweave/billing/"
    click AnalyticsBL "https://github.com/airweave-ai/airweave/tree/main/backend/airweave/analytics/"
    click PubCore "https://github.com/airweave-ai/airweave/blob/main/backend/airweave/core/pubsub.py"
    click PubSync "https://github.com/airweave-ai/airweave/blob/main/backend/airweave/platform/sync/pubsub.py"
    click Temporal "https://github.com/airweave-ai/airweave/tree/main/backend/airweave/platform/temporal/"
    click Redis "https://github.com/airweave-ai/airweave/blob/main/backend/airweave/core/redis_client.py"
    click Postgres "https://github.com/airweave-ai/airweave/tree/main/backend/airweave/db/"
    click Qdrant "https://github.com/airweave-ai/airweave/blob/main/backend/airweave/platform/destinations/qdrant.py"
    click Integrations "https://github.com/airweave-ai/airweave/tree/main/backend/airweave/integrations/"
    click Connectors "https://github.com/airweave-ai/airweave/tree/main/backend/airweave/platform/sources/"
    click MCP "https://github.com/airweave-ai/airweave/tree/main/mcp/"
    click Monke "https://github.com/airweave-ai/airweave/tree/main/monke/"

    %% Styles
    classDef service fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef db fill:#90EE90,stroke:#333,stroke-width:1px,shape:cylinder;
    classDef worker fill:#FFA500,stroke:#333,stroke-width:1px,shape:hexagon;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
