OrchestraFlow AI

Multi-Agent AI Project Planning, Coordination & Delivery Platform

OrchestraFlow AI is a full-stack project management platform where a real team of specialised AI agents - each with its own prompt, input schema, output schema, and execution record - plan, break down, risk-assess, and document your project, while you stay in control through a human-in-the-loop review workflow. It is not a chatbot wrapped in a dashboard: every "agent" is a separate, independently-executed piece of code, orchestrated deterministically.

Built by Oleh Datsyk.

---

Table of Contents

1. Overview
2. Why Multi-Agent
3. Agent Roles
4. Architecture
5. Orchestration Flow
6. Revision Flow
7. AI Providers
8. Provider Routing & Fallback
9. Project Management Features
10. Human-in-the-Loop
11. Technology Stack
12. Installation
13. Environment Variables
14. Local Startup
15. GitHub
16. Render Deployment
17. REST API
18. Security
19. Limitations
20. Future Improvements

---

Overview

You describe a project - its goal, deadline, budget, team size, constraints, and expected deliverables - and OrchestraFlow AI coordinates seven specialised agents (plus an optional eighth) to produce a phased plan, a task breakdown with dependencies, a risk register, resourcing guidance, a quality review, and final documentation. Everything is persisted to a real database, every agent run is logged, and every AI-generated suggestion is clearly labelled and stays editable or rejectable by you.

Why Multi-Agent

A single "do everything" prompt cannot reliably separate concerns, cannot be audited stage-by-stage, and cannot fail gracefully. OrchestraFlow AI instead:

