cleveragents-core/docs/reference/architecture_overview.md

Architecture Overview

CleverAgents is a Python-first automation platform for orchestrating complex, long-running tasks with AI actors. This document provides a high-level map of the system's layers, core abstractions, and the protocols that connect them. For the authoritative design rationale behind each decision, refer to the relevant Architecture Decision Records.

Specification is the source of truth. If this document conflicts with docs/specification.md, the specification takes precedence.

---

System Layers

CleverAgents follows a strict layered architecture (ADR-001):

┌──────────────────────────────────────────────────────────────────┐
│  Presentation Layer                                              │
│  CLI (Typer/Click)  ·  TUI (Textual)  ·  Server (ASGI/A2A)      │
├──────────────────────────────────────────────────────────────────┤
│  Application Layer                                               │
│  Services  ·  Use-case orchestration  ·  Event bus               │
├──────────────────────────────────────────────────────────────────┤
│  Domain Layer                                                    │
│  Models  ·  Value objects  ·  Domain events  ·  Invariants       │
├──────────────────────────────────────────────────────────────────┤
│  Infrastructure Layer                                            │
│  SQLAlchemy ORM  ·  Alembic migrations  ·  Resource handlers     │
│  LangChain/LangGraph  ·  MCP adapter  ·  LSP runtime             │
└──────────────────────────────────────────────────────────────────┘

Dependencies flow downward only. The domain layer has no imports from infrastructure or application layers.

---

Core Abstractions

Plan Lifecycle

The central workflow abstraction. A plan moves through four phases:

Action ──► Strategize ──► [Estimate] ──► Execute ──► Apply

Phase	Description
Action	Defines the goal: what the actor should accomplish
Strategize	Actor produces a decision tree of steps
Estimate	Optional: estimation actor forecasts cost/time/risk
Execute	Steps are executed; decisions recorded
Apply	Validated changes committed to resources

Phase transitions are governed by Automation Profiles (ADR-017), which set confidence thresholds for autonomous vs. human-approved transitions.

See ADR-006 and plan_execute.md.

Decision Tree

Every plan produces a decision tree — a versioned, append-only record of every choice made during execution. Decisions can be corrected, rolled back, and replayed (ADR-007, ADR-033–035).

Key decision types: tool_call, resource_selection, sub_plan, human_approval, correction.

Actors

Actors are the AI agents that execute plans. Each actor is a named, namespaced configuration binding a provider/model to a set of capabilities. Built-in actors follow <provider>/<model> naming; custom actors use local/<id>.

See ADR-010 and actor_runtime.md.

Resources

Resources are the managed objects that plans operate on — files, databases, containers, devcontainers, LSP servers, and more. The resource system uses a DAG for dependency tracking and a handler protocol for CRUD, checkpointing, and sandboxing (ADR-008, ADR-036).

See resources.md and resource_handlers.md.

Skills

Skills are reusable, versioned capability bundles that extend what actors can do. They are resolved from local files, Git repositories, or the AgentSkills.io registry (ADR-012, ADR-028, ADR-030).

Tools

Tools are the atomic operations actors invoke during execution. The tool system provides reachability analysis, access projection, and MCP adapter integration (ADR-011, ADR-029, ADR-037).

---

Key Services (Application Layer)

Service	Responsibility
PlanLifecycleService	Phase transitions, estimation hook, event emission
PlanApplyService	Validation gate, changeset statistics, PLAN_APPLIED event
CorrectionService	Decision correction, dry-run reports, rollback
SessionService	Session CRUD, message persistence
PermissionService	Tool permission requests, session-scoped decisions
AuditEventSubscriber	SEC7 audit log from domain events
UKOQueryInterface	ACMS context strategy queries against UKO graph
UKOInferenceEngine	Implicit triple inference (confidence 0.7)
UKOGraphPersistence	UKO graph serialisation/restore across restarts

---

Estimation Lifecycle (v3.7.0)

