Architecture

Architecture

The full, up-to-date architecture document lives in the repo: 👉 docs/architecture.md

This page is just a quick look.

In one sentence

"Who is allowed to do what" on the JVM side, "how to reason" on the Python side.

Two services

	control-plane	agent-runtime
Language	Java 21 / Spring Boot	Python 3.11 / FastAPI
Responsible for	API surface, auth, orchestration, persistence, queue	agent loop, tools, LLM, RAG, eval
Not responsible for	Talking to the LLM, selecting tools	Authorization decisions, queue management
Port	8080	8000

Why this boundary?

We keep security and orchestration decisions outside a runtime that a prompt can influence. Prompt injection can fool the agent-runtime; it cannot fool the authorization check in the control-plane, because there is no LLM there.

Detailed rationale: ADR-0001

Contract

Single entry point: POST /v1/tasks/run Source: agent-runtime/app/api/schemas.py

If you make a breaking change: ADR + breaking change label + update both services in the same PR.

Layer map (month by month)

Month	Layer added
1	Two services + PostgreSQL + Docker
2	Agent loop, tool registry, pgvector
3	Eval harness and baseline
4	Task queue, cache, cost tracking
5	Auth, rate limit, log/metric/trace, CI/CD
6	Diagram, demo, launch