• Gives each agent a narrow responsibility and only the context it needs (the Risk Agent never sees the Documentation Agent's job, for example).
• Lets the orchestrator, not an LLM, decide execution order, retries, fallback, and when to stop - computation an LLM would otherwise be asked to "simulate" unreliably.
• Uses deterministic code (not AI) for anything that is actually a graph or arithmetic problem: circular dependency detection, critical path, blocked/ready tasks, and the project health score.
• Produces structured, validated output at every stage, so a bad response is caught and retried/failed over instead of silently corrupting state.

Agent Roles

Agent	Responsibility	Input	Output Schema
Project Manager	Understands the goal, flags missing information, sets objectives, decides which agents are relevant	Project intake	ProjectManagerOutput
Planning	Converts the goal into phases and milestones with a timeline structure	Project + PM objectives	PlanningOutput
Task Breakdown	Breaks milestones into tasks with effort, skills, dependencies, DoD	Milestones	TaskBreakdownOutput
Risk Analyst	Identifies technical/timeline/resource/budget/dependency/security/scope risks	Project + milestones + tasks	RiskAnalysisOutput
Resource & Priority	Adds qualitative resourcing judgement on top of deterministic graph facts	Deterministic dependency-graph output	PriorityOutput
Quality Reviewer	Critically reviews the combined plan; drives the revision loop	Plan + tasks + risks	QualityReviewOutput
Documentation	Generates the charter, summaries, status report, executive summary	Final accepted state	DocumentationOutput
Technical Architect (optional)	Proposes a tech stack/architecture for software projects	Project intake	ArchitectOutput

Each agent is its own Python class in agents/, with its own system prompt, its own Pydantic input/output shape, and its own row in the agent_runs table - there is no single prompt pretending to be seven different roles.

Architecture

orchestraflow-ai/
├── app.py # FastAPI app - single entrypoint, serves API + frontend
├── orchestrator.py # Real orchestration layer (see below)
├── agents/ # One dedicated module per agent
│   ├── base.py # Shared BaseAgent contract + prompt-injection notice
│   ├── project_manager.py
│   ├── planner.py
│   ├── task_agent.py
│   ├── risk_agent.py
│   ├── priority_agent.py
│   ├── quality_agent.py
│   ├── documentation_agent.py
│   ├── architect_agent.py
│   └── registry.py
├── providers/ # AI provider abstraction
│   ├── base.py # AIProvider ABC: generate_text/generate_structured/health_check
│   ├── openai_provider.py
│   ├── anthropic_provider.py
│   ├── gemini_provider.py
│   └── router.py # Per-agent routing + automatic fallback + AI call logging
├── core/
│   ├── config.py # Environment-driven settings
│   ├── database.py # SQLAlchemy engine/session, auto-creates schema
│   ├── models.py # ORM tables (projects, tasks, risks, agent_runs, ...)
│   ├── schemas.py # Pydantic API + agent structured-output schemas
│   ├── dependency_engine.py # Deterministic graph algorithms (cycles, critical path, ...)
│   ├── health_score.py # Deterministic project health formula
│   └── templates.py # Non-AI project starter templates
├── static/ # Vanilla HTML/CSS/JS SaaS-style frontend (no build step)
├── tests/ # pytest suite (CRUD, cycles, fallback, full orchestration)
├── Start App.bat # Windows one-click startup
├── Start App (Mac).command # macOS one-click startup
└── render.yaml # Render Web Service deployment config

Orchestration Flow

orchestrator.py explicitly calls each agent in order, persists every execution, and passes only the structured context each stage needs:

Project Intake
   │
   ▼
Project Manager Agent ── flags missing info, sets objectives
   │
   ▼
┌─ Planning Agent ── phases + milestones
│      │
│      ▼
│  Task Breakdown Agent ── tasks + dependencies
│      │
│      ▼
│  Risk Analyst Agent ── risk register
│      │
│      ▼
│  Deterministic Dependency Engine ── cycles / critical path / ready / blocked (code, not AI)
│      │
│      ▼
│  Resource & Priority Agent ── annotates the deterministic facts
│      │
│      ▼
│  Quality Reviewer Agent ── approved / approved_with_changes / needs_revision
│      │
│      └──needs_revision──▶ (loop back to Planning, up to MAX_REVISIONS times)
│
▼ (once approved or revision limit hit)
Documentation Agent ── charter, summaries, status report, executive summary
   │
   ▼
Technical Architect Agent (optional, technical/software projects only)
   │
   ▼
Final Project State (persisted, reviewable, exportable)

Every stage's execution is written to agent_runs (who ran, which provider, how long, fallback used, safe output summary) and its validated structured output to agent_outputs - never the model's private reasoning.

Revision Flow

If the Quality Reviewer returns needs_revision, the orchestrator:

1. Extracts the concrete problems it raised.
2. Logs a Decision Log entry per problem ("Planning Agent will revise the plan to address: ...", actor = quality).
3. Re-runs Planning -> Task Breakdown -> Risk -> Priority -> Quality with those problems included as revision_notes in the agent prompts.
4. Repeats up to MAX_REVISIONS times (default 2).
5. If still not approved, stops cleanly with: "Agent workflow stopped because maximum revision limit was reached."

An independent MAX_AGENT_ITERATIONS safety net (default 25) bounds the total number of agent-stage executions in one workflow run, so a misbehaving loop can never run unbounded regardless of the revision count.

AI Providers

OrchestraFlow AI supports three independent AI providers behind one common interface (providers/base.py::AIProvider):

• OpenAI (openai SDK)
• Anthropic Claude (anthropic SDK)
• Google Gemini (google-generativeai SDK)

Every provider implements generate_text(), generate_structured() (which validates the response against a Pydantic schema and raises a normalized StructuredOutputError on failure), and health_check().

Provider Routing & Fallback

Each agent can be routed to a specific provider (openai / anthropic / gemini) or left as auto, via the Settings or AI Providers page (or PUT /api/settings/provider-routing). If the assigned provider fails, the orchestrator automatically retries (up to MAX_AGENT_RETRIES) and then falls through the configured chain (PRIMARY_AI_PROVIDER -> FALLBACK_AI_PROVIDER -> SECONDARY_FALLBACK_AI_PROVIDER). Every attempt is logged to ai_logs with a normalized error category (missing_key, invalid_key, rate_limit, quota, timeout, network, malformed_output, provider_outage). One provider failing never crashes the workflow - this is covered by tests/test_app.py.

Project Management Features

Projects, Milestones, Tasks (Kanban board), Task Dependencies (with deterministic cycle detection), Risk Register, Decision Log, Timeline view, a dependency graph (SVG), a transparent Project Health Score, Report/Document export (Markdown/HTML/TXT/JSON), and project templates (Software MVP, Website Launch, AI Project, Marketing Campaign, Research Project, Startup Launch). All of this works fully with zero AI keys configured.

Human-in-the-Loop

AI-generated milestones, tasks, and risks are created with ai_generated=true and accepted=false and are visibly labelled "✨ AI Suggested" in the UI. Nothing AI-generated silently overwrites your data - you Accept, Edit, or Delete each suggestion yourself. Missing-information items flagged by the Project Manager Agent become trackable Assumptions you can accept or dismiss.

Technology Stack

• Backend: Python 3.11+, FastAPI, SQLAlchemy, Pydantic v2, Uvicorn
• AI SDKs: openai, anthropic, google-generativeai
• Database: SQLite by default (auto-created), swappable for Postgres via DATABASE_URL
• Frontend: Vanilla HTML/CSS/JavaScript SPA (no Node.js, no build step)

Installation

Windows

1. Install Python 3.11+ (check "Add Python to PATH").
2. Double-click Start App.bat.
3. The script creates a virtual environment, installs dependencies, creates .env from .env.example, starts the server, and opens your browser at http://localhost:8000.

macOS

1. Install Python 3.11+ (brew install python@3.11 or python.org).
2. Make the script executable once: chmod +x "Start App (Mac).command".
3. Double-click Start App (Mac).command (or run it from Terminal).
4. It sets up the virtual environment, installs dependencies, starts the server, and opens your browser at http://localhost:8000.

Manual (any OS)

python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # then add your API keys (optional)
uvicorn app:app --host 127.0.0.1 --port 8000 --reload

Environment Variables

See .env.example for the full list. None are required to run the app - project management works fully without any AI key.

Variable	Purpose
OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY	Provider credentials (optional)
OPENAI_MODEL, ANTHROPIC_MODEL, GEMINI_MODEL	Model names per provider
PRIMARY_AI_PROVIDER, FALLBACK_AI_PROVIDER, SECONDARY_FALLBACK_AI_PROVIDER	Default fallback chain
MAX_AGENT_ITERATIONS, MAX_AGENT_RETRIES, MAX_REVISIONS	Loop/retry safety limits
MAX_PROJECT_TASKS	Hard cap on tasks per project
DATABASE_URL	Optional Postgres URL; defaults to local SQLite

Local Startup

Once running, open http://localhost:8000. The health check (GET /api/health) makes no AI call and simply confirms the server is up.

GitHub

git init
git add .
git commit -m "Initial commit: OrchestraFlow AI"
git branch -M main
git remote add origin https://github.com/<your-username>/orchestraflow-ai.git
git push -u origin main

.env is git-ignored by default - never commit real API keys.

Render Deployment

1. Push this repository to GitHub.
2. In Render, create a Web Service (not a Static Site) from the repo. It will auto-detect render.yaml, or configure manually:
   • Build Command: pip install -r requirements.txt
   • Start Command: uvicorn app:app --host 0.0.0.0 --port $PORT
3. In the Render dashboard's Environment tab, add whichever of OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY you have (all optional).
4. Deploy. SQLite works out of the box; note that its filesystem persistence on Render's free plan is not guaranteed across deploys/restarts - for durable data, set DATABASE_URL to a Render PostgreSQL instance (the codebase already supports this via SQLAlchemy with no code changes).

REST API

See app.py for the complete, current route list. Highlights:

GET    /api/health
GET    /api/dashboard
GET    /api/projects POST /api/projects
GET    /api/projects/{id} PUT/DELETE /api/projects/{id}
POST   /api/projects/{id}/run GET  /api/projects/{id}/workflow-status
GET    /api/agents POST /api/projects/{id}/agents/{name}/run
GET    /api/projects/{id}/milestones POST /api/projects/{id}/milestones
GET    /api/projects/{id}/tasks POST /api/projects/{id}/tasks
POST   /api/tasks/{id}/dependencies GET  /api/projects/{id}/dependency-graph
GET    /api/projects/{id}/risks POST /api/projects/{id}/risks
POST   /api/projects/{id}/reports/generate GET  /api/reports/{id}/download
GET    /api/ai/providers POST /api/ai/test/{provider}
GET    /api/settings PUT  /api/settings/provider-routing

Security

• API keys are read only from environment variables, never stored in the database, never returned by any API response, and never logged.
• Every agent's system prompt includes an explicit prompt-injection notice: project content is treated as untrusted data, wrapped in <untrusted_project_data> tags, and agents are instructed never to follow instructions embedded within it.
• No chain-of-thought is ever stored or displayed - only structured, validated final outputs and short factual activity summaries.

Limitations

• Structured-output validation catches malformed JSON but cannot verify factual correctness of AI-generated plans, tasks, or risks - always review before accepting.
• The dependency graph visualisation is intentionally lightweight (inline SVG) rather than a full graph-layout library.
• SQLite on Render's free tier is ephemeral storage; use a managed Postgres DATABASE_URL for anything you need to persist long-term.
• Provider health checks make a real (tiny) API call, so "Test" costs a minimal amount of provider quota.

Future Improvements

• WebSocket-based live agent activity instead of polling.
• Postgres-only production hardening (connection pooling, migrations via Alembic).
• Multi-user auth and per-user project scoping.
• Richer Gantt/critical-path visualisation.
• Plan versioning diff view (Plan v1 vs Plan v2).

---

Built by Oleh Datsyk.