Architecture

Deployment topology, runtime boundaries, and stable contracts.

Generated explanatory diagrams

Architecture explained visually

These raster diagrams are generated documentation assets and are paired with exact captions below so the page is readable even when a tiny in-image label is hard to inspect.

Dependency graph
Shows how users and channels enter the web app, how API routes delegate to ClapilotAICore, and how runtime, database, RAG, and workspace storage depend on each other.

Deployment topology
Explains the local container split: web app, native agent service, PostgreSQL, workspace volume, and optional tunnel ingress.

Runtime boundaries
Separates app-owned UI/API behavior from native-runtime-owned model loops, memory, jobs, channels, and persistent state.

This page maps ownership across the Clapilot stack: which container owns which behavior, where durable state lives, and which contracts stay stable across releases. Read it when you need to decide where to look — the generated diagrams above show the same topology visually.

Clapilot runs as a local-first container stack with three durable boundaries:

The Next.js app is the user-facing workbench and business API layer.
clapilot-agent is the native ClapilotAICore runtime for agent execution, memory, jobs, and external channels.
PostgreSQL plus /app/workspace are the durable state and file contracts shared by both services.

If a bug is visual or API-shaped, start in the app layer. If a bug is about model routing, tool loops, channel behavior, memory, jobs, or provider execution, start in the native runtime layer.

Deployment topology

The Compose stack (docker-compose.yml) defines these services:

Service	Role
`clapilot`	Next.js app, native runtime adapter, background workers (task scheduler, document RAG indexer, agent email poller, Google/iCal sync, instance cleanup, social-media post publisher), module and skill runtime
`clapilot-agent`	Native ClapilotAICore agent runtime service
`clapilot-streamer`	Separate Live Stream Studio process that owns FFmpeg/RTMPS output, queue playback, and top-up/chat polling triggers; reports health into PostgreSQL
`postgres`	Business data, auth profiles, app settings, chat state, native runtime tables, `pgvector` embeddings
`cloudflared`	Optional tunnel ingress to the web app
`watchtower`	Optional image auto-update for registry-based deploys

Details on the clapilot-agent service:

internal chat/responses/runs/jobs/channel endpoints
DB-backed provider registry, session state, run logs, memory, scheduled-job execution, and channel bindings
iterative native agent loop with a runtime-owned system prompt and internal tools (exec_command, package_install, context_search, context_get, memory_search, memory_get, memory_grep, memory_describe, memory_expand, knowledge_search, knowledge_get_entity, knowledge_neighbors, knowledge_explain_claim, learning_search, learning_get_object, web_search, session_status)
native memory uses PostgreSQL pgvector plus OpenAI text embeddings for vector recall and PostgreSQL full-text search for keyword recall
chat and tool execution stay on the native provider loop inside clapilot-agent

Core runtime boundaries

Application layer

Next.js App Router pages and route handlers under src/app and src/app/api/**/route.ts.

Data layer

PostgreSQL with schema in db/migrations and access through src/lib/db and local supabase-compatible adapters.

RAG (retrieval-augmented generation) indexing is local-first and stored in Postgres:

document_index_jobs queue tracks pending/failed/processed indexing work
document_chunks stores chunk text + vector embeddings (pgvector)
dokumente changes enqueue reindex jobs through a DB trigger

AI and runtime layer

Chat, jobs, channels, and delegation are routed through the native clapilot-agent runtime service.

Extensibility layer

Module and skill stores and runtime APIs:

/api/module-store/*
/api/skill-store/*
/api/modules/[slug]/api/[...endpointPath]

Workspace and state layer

workspace root: /app/workspace
ClapilotAICore embedded runtime state: /app/workspace/.clapilotaicore
ClapilotAICore canonical embedded config snapshot: /app/workspace/.clapilotaicore/clapilotaicore.json

Stable contracts

dokumente.file_path is always relative to /app/workspace/mandanten
agent mailbox credentials resolve from app_settings
user mailbox credentials resolve from user_profiles
the native system-auth secret persists under /app/workspace/.clapilotaicore/system-auth.json and is reused across restarts
admin-only operations are checked at the API boundary

Primary implementation sources

entrypoint.sh
services/clapilot-agent/**
db/migrations/*.sql
src/lib/auth/*
src/lib/supabase/middleware.ts
src/lib/module-store/*
src/lib/skill-store/*