How poco-ai/poco-agent works
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