When actor.default.estimation is configured, the Strategize→Execute transition invokes an estimation actor before execution begins:

Strategize complete
       │
       ▼
EstimationActor.run(plan)
       │
       ├── stores EstimationResult on plan
       ├── populates plan.cost_estimate_usd
       └── emits PLAN_ESTIMATION_COMPLETE event
       │
       ▼  (estimation failure is informational — never blocks Execute)
Execute phase begins

See estimation_lifecycle.md.

---

Protocols and Standards

CleverAgents integrates three industry protocols for interoperability:

Protocol	Purpose	ADR
A2A (Agent-to-Agent)	CLI/TUI ↔ application service communication	ADR-026, ADR-047
MCP (Model Context Protocol)	Tool and resource exposure to LLM actors	ADR-029
LSP (Language Server Protocol)	Code intelligence for resource types	ADR-027, ADR-040

A2A Facade

The A2A local facade is the single communication channel between the presentation layer (CLI, TUI) and the application layer. It maps A2A protocol messages to service calls and translates domain errors to A2A error codes:

Domain Error	A2A Code
NotFoundError	NOT_FOUND
ValidationError	VALIDATION_ERROR
InvalidStateError	INVALID_STATE
PlanError	PLAN_ERROR
ValueError	VALIDATION_ERROR

---

Dependency Injection

All services are wired through a DI container (ADR-003). The container is initialised once at startup (agents init) and injected into CLI commands and TUI handlers. This ensures testability and prevents hidden global state.

See di.md.

---

Persistence

Store	Technology	Purpose
Primary DB	SQLite (default) / PostgreSQL	Plans, decisions, sessions, resources, audit log
Migrations	Alembic	Schema versioning
Persona config	YAML files (~/.config/cleveragents/personas/)	TUI persona definitions
TUI state	YAML (~/.config/cleveragents/tui-state.yaml)	Last-used persona
Checkpoints	Per-handler strategy	Rollback points for resource mutations

See ADR-019 and database_schema.md.

---

Sandboxing and Safety

Every resource mutation during Execute is wrapped in a sandbox. The SandboxManager coordinates cross-mechanism sandbox commits atomically (all-or-nothing, LIFO rollback on partial failure). Automation profiles control which transitions require human approval.

See ADR-015, ADR-038, and sandbox.md.

---

Interactive Terminal UI (v3.7.0)

The TUI (agents tui) is a full-screen Textual application that communicates with the application layer exclusively through the A2A local facade — the same protocol used by the CLI.

TUI (Textual App)
    │
    ├── InputModeRouter  ─── Normal / Command (/) / Shell (!)
    ├── SlashCommandOverlay  ─── 67 commands, 14 groups
    ├── ReferencePickerOverlay  ─── @reference expansion
    ├── HelpPanelOverlay (F1)  ─── context-sensitive help
    ├── PermissionsScreen  ─── tool permission diff review
    ├── ActorSelectionOverlay  ─── first-run actor picker
    └── PersonaBar  ─── active persona / preset / scope count
              │
              ▼
        A2A Local Facade
              │
              ▼
        Application Services

See tui.md and ADR-044.

---

Server Mode (v3.7.0)

agents server connect configures a remote CleverAgents server. The server exposes the same A2A protocol over HTTP/WebSocket. A Kubernetes Helm chart (k8s/) and Dockerfile.server are provided for production deployment.

See ADR-023, ADR-048, and server_client_stubs.md.

---

Observability

LangSmith tracing is optional and off by default. Domain events flow through the event bus to the AuditEventSubscriber, which writes structured audit log entries (SEC7 compliance). All PLAN_APPLIED events carry changeset statistics (files changed, lines added/removed, resources modified, apply duration).

See ADR-025 and observability.md.

---

Related Documentation

• Specification — authoritative source of truth
• ADR Index — all architectural decisions
• Plan Lifecycle
• Decision Correction
• Resource System
• Actor Runtime
• TUI Reference
• ACMS / UKO
• Dependency Injection
• Database Schema