Orchestro — Architecture: how the ‘Trello for Claude Code’ works under the hood
TL;DR
- MCP Server (TypeScript): executes the flow goal → tasks → deps → code → learning, exposing ~60 tools to Claude Code.
- Web Dashboard (Next.js + React Flow): Kanban board, dependency graphs, event timeline, real-time via Socket.io.
- Claude Code: consumes MCP tools for analysis/implementation; agents move cards across columns as work happens.
- Supabase (PostgreSQL + RLS): the single source of truth with a complete audit trail and row-level security.
---
## Block view
[User/PM] ──(story)──▶ Dashboard
│
▼
MCP Server (Conductor)
┌──────── tasking / deps / analysis / history ───────┐
│ │
Claude Code ◀── MCP tools & prompts ──▶ Supabase (data & events)
│ │
└──── agents / “scrum master” ⇒ move cards (Socket) ──┘
---
## Components
1) MCP Server (TypeScript)
- Tools for: decompose_story, create/list/update_task, save_dependencies, prepare_task_for_execution, get_execution_prompt, add_feedback, detect_failure_patterns, get_task_history, and more.
- Scrum Master (auto): guardrails for states, dependencies, execution order, and consistency.
- Suggestions: proposes relevant agents/tools; syncs .claude/agents/.
- Safety & idempotency: validations, conflict checks, every mutation audited.
2) Web Dashboard (Next.js)
- Kanban + dependency graphs (React Flow); filters by story/task/status.
- Real-time via Socket.io: each server event updates the UI (card movement, risk flags, decision history).
- Timeline: decisions, status changes, analyses, code changes.
3) Claude Code (MCP client)
- Consumes Orchestro tools; gets context-rich prompts per task/feature.
- Agents (guardians/sub-agents) analyze, implement, and move cards via MCP calls.
4) Supabase (data layer)
- PostgreSQL with RLS; stores tasks, deps, resources, events, patterns, learnings.
- Triggers for pattern frequency, task history, and audit exports.
---
## End-to-end flow
1. Create Story (PM/Dev from the dashboard): “User logs in with email/password.”
2. decompose_story (MCP): generates technical tasks + initial dependencies (optional autoAnalyze).
3. save_dependencies: consolidates the graph + get_execution_order (topological sort).
4. prepare_task_for_execution: produces analysis prompts (files/impact areas, risks, helpful patterns).
5. get_execution_prompt: execution prompt for Claude (context, constraints, checklist).
6. Implementation (Claude/Dev): code & tests; record_code_change and record_decision.
7. Status & Board: record_status_transition → card moves (Socket.io), risks/indicators refresh.
8. Learning: add_feedback and detect_failure_patterns → future suggestions + mitigations.
---
## Data model (excerpt)
- projects, user_stories, tasks (JSONB metadata: assignee, priority, tags, category)
- task_dependencies (graph), resource_nodes / resource_edges (files, APIs, tables, etc.)
- events / history: task_history, status_transitions, decisions, code_changes, guardian_interventions
- knowledge: patterns, learnings, templates, pattern_frequency
- config: tech_stack, agents, mcp_tools
> Every action emits an auditable event.
---
## Security & trust
- Local-first: data lives in your Supabase project.
- RLS on + least-privilege access.
- Secrets via ENV only (no secrets in code).
- Full audit trail, exportable (compliance/GDPR friendly).
---
## Extensibility
- Add MCP tools: define schema + validation, register in mcp_tools.
- Custom agents: drop files in .claude/agents/ → sync_claude_code_agents.
- Patterns/Templates: enrich patterns, templates, learnings to cut friction.
- Hooks: wire Slack/Teams via event stream for notifications.
---
## Operations & performance
- Socket.io for live updates; light polling where needed.
- Indexes (GIN on JSONB) for sub-10ms queries on common task/event filters.
- Migrations via scripts; manual fallback for locked-down envs.
- Quick troubleshooting: dashboard health, Claude config checks, ENV sanity.
---
## Deploy
- Local dev
npx @orchestro/init
npm run dashboard (opens http://localhost:3000)
restart Claude Code and ask: “Show me orchestro tools”
- Self-host
Container with ENV: DATABASE_URL, SUPABASE_URL, SUPABASE_SERVICE_KEY, PORT.
- Multi-user/team
RLS + event stream per workspace; project/permission separation.
---
## Why this architecture
- Visibility (board + graphs) and executability (MCP) in the same loop.
- Claude-first: robust prompts, persistent context, agent/tool suggestions.
- Shared state (Supabase) with full history for retros and quality gates.
---
## Next steps (short)
- PM-friendly exports & stakeholder notifications
- Lightweight metrics (velocity, aging, blockers)
- Slack/Teams integrations
- Advanced auto-orchestration (path suggestions, conflict resolution)
---
## Links
- Website: orchestro.org
- Repo: github.com/khaoss85/mcp-orchestro
If you want a deeper dive (schema diagrams, event examples), tell me and I’ll add them here.
