Architecture Overview

Target picture

The platform is conceived as a local control plane for AI-assisted development. It encapsulates project intake, artifact generation, run orchestration, Git/build transparency and policy/approval logic in a single web application.

User → Web UI → application logic → domain model → adapters (Claude, Git, build, filesystem, database)

Recommended layers

Web/UI: Spring MVC, Thymeleaf, optional HTMX interactions
Application: orchestration and use-case services
Domain: project, run, agent and policy model
Infrastructure: PostgreSQL, filesystem, Git, Claude adapter, build adapter

Key modules

Project Definition
Agent Definition
Team Assembly
Prompt Assembly
Run Orchestration
Validation & Gates
Policy & Approval
Artifact & Log Management

Central data flows

Project flowCreate project → fill fields → generate markdown artifacts → READY status

Run flowCreate run → walk through phases → capture logs/Git/build → complete

Approval flowCritical phase reached → persist approval → continue or abort run

Validation flowRun build/tests → store result

Run phases as a state model

Phase	Purpose	Typical action
INTAKE	Pick project and team	Create initial run
PROMPT_ASSEMBLY	Assemble artifacts	Read markdown and copy into workspace
WORKSPACE_PREPARATION	Prepare workspace	Git init, base files, initial commit
EXECUTION	Agent works	Run Claude adapter or mock
VALIDATION	Run build/tests	`mvn verify`
CORRECTION	Corrections after issues	Follow-up step or follow-up run
COMPLETION	Formally close the run	Store final status

Phase

Purpose

Typical action

INTAKE

Pick project and team

Create initial run

PROMPT_ASSEMBLY

Assemble artifacts

Read markdown and copy into workspace

WORKSPACE_PREPARATION

Prepare workspace

Git init, base files, initial commit

EXECUTION

Agent works

Run Claude adapter or mock

VALIDATION

Run build/tests

mvn verify

CORRECTION

Corrections after issues

Follow-up step or follow-up run

COMPLETION

Formally close the run

Store final status

License and identity layer

Besides the product backend there is a dedicated stack for identity and licensing, decoupled from the platform database:

Keycloak as OIDC provider (users, roles, device authorization grant)

License service as a Spring Boot microservice with its own PostgreSQL

Lease JWT (RS256, valid for 7 days) carrying per-tier limits

Offline verification in the client via embedded public key, fail closed once the lease has expired

After installation the client runs in registration-free DEMO mode (mock adapter only, hard-coded limits in the client, no server contact). Once the user registers via the device flow, a COMMUNITY license is provisioned automatically; an admin can upgrade the tier to FULL in the admin UI. The lease dictates which adapter may be used and how run creation and team size are capped.

Going deeper

The architecture outlined here is the product-side realisation of a more general model. If you want to dig into the underlying principles of agentic software development architectures – reference architecture, agent orchestration, guardrails, memory structures and SDLC integration – the companion whitepaper (76 pages) contains the fuller account. It provides the conceptual background this platform is built on.

Why this architecture makes sense

It keeps version 1 deliberately lean without blocking later growth. The platform can start with a single executing adapter and is still cut in such a way that additional agent roles, more complex policies or true multi-agent execution can be added later.

Rule of thumb: Version 1 does not need to do everything. It needs to place the right boundaries and extension points cleanly.