# shemayon/devpro-orchestrator architecture

> Architecture diagram of the GitHub repository shemayon/devpro-orchestrator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shemayon/devpro-orchestrator
- Repository: https://github.com/shemayon/devpro-orchestrator

## Overview

1. **System shape**
   - This repo is a two-tier agent orchestration platform: a **React frontend** for visibility/control and a **Python backend** that executes tasks through a multi-agent supervisor.
   - The main boundary is between the browser-facing dashboard and the backend orchestration/runtime; the backend then fans out to agents, storage, and external AI/search services.

2. **Frontend subsystem**
   - `frontend/` is a standalone **Vite + React** application.
   - Its role is operational: present task state, agent status, and progress updates. It does not appear to own business logic or persistence.
   - The frontend is built into static assets and served behind Nginx, which suggests the browser talks to the backend through a unified entrypoint rather than directly to multiple services.

3. **Edge/proxy layer**
   - `nginx.conf` and the Docker setup indicate Nginx is the public reverse proxy.
   - It likely routes browser traffic to the React assets and forwards API calls to the Python service, giving the system a single external port and a clean deployment boundary.

4. **API and application entrypoints**
   - `src/api.py` is the backend HTTP surface, exposing the orchestration system over REST.
   - `src/cli.py` provides a non-HTTP entrypoint for local/operator workflows.
   - `src/supervisor.py`, `src/supervisor_executor.py`, and `src/task_manager.py` are the operational core used by the API and CLI to start, coordinate, and track work.

5. **Orchestration core**
   - `src/core/` contains the shared orchestration primitives: agent protocol, registry, workflow state, and the orchestrator itself.
   - This is the main coordination boundary: it defines how tasks move through the system, how agent capabilities are discovered, and how task state is shared across steps.
   - The README explicitly positions this as a **LangGraph Supervisor**-style multi-agent system, so the supervisor is the central scheduler/router rather than a simple queue consumer.

6. **Specialized agents**
   - `src/agents/` contains the four domain agents: **research**, **coding**, **testing**, and **documentation**.
   - These are separate expert roles with distinct prompts/behavior, not just generic workers.
   - The likely data flow is: supervisor receives a task, decomposes or routes it, and dispatches substeps to the appropriate agent based on the task type and current state.

7. **External intelligence and research integrations**
   - `src/integrations/` includes clients for **Crawl4AI** and **Exa**.
   - These are material to the architecture because they extend the research agent beyond local reasoning: Crawl4AI for web extraction/scraping and Exa for semantic search.
   - The research agent is the primary consumer of these integrations; they form the outbound I/O boundary to the wider web/knowledge layer.

8. **Persistence and task lifecycle**
   - The repo ships with a SQLite database file under `src/database/implementation_tracker.db`, which indicates local persistence is part of the system design.
   - `src/database.py`, `src/repositories/`, and `src/services/` split persistence access from business logic.
   - `task_service.py` and `task_repository.py` likely implement the lifecycle for task creation, status updates, and progress retrieval, while the database keeps execution history and runtime metrics.

9. **Data model and validation layer**
   - `src/schemas/` holds the structured models used across the system: unified models, database schemas, and transformation helpers.
   - The README notes **Pydantic v2**, so schema validation is an architectural boundary between external input, internal task state, and stored records.
   - This layer keeps the API, agents, and repositories consistent even as task state moves across the system.

10. **Configuration and behavior tuning**
   - `src/config/agents.yaml`, `src/config/orchestrator.yaml`, and `src/prompts/agent_prompts.yaml` externalize agent behavior and orchestration parameters.
   - This makes the system more data-driven: agent roles, prompt templates, and supervisor behavior are configured rather than hardcoded in one place.
   - For an architecture diagram, these files sit beside the supervisor/agent layer as the system’s behavioral configuration plane.

11. **Deployment model**
   - `docker-compose.yml`, `Dockerfile.api`, `frontend/Dockerfile`, and `nginx.conf` show a containerized multi-service deployment.
   - The deployment boundary is cleanly split into frontend, backend API/orchestrator, and the reverse proxy.
   - The README also implies environment-based secret injection for LLM and search API keys, so external credentials are part of runtime configuration rather than code.

