# poco-ai/poco-agent architecture

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

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

## Overview

##### Project Type & Purpose
- This is a full-stack, containerized AI agent platform (“Poco”) with:
- A Next.js-based web frontend
- A FastAPI backend service
- Two auxiliary microservices—executor_manager (schedules and dispatches jobs) and executor (runs sandboxed tasks)
- A relational database (managed via SQLAlchemy/Alembic) and optional object storage (S3/R2)
- Docker-based isolation for sandboxed code execution

##### Top-Level File Structure & Architectural Patterns
- Directories:
- frontend/ → Next.js app (React UI, i18n, API proxy)
- backend/ → Core FastAPI REST API (models, schemas, repos, services, middleware, Alembic migrations)
- executor_manager/ → Scheduler microservice (pull jobs, dispatch tasks to executors)
- executor/ → Worker microservice (executes code in sandbox, reports back)
- docker/ → Dockerfiles & startup scripts for each service
- Patterns:
- Layered architecture (API layer, service layer, repository layer, DB)
- Microservices communicating over HTTP (FastAPI clients)
- Container-per-task sandbox model

##### Key Components & Interactions
A. User & Client
- Browser/mobile client ←→ Next.js frontend
B. Frontend (Next.js)
- UI pages and components ←→ backend REST API (via fetch calls to /api/v1/*)
C. Backend (FastAPI)
- Exposes API endpoints (app/api/v1)
- Orchestrates business logic (app/services)
- Persists state to database (app/core/database + Alembic migrations)
- Emits scheduling or execution requests to executor_manager (via HTTP client)
D. Executor Manager
- Periodically polls database or listens for new runs (app/scheduler)
- Uses HTTP client to dispatch tasks to executor services
E. Executor
- Receives task payloads, spins up a sandboxed container (Docker)
- Executes user code or agent plans (app/core/engine)
- Reports results and artifacts back to backend or object storage
F. Database & Storage
- PostgreSQL or SQLite for metadata
- Optional S3/R2 for artifacts (via storage_service)
G. External Services
- Claude Code LLM API (for AI reasoning tasks)
- GitHub/GitLab integration for repo access

##### Architectural Patterns & Design Principles
- Layered modules: routers → services → repositories → models
- Dependency injection via FastAPI’s Depends
- Asynchronous tasks and scheduling decoupled into separate microservices
- Docker sandbox ensures host safety
- Versioned API (v1) to allow future evolution

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Client
    subgraph "User & Client"
        User["User / Browser"]:::frontend
    end

    %% Frontend Layer
    subgraph "Frontend Container"
        FE["Next.js Frontend"]:::frontend
        UIpages["UI Pages & Components"]:::frontend
        Components["Components"]:::frontend
        FrontendAPIProxy["API Proxy Routes"]:::frontend
        APIClient["API Client Utilities"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Container"
        BE["FastAPI Backend"]:::backend
        BErouters["API Endpoints (app/api/v1)"]:::backend
        BEsrv["Business Logic (services)"]:::backend
        BErepo["Repositories"]:::backend
        BEdb["Database Core & Connection"]:::backend
        BECoresettings["Settings & DI"]:::backend
        Alembic["Alembic Migrations"]:::datastore
        Claude["Claude LLM Integration"]:::backend
        StorageSrv["Storage Service (S3/R2)"]:::backend
    end

    %% Executor Manager Layer
    subgraph "Executor Manager Container"
        EMGR["Executor Manager"]:::micro
        EMScheduler["Scheduler Module"]:::micro
        EMServices["EM Services (dispatch)"]:::micro
    end

    %% Executor Layer
    subgraph "Executor Container"
        EXEC["Executor Worker"]:::micro
        ExecAPI["Task Receiver API"]:::micro
        ExecEngine["Core Engine (Sandbox Runner)"]:::micro
        ExecHooks["Hooks & Callbacks"]:::micro
        ExecGit["Git Integration Utils"]:::micro
    end

    %% Datastores & External
    DB["Relational Database"]:::datastore
    Storage["Object Storage"]:::datastore
    ClaudeAPI["Claude Code LLM API"]:::external
    GitExt["GitHub/GitLab"]:::external

    %% Docker & Env
    DockerFront["docker/frontend/"]:::external
    DockerBack["docker/backend/"]:::external
    DockerEM["docker/executor_manager/"]:::external
    DockerExec["docker/executor/"]:::external
    Compose["docker-compose.yml\n& docker-compose.r2.yml"]:::external
    Env[".env.example & backend/.env.example"]:::external

    %% Flows
    User -->|"HTTP"| FE
    FE -->|"fetch /api/v1/*"| BE
    BE -->|"read/write"| DB
    BE -->|"HTTP request"| EMGR
    EMGR -->|"HTTP dispatch"| EXEC
    EXEC -->|"results callback"| BE
    BE -->|"upload artifacts"| Storage
    EXEC -->|"write artifacts"| Storage
    BE -->|"call"| ClaudeAPI
    EXEC -->|"git clone"| GitExt

    %% Click Events
    click FE "https://github.com/poco-ai/poco-agent/tree/main/frontend/"
    click UIpages "https://github.com/poco-ai/poco-agent/tree/main/frontend/app/[lng]/(shell)"
    click Components "https://github.com/poco-ai/poco-agent/tree/main/frontend/components/"
    click FrontendAPIProxy "https://github.com/poco-ai/poco-agent/blob/main/frontend/app/api/v1/[...path]/route.ts"
    click APIClient "https://github.com/poco-ai/poco-agent/blob/main/frontend/lib/api-client.ts"
    click BErouters "https://github.com/poco-ai/poco-agent/tree/main/backend/app/api/v1/"
    click BEsrv "https://github.com/poco-ai/poco-agent/tree/main/backend/app/services/"
    click BErepo "https://github.com/poco-ai/poco-agent/tree/main/backend/app/repositories/"
    click BEdb "https://github.com/poco-ai/poco-agent/blob/main/backend/app/core/database.py"
    click BECoresettings "https://github.com/poco-ai/poco-agent/blob/main/backend/app/core/settings.py"
    click Alembic "https://github.com/poco-ai/poco-agent/tree/main/backend/alembic/"
    click Claude "https://github.com/poco-ai/poco-agent/blob/main/backend/app/services/claude_md_service.py"
    click StorageSrv "https://github.com/poco-ai/poco-agent/blob/main/backend/app/services/storage_service.py"
    click EMGR "https://github.com/poco-ai/poco-agent/tree/main/executor_manager/app/"
    click EMScheduler "https://github.com/poco-ai/poco-agent/tree/main/executor_manager/app/scheduler/"
    click EMServices "https://github.com/poco-ai/poco-agent/tree/main/executor_manager/app/services/"
    click ExecAPI "https://github.com/poco-ai/poco-agent/blob/main/executor/app/api/v1/task.py"
    click ExecEngine "https://github.com/poco-ai/poco-agent/blob/main/executor/app/core/engine.py"
    click ExecHooks "https://github.com/poco-ai/poco-agent/tree/main/executor/app/hooks/"
    click ExecGit "https://github.com/poco-ai/poco-agent/tree/main/executor/app/utils/git/"
    click DockerFront "https://github.com/poco-ai/poco-agent/tree/main/docker/frontend/"
    click DockerBack "https://github.com/poco-ai/poco-agent/tree/main/docker/backend/"
    click DockerEM "https://github.com/poco-ai/poco-agent/tree/main/docker/executor_manager/"
    click DockerExec "https://github.com/poco-ai/poco-agent/tree/main/docker/executor/"
    click Compose "https://github.com/poco-ai/poco-agent/blob/main/docker-compose.yml"
    click Env "https://github.com/poco-ai/poco-agent/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#000,color:#000
    classDef backend fill:#DFFFD0,stroke:#000,color:#000
    classDef micro fill:#FFE4B5,stroke:#000,color:#000
    classDef datastore fill:#EEEEEE,stroke:#000,color:#000
    classDef external fill:#E6D0FF,stroke:#000,color:#000
```
