# kortix-ai/suna architecture

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

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

## Overview

##### Project Type and Purpose
- This is a full-stack web application called **Suna**, an open-source AI assistant that automates real-world tasks through conversation.
- It has four main parts:
- A **Frontend** (Next.js/React) for the user interface
- A **Backend API** (Python/FastAPI) that manages threads, users, and talks to LLMs
- An **Agent Docker** environment (Daytona) where each AI agent runs securely
- A **Supabase Database** for persistence, authentication, and real-time subscriptions

##### File Structure
- Top-level directories:
- `.github` / `docker-compose.yaml` – CI/CD and container orchestration
- `backend/` – FastAPI service, agent code, sandbox runner, service wrappers, scripts
- `frontend/` – Next.js app with UI components, pages, APIs, and styling/config files
- Key backend sub-directories:
- `backend/agent/` – core agent logic, tool integrations (browser, file system, data providers)
- `backend/agentpress/` – thread and tool registry, context and response processing
- `backend/services/` – wrappers for Redis, LLMs, Supabase, billing
- `backend/sandbox/` – isolated sandbox for secure tool execution
- Deployment files:
- Dockerfiles (root, frontend/Dockerfile, backend/Dockerfile, sandbox/docker)
- Fly.io and docker-compose configurations

##### README for Additional Insights
- Confirms the four components and their roles.
- Mentions LLM providers (Anthropic, OpenAI, Groq), web search/scraping tools (Tavily, Firecrawl), Playwright for browser automation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client / Frontend"
        direction TB
        Browser["User's Browser"]:::client
        subgraph "Next.js Frontend" 
            direction TB
            Frontend["Next.js Frontend UI"]:::frontend
            FE_Docker["Dockerfile"]:::file
            FE_App["src/app/ & src/app/api/"]:::file
            FE_Comp["src/components/"]:::file
        end
    end

    %% Server Layer
    subgraph "Server / Backend"
        direction TB
        subgraph "API Service (FastAPI)"
            direction TB
            BackendAPI["FastAPI Backend API"]:::backend
            BE_API["api.py"]:::file
            BE_Pyproj["pyproject.toml"]:::file
            BE_Req["requirements.txt"]:::file
            BE_Docker["Dockerfile"]:::file
            BE_DC["docker-compose.yml"]:::file
        end

        subgraph "Agent Core Logic"
            direction TB
            AgentCore["Agent Core Logic"]:::agent
            AC_Run["run.py"]:::file
            AC_Prompt["prompt.py & gemini_prompt.py"]:::file
        end

        subgraph "Agentpress (Registry & Processing)"
            direction TB
            AP_Thread["thread_manager.py"]:::file
            AP_Context["context_manager.py"]:::file
            AP_Registry["tool_registry.py"]:::file
            AP_Processor["response_processor.py"]:::file
        end

        subgraph "Tool Integrations"
            direction TB
            Tools["Browser, FS, Scraping, Data"]:::external
        end

        subgraph "Sandbox Environment"
            direction TB
            SandboxAPI["api.py & sandbox.py"]:::agent
            SandboxDocker["docker/Dockerfile"]:::file
        end

        subgraph "Service Wrappers"
            direction TB
            Redis["Redis Cache"]:::cache
            SupabaseSvc["Supabase Integration"]:::db
            LLMWrap["LLM Provider Wrapper"]:::external
            Billing["Billing Service"]:::external
        end

        subgraph "Supabase Database & Auth"
            direction TB
            SupabaseDB["Postgres & Auth"]:::db
            SupabaseConfig["config.toml & migrations"]:::file
        end
    end

    %% External Services
    LLMs["External LLM Providers"]:::external
    ToolsExt["Playwright, Tavily, Firecrawl"]:::external

    %% Connections
    Browser -->|"HTTPS"| Frontend
    Frontend -->|"REST API"| BackendAPI
    BackendAPI -->|"Read/Write"| SupabaseDB
    BackendAPI -->|"Cache"| Redis
    BackendAPI -->|"Spawn/Delegate"| AgentCore
    AgentCore -->|"Use Registry"| AP_Registry
    AgentCore -->|"Execute Tools"| Tools
    AgentCore -->|"Callback"| BackendAPI
    BackendAPI -->|"Call"| LLMs
    BackendAPI -->|"Service"| LLMWrap
    BackendAPI -->|"Service"| Billing
    BackendAPI -->|"Service"| SupabaseSvc
    BackendAPI -->|"Service"| Redis
    Frontend <-->|"Realtime"| SupabaseDB
    AgentCore -->|"Run in Sandbox"| SandboxAPI
    SandboxAPI -->|"Dockerized"| SandboxDocker

    %% Click Events
    click Frontend "https://github.com/kortix-ai/suna/tree/main/frontend/"
    click FE_Docker "https://github.com/kortix-ai/suna/tree/main/frontend/Dockerfile"
    click FE_App "https://github.com/kortix-ai/suna/tree/main/frontend/src/app/"
    click FE_Comp "https://github.com/kortix-ai/suna/tree/main/frontend/src/components/"
    click BE_API "https://github.com/kortix-ai/suna/blob/main/backend/api.py"
    click BE_Pyproj "https://github.com/kortix-ai/suna/blob/main/backend/pyproject.toml"
    click BE_Req "https://github.com/kortix-ai/suna/blob/main/backend/requirements.txt"
    click BE_Docker "https://github.com/kortix-ai/suna/tree/main/backend/Dockerfile"
    click BE_DC "https://github.com/kortix-ai/suna/blob/main/backend/docker-compose.yml"
    click AC_Run "https://github.com/kortix-ai/suna/blob/main/backend/agent/run.py"
    click AC_Prompt "https://github.com/kortix-ai/suna/blob/main/backend/agent/prompt.py"
    click AP_Registry "https://github.com/kortix-ai/suna/blob/main/backend/agentpress/tool_registry.py"
    click AP_Thread "https://github.com/kortix-ai/suna/blob/main/backend/agentpress/thread_manager.py"
    click SandboxDocker "https://github.com/kortix-ai/suna/tree/main/backend/sandbox/docker/Dockerfile"

    %% Styles
    classDef client fill:#e0f7fa,stroke:#006064,color:#004d40;
    classDef frontend fill:#e8f5e9,stroke:#1b5e20,color:#2e7d32;
    classDef backend fill:#e3f2fd,stroke:#0d47a1,color:#1565c0;
    classDef agent fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c;
    classDef cache fill:#fff3e0,stroke:#ef6c00,color:#e65100;
    classDef db fill:#fff8e1,stroke:#ff8f00,color:#ff6f00;
    classDef external fill:#eceff1,stroke:#607d8b,color:#37474f;
    classDef file fill:#fafafa,stroke:#9e9e9e,color:#616161,stroke-dasharray: 2 2;
```