12. **Operational support and documentation**
   - `docs/SYSTEM_OVERVIEW.md` and `docs/AGENT_TESTING_GUIDE.md` suggest there is explicit operational documentation around agent behavior and validation.
   - `src/utils/task_calculations.py` and `src/schemas/transformations.py` support task scoring/derivation and data normalization, which are likely used by the service/orchestration layer.

13. **End-to-end request flow**
   - A user interacts with the React dashboard.
   - The dashboard calls the FastAPI backend for task creation and status polling.
   - The backend persists the task, hands it to the supervisor, and the supervisor routes work to one or more specialized agents.
   - Agents may call external search/scraping services, update shared state, and write progress/results back through the service/repository layer into SQLite.
   - The frontend reads updated task state and displays execution progress, completion, and metrics.

14. **Key architectural takeaway**
   - The central design pattern is **supervisor-led, multi-agent orchestration with local persistence and a thin UI**.
   - If you are drawing the diagram, the most important boundaries are: browser/UI, proxy/edge, backend API, orchestration core, specialized agents, persistence, and external intelligence services.

Main entry points: [`src/supervisor.py`](https://github.com/shemayon/devpro-orchestrator/blob/main/src/supervisor.py) (Supervisor), [`src/core/agent_registry.py`](https://github.com/shemayon/devpro-orchestrator/blob/main/src/core/agent_registry.py) (Registry), [`src/api.py`](https://github.com/shemayon/devpro-orchestrator/blob/main/src/api.py) (API), [`src/services/task_service.py`](https://github.com/shemayon/devpro-orchestrator/blob/main/src/services/task_service.py) (Task service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui["Dashboard<br/>React UI<br/>[App.jsx]"]
  node_ui_boot["UI entry<br/>Vite app<br/>[main.jsx]"]
end

subgraph group_backend["Backend"]
  node_api["API<br/>[api.py]"]
  node_cli["CLI<br/>operator entrypoint<br/>[cli.py]"]
  node_supervisor["Supervisor<br/>task coordinator<br/>[supervisor.py]"]
  node_executor["Executor<br/>runtime runner"]
  node_tasksvc["Task service<br/>service layer<br/>[task_service.py]"]
  node_taskrepo["Task repo<br/>[task_repository.py]"]
  node_state["State<br/>[state.py]"]
  node_registry["Registry<br/>[agent_registry.py]"]
  node_protocol["Protocol<br/>agent contract<br/>[agent_protocol.py]"]
  node_research["Research<br/>agent<br/>[research_agent.py]"]
  node_coding["Coding<br/>agent<br/>[coding_agent.py]"]
  node_testing["Testing<br/>agent<br/>[testing_agent.py]"]
  node_docs_agent["Docs<br/>agent"]
  node_db[("SQLite<br/>local persistence")]
  node_config["Config<br/>[orchestrator.yaml]"]
end

subgraph group_edge["Edge"]
  node_proxy["Nginx<br/>reverse proxy<br/>[nginx.conf]"]
end

subgraph group_external["External"]
  node_search(("Exa<br/>search service<br/>[exa_client.py]"))
  node_crawl(("Crawl4AI<br/>scrape service<br/>[crawl4ai_client.py]"))
end

node_ui_boot -->|"mounts"| node_ui
node_ui -->|"requests"| node_proxy
node_proxy -->|"forwards API"| node_api
node_api -->|"uses"| node_tasksvc
node_cli -->|"starts"| node_supervisor
node_api -->|"submits work"| node_supervisor
node_tasksvc -->|"persists"| node_taskrepo
node_taskrepo -->|"stores"| node_db
node_supervisor -->|"runs via"| node_executor
node_supervisor -->|"updates"| node_state
node_supervisor -->|"discovers"| node_registry
node_supervisor -->|"adheres to"| node_protocol
node_registry -->|"includes"| node_research
node_registry -->|"includes"| node_coding
node_registry -->|"includes"| node_testing
node_registry -->|"includes"| node_docs_agent
node_research -->|"queries"| node_search
node_research -->|"scrapes"| node_crawl
node_supervisor -->|"reads"| node_config
node_tasksvc -->|"derives"| node_state

click node_ui "https://github.com/shemayon/devpro-orchestrator/blob/main/frontend/src/App.jsx"
click node_ui_boot "https://github.com/shemayon/devpro-orchestrator/blob/main/frontend/src/main.jsx"
click node_proxy "https://github.com/shemayon/devpro-orchestrator/blob/main/nginx.conf"
click node_api "https://github.com/shemayon/devpro-orchestrator/blob/main/src/api.py"
click node_cli "https://github.com/shemayon/devpro-orchestrator/blob/main/src/cli.py"
click node_supervisor "https://github.com/shemayon/devpro-orchestrator/blob/main/src/supervisor.py"
click node_executor "https://github.com/shemayon/devpro-orchestrator/blob/main/src/supervisor_executor.py"
click node_tasksvc "https://github.com/shemayon/devpro-orchestrator/blob/main/src/services/task_service.py"
click node_taskrepo "https://github.com/shemayon/devpro-orchestrator/blob/main/src/repositories/task_repository.py"
click node_state "https://github.com/shemayon/devpro-orchestrator/blob/main/src/core/state.py"
click node_registry "https://github.com/shemayon/devpro-orchestrator/blob/main/src/core/agent_registry.py"
click node_protocol "https://github.com/shemayon/devpro-orchestrator/blob/main/src/core/agent_protocol.py"
click node_research "https://github.com/shemayon/devpro-orchestrator/blob/main/src/agents/research_agent.py"
click node_coding "https://github.com/shemayon/devpro-orchestrator/blob/main/src/agents/coding_agent.py"
click node_testing "https://github.com/shemayon/devpro-orchestrator/blob/main/src/agents/testing_agent.py"
click node_docs_agent "https://github.com/shemayon/devpro-orchestrator/blob/main/src/agents/documentation_agent.py"
click node_db "https://github.com/shemayon/devpro-orchestrator/blob/main/src/database/implementation_tracker.db"
click node_config "https://github.com/shemayon/devpro-orchestrator/blob/main/src/config/orchestrator.yaml"
click node_search "https://github.com/shemayon/devpro-orchestrator/blob/main/src/integrations/exa_client.py"
click node_crawl "https://github.com/shemayon/devpro-orchestrator/blob/main/src/integrations/crawl4ai_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_ui_boot toneBlue
class node_api,node_cli,node_supervisor,node_executor,node_tasksvc,node_taskrepo,node_state,node_registry,node_protocol,node_research,node_coding,node_testing,node_docs_agent,node_db,node_config toneAmber
class node_proxy toneMint
class node_search,node_crawl toneRose
```

## Components

### Frontend

Browser dashboard and static UI assets

- [Dashboard](https://github.com/shemayon/devpro-orchestrator/blob/main/frontend/src/App.jsx): React UI · Operational frontend for task visibility and control · `frontend/src/App.jsx`
- [UI entry](https://github.com/shemayon/devpro-orchestrator/blob/main/frontend/src/main.jsx): Vite app · Frontend bootstrap and client startup · `frontend/src/main.jsx`

### Backend

Python API, orchestration, agents, and data access

- [API](https://github.com/shemayon/devpro-orchestrator/blob/main/src/api.py): FastAPI surface · HTTP interface for task creation and orchestration control · `src/api.py`
- [CLI](https://github.com/shemayon/devpro-orchestrator/blob/main/src/cli.py): operator entrypoint · Non-HTTP interface for local execution and administration · `src/cli.py`
- [Supervisor](https://github.com/shemayon/devpro-orchestrator/blob/main/src/supervisor.py): task coordinator · Main runtime scheduler that routes work across agents · `src/supervisor.py`
- [Executor](https://github.com/shemayon/devpro-orchestrator/blob/main/src/supervisor_executor.py): runtime runner · Executes supervisor-controlled steps and agent runs · `src/supervisor_executor.py`
- [Task service](https://github.com/shemayon/devpro-orchestrator/blob/main/src/services/task_service.py): service layer · Business logic for task lifecycle and progress updates · `src/services/task_service.py`
- [Task repo](https://github.com/shemayon/devpro-orchestrator/blob/main/src/repositories/task_repository.py): repository · Persistence access for task records and status · `src/repositories/task_repository.py`
- [State](https://github.com/shemayon/devpro-orchestrator/blob/main/src/core/state.py): workflow state · Shared orchestration state and task context · `src/core/state.py`
- [Registry](https://github.com/shemayon/devpro-orchestrator/blob/main/src/core/agent_registry.py): agent registry · Discovers and maps available agent capabilities · `src/core/agent_registry.py`
- [Protocol](https://github.com/shemayon/devpro-orchestrator/blob/main/src/core/agent_protocol.py): agent contract · Shared interface for agent execution and messaging · `src/core/agent_protocol.py`
- [Research](https://github.com/shemayon/devpro-orchestrator/blob/main/src/agents/research_agent.py): agent · Research agent for web search and extraction · `src/agents/research_agent.py`
- [Coding](https://github.com/shemayon/devpro-orchestrator/blob/main/src/agents/coding_agent.py): agent · Implementation agent for code changes and synthesis · `src/agents/coding_agent.py`
- [Testing](https://github.com/shemayon/devpro-orchestrator/blob/main/src/agents/testing_agent.py): agent · Validation agent for checks and test reasoning · `src/agents/testing_agent.py`
- [Docs](https://github.com/shemayon/devpro-orchestrator/blob/main/src/agents/documentation_agent.py): agent · Documentation agent for summaries and writeups · `src/agents/documentation_agent.py`
- [SQLite](https://github.com/shemayon/devpro-orchestrator/blob/main/src/database/implementation_tracker.db): local persistence · On-disk execution tracker and task history · `src/database/implementation_tracker.db`
- [Config](https://github.com/shemayon/devpro-orchestrator/blob/main/src/config/orchestrator.yaml): behavior config · Orchestrator, agent, and prompt configuration plane · `src/config/orchestrator.yaml`

### Edge

Public reverse proxy and container entrypoints

- [Nginx](https://github.com/shemayon/devpro-orchestrator/blob/main/nginx.conf): reverse proxy · Public entrypoint routing browser traffic and API requests · `nginx.conf`

### External

Third-party intelligence and search services

- [Exa](https://github.com/shemayon/devpro-orchestrator/blob/main/src/integrations/exa_client.py): search service · Semantic search integration for research workflows · `src/integrations/exa_client.py`
- [Crawl4AI](https://github.com/shemayon/devpro-orchestrator/blob/main/src/integrations/crawl4ai_client.py): scrape service · Web extraction integration used by research workflows · `src/integrations/crawl4ai_client.py`

## Connections

- UI entry → Dashboard: mounts · Client bootstrap renders the dashboard
- Dashboard → Nginx: requests · Browser traffic enters through the reverse proxy
- Nginx → API: forwards API · Proxy sends backend calls to the Python service
- API → Task service: uses · HTTP requests are handled through task service logic
- CLI → Supervisor: starts · CLI can invoke orchestration directly
- API → Supervisor: submits work · API hands tasks to the orchestration core
- Task service → Task repo: persists · Service layer writes and reads task records
- Task repo → SQLite: stores · Repository reads and writes SQLite state
- Supervisor → Executor: runs via · Supervisor delegates execution to the runtime runner
- Supervisor → State: updates · Supervisor maintains shared workflow state
- Supervisor → Registry: discovers · Supervisor resolves available agent capabilities
- Supervisor → Protocol: adheres to · Agent communication follows the shared contract
- Registry → Research: includes · Registry exposes the research agent
- Registry → Coding: includes · Registry exposes the coding agent
- Registry → Testing: includes · Registry exposes the testing agent
- Registry → Docs: includes · Registry exposes the documentation agent
- Research → Exa: queries · Research workflows use semantic search
- Research → Crawl4AI: scrapes · Research workflows use web extraction
- Supervisor → Config: reads · Behavior and prompts are driven by configuration
- Task service → State: derives · Service layer may compute or normalize task progress
