# superagent-ai/superagent architecture

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

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

## Overview

##### Project Type and Purpose
- This is a full-stack monorepo for “Superagent,” an open-source AI assistant framework and API.
- It provides:
- A Python backend microservice exposing REST endpoints for agents, workflows, memory, tools, vectorstores.
- A Next.js frontend dashboard/UI for user interaction, provisioning agents, viewing logs, billing.
- Infrastructure definitions (Docker Compose orchestrator) for databases, vector stores, observability, and the services themselves.
- API spec and docs generation via the `fern/` directory.
- Embeddable JavaScript SDK in `libs/embed/`.

##### File-Structure Analysis
- Top-level directories:
- `fern/` – API specification (OpenAPI, Fern IDL) and MDX-based documentation.
- `libs/.docker/` – docker-compose configs to spin up Supabase (Postgres), Redis, vectorstores (Weaviate), observability (Langfuse), backend, UI, etc.
- `libs/embed/` – embeddable JS client for Superagent.
- `libs/superagent/` – Python application (`app/`), ORM schema & migrations (`prisma/`), prompts, services, Dockerfile.
- `libs/ui/` – Next.js (app router) React frontend, server-side routes under `app/api`, Supabase migrations for auth, UI config for Stripe, SAML, theming, etc.
- Architectural patterns:
- Clean separation of concerns: frontend vs. backend vs. infra.
- Plugin-style modules under `app/tools/`, `app/vectorstores/`.
- Microservices/containers orchestrated by Docker Compose.
- API spec-as-code in `fern/` driving generators.

##### Key README Insights
- Features: REST API, memory (Redis, vectorstores), streaming, Python & TypeScript SDKs.
- Supports proprietary & open-source LLMs, third-party vector stores.
- Encourages self-hosted infrastructure via Docker Compose.

##### Detail Level
- Major directory/module as a component.
- Plugin buckets (`app/tools`, `app/vectorstores`) as collections within the backend.
- Don’t over-fragment—group related submodules under a single service block when possible.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UI["Next.js Frontend UI"]:::frontend
        FrontendAPIRoutes["Frontend API Routes (/api)"]:::frontend
        AuthConfig["Auth & SAML Config"]:::frontend
        SupabaseAuth["Supabase Auth & Migrations"]:::frontend
        Stripe["Stripe Integration"]:::frontend
        Components["Global Components"]:::frontend
        Layout["Layout (layout.tsx)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        MainService["Python API Service\n(main.py)"]:::backend
        APILayer["Backend API Layer"]:::backend
        BusinessAgents["Agent Logic"]:::backend
        BusinessWorkflows["Workflow Logic"]:::backend
        PluginsTools["Tools Plugins"]:::backend
        PluginsVector["Vectorstores Plugins"]:::backend
        MemoryLayer["Memory Layer (Redis)"]:::backend
        ORM["ORM Schema & Migrations"]:::backend
        BackendDocker["Backend Dockerfile"]:::infra
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Postgres["Supabase / Postgres"]:::datastore
        RedisStore["Redis"]:::datastore
        VectorInfraWeaviate["Weaviate Vector Store"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMProviders["LLM Providers"]:::external
        ThirdPartyAPIs["3rd-Party Tools APIs"]:::external
        Langfuse["Observability (Langfuse)"]:::external
        EmbeddableSDK["Embeddable JS SDK"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure Orchestrator"
        direction TB
        DockerCompose["Docker Compose Orchestrator"]:::infra
        Fern["API Spec Generator (Fern)"]:::infra
    end

    %% Relationships
    %% Frontend Flow
    UI --> FrontendAPIRoutes
    FrontendAPIRoutes --> MainService
    EmbeddableSDK --> MainService

    %% Backend Internal
    MainService --> APILayer
    APILayer --> BusinessAgents
    APILayer --> BusinessWorkflows
    APILayer --> PluginsTools
    APILayer --> PluginsVector

    BusinessAgents --> MemoryLayer
    BusinessWorkflows --> ORM
    PluginsTools --> ThirdPartyAPIs
    PluginsVector --> VectorInfraWeaviate

    MainService --> Langfuse
    MainService --> LLMProviders

    MemoryLayer --> RedisStore
    ORM --> Postgres

    %% Infra orchestration
    DockerCompose -->|orchestrates| Postgres
    DockerCompose -->|orchestrates| RedisStore
    DockerCompose -->|orchestrates| VectorInfraWeaviate
    DockerCompose -->|orchestrates| Langfuse
    DockerCompose -->|orchestrates| MainService
    DockerCompose -->|orchestrates| UI
    Fern --> APILayer

    %% Click Events
    click UI "https://github.com/superagent-ai/superagent/tree/main/libs/ui/app/"
    click FrontendAPIRoutes "https://github.com/superagent-ai/superagent/tree/main/libs/ui/app/api/"
    click AuthConfig "https://github.com/superagent-ai/superagent/blob/main/libs/ui/config/saml.ts"
    click SupabaseAuth "https://github.com/superagent-ai/superagent/tree/main/libs/ui/supabase/"
    click Stripe "https://github.com/superagent-ai/superagent/blob/main/libs/ui/lib/stripe.ts"
    click Components "https://github.com/superagent-ai/superagent/tree/main/libs/ui/components/"
    click Layout "https://github.com/superagent-ai/superagent/blob/main/libs/ui/app/layout.tsx"
    click MainService "https://github.com/superagent-ai/superagent/blob/main/libs/superagent/app/main.py"
    click APILayer "https://github.com/superagent-ai/superagent/tree/main/libs/superagent/app/api/"
    click BusinessAgents "https://github.com/superagent-ai/superagent/tree/main/libs/superagent/app/agents/"
    click BusinessWorkflows "https://github.com/superagent-ai/superagent/tree/main/libs/superagent/app/workflows/"
    click PluginsTools "https://github.com/superagent-ai/superagent/tree/main/libs/superagent/app/tools/"
    click PluginsVector "https://github.com/superagent-ai/superagent/tree/main/libs/superagent/app/vectorstores/"
    click MemoryLayer "https://github.com/superagent-ai/superagent/tree/main/libs/superagent/app/memory/"
    click ORM "https://github.com/superagent-ai/superagent/blob/main/libs/superagent/prisma/schema.prisma"
    click VectorInfraWeaviate "https://github.com/superagent-ai/superagent/tree/main/libs/.docker/external/vector-store/weaviate/"
    click Langfuse "https://github.com/superagent-ai/superagent/tree/main/libs/.docker/external/observabillity/langfuse/"
    click DockerCompose "https://github.com/superagent-ai/superagent/blob/main/libs/.docker/docker-compose.yml"
    click Fern "https://github.com/superagent-ai/superagent/tree/main/fern/"
    click EmbeddableSDK "https://github.com/superagent-ai/superagent/blob/main/libs/embed/src/index.js"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,stroke-width:1px
    classDef backend fill:#C8E6C9,stroke:#1B5E20,stroke-width:1px
    classDef datastore fill:#FFE0B2,stroke:#E65100,stroke-width:1px
    classDef external fill:#E1BEE7,stroke:#4A148C,stroke-width:1px
    classDef infra fill:#CFD8DC,stroke:#37474F,stroke-width:1px
```
