Architecture
Orchestra is a distributed application orchestrated by .NET Aspire 9. It consists of five services, two infrastructure dependencies, and communicates with external third-party platforms via REST and MCP protocols.
System Diagram
The following diagram shows how all Orchestra services and dependencies connect at runtime:
Service Breakdown
Each service has a distinct responsibility and communicates over well-defined boundaries:
| Service | Port | Responsibility |
|---|---|---|
| React 19 UI | 3002 |
Conductor's dashboard — agents, tickets, workflows, jobs, MCP, CLI integrations, and skills management |
| CopilotKit Runtime | 3001 |
Node.js agentic UI communication layer powering the embedded AI assistant widget |
| ADF Generator | 3300 |
Node.js microservice for bidirectional Atlassian Document Format (ADF) conversion |
| .NET 10 API | 3000 |
Core business logic via Clean Architecture — REST controllers, SignalR hubs, JWT auth, encryption |
| .NET Worker | — | Background agent execution, DB migrations on startup, job orchestration, session recovery after restarts |
| PostgreSQL | 5432 |
Primary relational store via Entity Framework Core — all workspace, agent, ticket, and integration data |
| Redis | 6379 |
SignalR scale-out backplane enabling real-time pub/sub between API and Worker services |
Key Data Flows
Agent Execution Flow
User assigns a ticket to an agent in the UI. The API creates a background Job record in PostgreSQL.
The .NET Worker service polls for pending jobs and begins executing the agent with its configured tools and instructions.
As the agent works, the Worker publishes events to Redis. The API relays these via SignalR WebSocket to the connected UI.
Agents call tools based on their authorized ToolAction list — either native integrations (via reflection) or MCP servers (via HTTP/stdio).
The Worker marks the job complete. Sub-agent interactions and execution logs are persisted. The UI updates in real time.
MCP Tool Registration Flow
User submits an MCP server form with transport type (HTTP or stdio), endpoint, and auth credentials.
API calls POST /v1/integrations/mcp/discover to test the connection and list available tools.
On success, McpToolSeedingService creates ToolCategory and ToolAction records — one per discovered tool.
Agents can now authorize these MCP tools via the agent form's tool authorization panel, referencing tools by ID.
Tech Stack
| Category | Technologies |
|---|---|
| Backend | .NET 10, .NET Aspire 9, Entity Framework Core |
| Frontend | React 19, Vite, TypeScript, Tailwind CSS, React Flow, Recharts |
| Database | PostgreSQL (EF Core migrations) |
| Cache / Real-Time | Redis, SignalR (WebSockets) |
| AI Runtime | Microsoft Agents Framework, Azure OpenAI, Ollama |
| Authentication | JWT Bearer, bcrypt password hashing |
| Integration Protocol | Model Context Protocol (MCP) — stdio & HTTP transports |
| Node.js Services | CopilotKit Runtime, ADF Generator (Express) |
| Orchestration | .NET Aspire AppHost with service discovery |
Clean Architecture Layers
The Orchestra.ApiService and Orchestra.Worker follow Clean Architecture with strict dependency rules:
Entities, enums, interfaces, value objects, validators. Zero external dependencies — the pure business model.
Key entities: Agent, Integration, Ticket, Workspace, ToolCategory, ToolAction
Use cases and services — AgentService, IntegrationService, McpIntegrationService, ToolService, AI agent execution logic.
EF Core DbContext, data access implementations, MCP client factory (HTTP + stdio), encryption service.
REST controllers, SignalR hubs, JWT middleware, request/response models. Depends only on Application interfaces.
Database Schema Overview
Key entities and their relationships stored in PostgreSQL:
| Entity | Key Fields | Relationships |
|---|---|---|
| Workspace | Id, Name, AI provider config |
Has many Agents, Integrations, Tickets, Tools, Skills |
| Agent | Id, WorkspaceId, Name, Role, Model, TemplateIdentifier |
Has many ToolActions (via AgentToolAction join table) |
| Integration | Id, WorkspaceId, Provider, IsMcpBacked, McpEndpointUrl |
Has many ToolCategories (when MCP-backed) |
| ToolCategory | Id, Name, ProviderType, IntegrationId? |
Has many ToolActions. IntegrationId = null for native tools |
| ToolAction | Id, ToolCategoryId, Name, DangerLevel, IsMcpTool |
Referenced by AgentToolAction join records |
| Ticket | Id, WorkspaceId, ExternalId, Status, Priority |
Sourced from Integration, optionally assigned to an Agent |
| Job | Id, AgentId, TicketId, Status |
Created per agent execution, has many SubAgentInteractions |
Migrations: EF Core database migrations are applied automatically by the Orchestra.Worker service on startup — no manual dotnet ef database update is required.