Repository map

Top-level components

abada-engine/
├── engine/          Java 21 transactional runtime, persistence, API and security
├── agent-worker/    First-party Java 21 Agent Worker sidecar (abada.agent/v1)
├── sdk/java/        Java external-worker protocol v1 client
├── studio/          React/TypeScript Studio — the single operator UI
├── abada-site/      Marketing site (abadaplatform.com)
├── install/         Cloudflare Worker serving install.abadaplatform.com
├── documentation/   Astro/Starlight guide (this site)
├── docs/            Contracts, ADRs, specifications, features, release evidence
├── examples/        Runnable APL examples (examples/apl/*.apl.yaml)
├── docker/          Observability and supporting container configuration
├── deployment/, k8s/, monitoring/   Ops and infrastructure assets
├── compose*.yaml    Supported Compose family (dev, prod, telemetry overlays)
├── release/, scripts/  Release bundles, launcher and development/verification helpers

Engine packages

com.abada.engine/
├── api/             REST controllers and HTTP error translation
├── authoring/       Authoring-side engine services (documents, forms, project tree)
├── bpmn/            Compatibility detection, validation and migration
├── cli/             Migration command-line entry points
├── config/          OpenAPI and observability configuration
├── core/            Atomic commands and state advancement (incl. agent external tasks)
├── context/         Request/identity context plumbing
├── dto/             Stable public request and response models
├── identity/        IdP proxy and principal cache
├── insight/         Insight Engine — facts, windows, findings, proposals, policies
├── llm/             Bounded LLM client used by authoring and Insight drafting
├── observability/   Metrics and tracing
├── parser/          AplParser (native APL) and BPMN dialect parsing
├── persistence/     JPA entities, repositories and persistence adapters
├── project/         Project envelope, membership, worker health and bindings
├── runtime/         Runtime primitives behind the canonical model
├── security/        OIDC, proxy authentication and permission mapping
├── spi/             Service-provider extension points
└── util/            Shared helpers

Studio feature panels

Studio is the single operator UI. Its feature modules under studio/src/features/ map to the product surfaces:

Feature module	Surface
designer/	Canvas, node inspector, AI diff review modal
dmn/	Native decision-table rule matrix editor
ai/	Natural-language APL scaffolding / AI assist
run/	Dry Run and Deploy & Start panels
inbox/	Task Inbox with form rendering (FormRenderer)
operations/	Instances, telemetry, worker health
insight/	Proposal review (InsightPanel, InsightAPI.reviewProposal)
admin/	Users, groups and projects administration
workspace/	Project Explorer, file tree and project switching
execution/, tasks/	Engine execution and task DTO plumbing

The shared APL document model lives in studio/src/lib/apl/ (types, parser, stringify) and the APL↔BPMN compiler/transpiler in studio/src/lib/bpmn/.

Find behavior by responsibility

Question	Begin at
Which HTTP contract handles this request?	engine/src/main/java/com/abada/engine/api/
Where is workflow state advanced?	core/ — @AtomicRuntimeCommand services and the canonical model
How is APL YAML compiled?	parser/AplParser and its rejection matrix tests
How is BPMN XML normalized?	parser/ and bpmn/compatibility/
Where do agent tasks live between fetch and completion?	core/ external-task commands, project/WorkerHealthService, agent-worker/
Where does the Insight Engine live?	insight/ (facts, analyzer, proposals, policies)
Which row is authoritative?	persistence/entity/ and the latest Flyway migration
How is a permission granted?	security/SecurityConfig, AbadaRoles, and project roles in project/
What is guaranteed publicly?	docs/reference/ and executable contract tests
Which release gate owns the work?	docs/development/roadmap.md (earlier roadmaps are in docs/archive/)

Test layout

Tests mirror production packages under engine/src/test/java. Executable APL models live under engine/src/test/resources/apl (including the kitchen-sink.apl.yaml twin of the BPMN kitchen sink), BPMN fixtures under engine/src/test/resources/bpmn, and stable API shapes under engine/src/test/resources/contracts. PostgreSQL suites use two or more Spring contexts when they must prove behavior across replicas. Representative agentic-era suites: AplParserTest, AplRuntimeTest, AplKitchenSinkTest, AgentWorkerResilienceTest, FirstPartyWorkerCapabilityTest, WorkerHealthServiceTest and the Insight analyzer tests.

Local instructions

Repository-wide contribution rules live in AGENTS.md. A more specific AGENTS.md may override them for a subtree. Generated output, local databases, logs, credentials, .env files and IDE metadata must not be committed.