How shemayon/devpro-orchestrator works
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: supervisor.py Supervisor · agent_registry.py Registry · api.py API · task_service.py Task service
Components 20
Frontend
Browser dashboard and static UI assets
Backend
Python API, orchestration, agents, and data access
- API · HTTP interface for task creation and orchestration control
src/api.py - CLI · Non-HTTP interface for local execution and administration
src/cli.py - Supervisor · Main runtime scheduler that routes work across agents
src/supervisor.py - Executor · Executes supervisor-controlled steps and agent runs
src/supervisor_executor.py - Task service · Business logic for task lifecycle and progress updates
src/services/task_service.py - Task repo · Persistence access for task records and status
src/repositories/task_repository.py - State · Shared orchestration state and task context
src/core/state.py - Registry · Discovers and maps available agent capabilities
src/core/agent_registry.py - Protocol · Shared interface for agent execution and messaging
src/core/agent_protocol.py - Research · Research agent for web search and extraction
src/agents/research_agent.py - Coding · Implementation agent for code changes and synthesis
src/agents/coding_agent.py - Testing · Validation agent for checks and test reasoning
src/agents/testing_agent.py - Docs · Documentation agent for summaries and writeups
src/agents/documentation_agent.py - SQLite · On-disk execution tracker and task history
src/database/implementation_tracker.db - Config · Orchestrator, agent, and prompt configuration plane
src/config/orchestrator.yaml
Edge
Public reverse proxy and container entrypoints
- Nginx · Public entrypoint routing browser traffic and API requests
nginx.conf
Connections 20
- 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