Orchestra System Architecture

Welcome to the architectural documentation for Orchestra, an automated agent orchestration system built on Spring Boot AI and OpenCode.

Overview

Orchestra acts as the "Control Plane" for autonomous software engineering. It does not contain the LLM logic itself; instead, it orchestrates a fleet of specialized agents (running on the OpenCode "Data Plane") to collaborate on complex tasks.

Documentation Index

1. Data Model (ERD)

   • Explains how Workflows, Tasks, Agents, and Artifacts are structured and persisted.

2. System Class Structure

   • Details the Java class hierarchy, including the split between the Orchestration Service (Manager) and the State Engine (Brain).

3. Execution Flow

   • Visualizes the lifecycle of a request, showing how a high-level goal is transformed into architectural designs and implementation tasks via the event-driven loop.

Key Concepts

• Delegated Autonomy: The Spring Boot application manages state, while the OpenCode server manages intelligence and tool execution.
• Artifact-Driven State Machine: Transitions between workflow stages are not hardcoded steps, but reactions to the specific artifacts (YAML, Code) produced by agents.
• Event Sourcing: The system uses internal Spring Events to decouple the mechanical process of running agents from the business logic of workflow progression.