Architecture

CleverThis is a monorepo with three primary components: the Next.js webapp, the Python FastAPI server, and the cleveractors-core library. They are developed together but have clear interface boundaries.

Monorepo layout

cleverthis/
├── apps/
│   └── webapp/          # Next.js app (frontend + BFF)
├── packages/
│   └── cleveractors-core/  # Python library: Actor execution engine
├── server/              # Python FastAPI server (gateway + management API)
├── docker/              # Dockerfiles and compose configs
├── docs/                # This documentation site (Docusaurus)
└── scripts/             # Developer tooling scripts

Component overview

Webapp (apps/webapp) — A Next.js 14 App Router application. Handles all user-facing UI: Dashboard, Library, Namespaces, Deployments, Chat, Usage & Billing, Settings. Communicates with the API server via the A2A client (management operations) and directly via the OpenAI-compatible inference endpoints (chat). See Webapp.

API Server (server/) — A Python FastAPI application. Exposes the OpenAI-compatible inference routes (/v1/*) and the A2A control plane (/a2a). Orchestrates provider routing, Actor execution (via cleveractors-core), usage tracking, and authentication. See API Server.

cleveractors-core (packages/cleveractors-core/) — A standalone Python library responsible for parsing Actor YAML, validating it against the schema, and executing Actor graphs. The API server imports it as a library — it has no HTTP surface of its own. See cleveractors-core.

What's in this section

• Webapp
• API Server
• cleveractors-core

Coming soon

Architecture decision records (ADRs) are linked from each component page.