Autonomous Orchestration System - Architecture Diagram
Visual Reference for Implementation Created: December 18, 2025
System Overview
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ AUTONOMOUS ORCHESTRATOR │
│ (Master Controller) │
│ scripts/autonomous-orchestrator.py │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Control Loop │ │ Checkpoint Mgr │ │ Error Handler │ │
│ │ - Get tasks │ │ - Milestones │ │ - Retry logic │ │
│ │ - Spawn agents │ │ - State saves │ │ - Circuit break │ │
│ │ - Monitor │ │ - Recovery │ │ - Escalation │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │
└────────────┬────────────────────────┬────────────────────┬─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────┐ ┌─────────────────────┐ ┌──────────────────┐
│ Sync Daemon │ │ Task Dispatcher │ │ Agent Executor │
│ (Bidirectional) │ │ (Smart Routing) │ │ (Per-Task) │
└──────┬──────────────┘ └──────┬──────────────┘ └────┬─────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌──────────────────────────────────────────────────────────────────────┐
│ DATA LAYER │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ context.db (SQLite) │ │
│ │ │ │
│ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │
│ │ │ v2_tasks │ │ v2_features │ │ v2_epics │ │ │
│ │ │ (122 rows) │ │ (35 rows) │ │ (10 rows) │ │ │
│ │ └─────────────┘ └──────────────┘ └──────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────┐ ┌────────────────────────────────┐ │ │
│ │ │ task_dependencies│ │ agent_execution_log │ │ │
│ │ │ (DAG storage) │ │ (audit trail) │ │ │
│ │ └──────────────────┘ └────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ V2-TASKLIST-WITH-CHECKBOXES.md │ │
│ │ (Human-readable tasklist) │ │
│ └─────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────┘
▲ ▲ ▲
│ │ │
│ │ │
┌──────┴──────────┐ ┌──────────┴──────────┐ ┌───────┴────────────┐
│ File Watcher │ │ Dependency Graph │ │ Claude Code API │
│ (watchdog) │ │ (DAG resolver) │ │ (Agent invoke) │
└─────────────────┘ └─────────────────────┘ └────────────────────┘
Component Flow Diagram
┌─────────────┐
│ Human │
│ Updates │
│ Markdown │
└──────┬──────┘
│
│ Manual edit
▼
┌─────────────────────────────────────┐
│ V2-TASKLIST-WITH-CHECKBOXES.md │
│ │
│ - [ ] T001.005: Create discovery │
│ - [ ] T001.006: Implement agent │
│ - [x] T001.003: Activation status │ ✅
└──────┬──────────────────────────────┘
│
│ File change detected (watchdog)
▼
┌─────────────────────┐
│ Sync Daemon │
│ sync-daemon.py │
│ │
│ 1. Parse markdown │
│ 2. Calculate diff │
│ 3. Update database │
└──────┬──────────────┘
│
│ SQL UPDATE
▼
┌──────────────────────────────────────┐
│ context.db │
│ │
│ UPDATE v2_tasks │
│ SET status='completed', │
│ completed_at=NOW() │
│ WHERE task_id='T001.003' │
└──────┬───────────────────────────────┘
│
│ Database change detected (polling)
▼
┌─────────────────────┐
│ Task Dispatcher │
│ task-dispatcher.py │
│ │
│ 1. Query pending │
│ 2. Check deps │
│ 3. Assign agent │
└──────┬──────────────┘
│
│ Task assignment
▼
┌─────────────────────┐
│ Agent Executor │
│ agent-executor.py │
│ │
│ Agent: devops-eng │
│ Task: T001.005 │
│ Status: in_progress│
└──────┬──────────────┘
│
│ Claude Code API call
▼
┌─────────────────────────────────┐
│ Claude Sonnet 4.5 │
│ (Specialized Agent) │
│ │
│ "You are devops-engineer..." │
│ "Task: Create discovery..." │
│ "Execute and report..." │
└──────┬──────────────────────────┘
│
│ Task execution
▼
┌─────────────────────────────────┐
│ Execution Results │
│ │
│ ✅ Files created │
│ ✅ Tests passed │
│ ✅ Documentation updated │
└──────┬──────────────────────────┘
│
│ Update status
▼
┌──────────────────────────────────┐
│ context.db │
│ │
│ UPDATE v2_tasks │
│ SET status='completed' │
│ WHERE task_id='T001.005' │
└──────┬───────────────────────────┘
│
│ Sync to markdown
▼
┌──────────────────────────────────┐
│ V2-TASKLIST-WITH-CHECKBOXES.md │
│ │
│ - [x] T001.005: Create discovery│ ✅
│ - [ ] T001.006: Implement agent │
└──────────────────────────────────┘
│
│ Visual feedback
▼
┌──────────────────────────────────┐
│ Progress Dashboard │
│ (Web UI) │
│ │
│ Completed: 30/122 (24%) │
│ Active: 3 agents running │
└──────────────────────────────────┘
Dependency Resolution Flow
┌─────────────────────────────────────────────────────────────┐
│ Dependency Graph │
│ │
│ T001.009 │
│ Deploy RabbitMQ │
│ [completed] │
│ │ │
│ ├─────────────┬──────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ T001.010 T001.011 T001.012 │
│ Task Queue Priority Circuit │
│ [pending] [blocked] [blocked] │
│ │ │
│ ▼ │
│ T001.014 │
│ Test delegation │
│ [blocked - waiting for T001.010, T001.011, T001.012] │
│ │
└─────────────────────────────────────────────────────────────┘
Algorithm:
1. Parse task descriptions for "depends on", "after", "T\d{3}\.\d{3}"
2. Build adjacency list: graph[T001.009] = [T001.010, T001.011, T001.012]
3. Before dispatching T001.010:
- Check: Is T001.009 completed? ✅ Yes → Dispatch
4. Before dispatching T001.014:
- Check: Are T001.010, T001.011, T001.012 completed? ❌ No → Block
5. When T001.012 completes:
- Check: Are all dependencies now satisfied? ✅ Yes → Unblock T001.014
Sync Daemon Architecture
┌─────────────────────────────────────────────────────────────┐
│ Sync Daemon │
│ sync-daemon.py │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Main Thread (Coordinator) │ │
│ │ │ │
│ │ - Start file watcher thread │ │
│ │ - Start database poller thread │ │
│ │ - Monitor health │ │
│ │ - Handle graceful shutdown │ │
│ └────────────┬─────────────────┬───────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌──────────────────┐ │
│ │ File Watcher │ │ DB Poller │ │
│ │ Thread │ │ Thread │ │
│ │ │ │ │ │
│ │ watchdog lib │ │ SELECT MAX(...) │ │
│ │ on_modified() │ │ Every 5 seconds │ │
│ └────────┬────────┘ └──────────┬───────┘ │
│ │ │ │
│ │ Change detected │ Change detected │
│ ▼ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ Debounce Queue │ │
│ │ (2-second delay) │ │
│ │ │ │
│ │ - Prevents rapid repeated syncs │ │
│ │ - Batches multiple changes │ │
│ └────────────────┬───────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ Sync Executor │ │
│ │ │ │
│ │ if markdown_changed: │ │
│ │ sync_plan_to_db() │ │
│ │ if db_changed: │ │
│ │ sync_db_to_plan() │ │
│ └────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────┘
Concurrency Control:
- Use threading.Lock() for sync operations
- Prevent simultaneous markdown → DB and DB → markdown
- SQLite WAL mode for better concurrent read/write
Task Dispatcher Logic
┌─────────────────────────────────────────────────────────────┐
│ Task Dispatcher │
│ task-dispatcher.py │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 1. Query Available Tasks │ │
│ │ │ │
│ │ SELECT * FROM v2_tasks │ │
│ │ WHERE status='pending' │ │
│ │ AND NOT EXISTS ( │ │
│ │ SELECT 1 FROM task_dependencies │ │
│ │ WHERE dependency_status != 'completed' │ │
│ │ ) │ │
│ │ ORDER BY │ │
│ │ CASE priority │ │
│ │ WHEN 'P0' THEN 0 │ │
│ │ WHEN 'P1' THEN 1 │ │
│ │ WHEN 'P2' THEN 2 │ │
│ │ ELSE 3 │ │
│ │ END │ │
│ │ LIMIT 1 │ │
│ └──────────────────┬───────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 2. Extract Task Metadata │ │
│ │ │ │
│ │ task_id: T001.005 │ │
│ │ description: "Create discovery service..." │ │
│ │ priority: P0 │ │
│ │ epic_id: E001 (Core Platform) │ │
│ └──────────────────┬───────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 3. Pattern Matching │ │
│ │ │ │
│ │ patterns = { │ │
│ │ r'discovery|redis': 'devops-engineer', │ │
│ │ r'security|auth': 'security-specialist', │ │
│ │ r'api|backend': 'backend-development' │ │
│ │ } │ │
│ │ │ │
│ │ Match: "discovery" → devops-engineer ✅ │ │
│ └──────────────────┬───────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 4. Return Assignment │ │
│ │ │ │
│ │ { │ │
│ │ 'task_id': 'T001.005', │ │
│ │ 'agent_type': 'devops-engineer', │ │
│ │ 'priority': 'P0', │ │
│ │ 'estimated_hours': 32 │ │
│ │ } │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────┘
Agent Executor State Machine
┌─────────────────────────────────────────────────────────────┐
│ Agent Executor │
│ agent-executor.py │
│ │
│ ┌──────────┐ │
│ │ PENDING │ Initial state │
│ └────┬─────┘ │
│ │ │
│ │ executor.start() │
│ ▼ │
│ ┌──────────────────┐ │
│ │ IN_PROGRESS │ │
│ │ │ │
│ │ 1. Build prompt │ │
│ │ 2. Invoke agent │ │
│ │ 3. Parse result │ │
│ └────┬─────────────┘ │
│ │ │
│ ├─────────────┬────────────────┐ │
│ │ Success │ Failure │ Timeout │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │COMPLETED │ │ BLOCKED │ │ TIMEOUT │ │
│ │ │ │ │ │ │ │
│ │status= │ │status= │ │retry_count++ │ │
│ │completed │ │blocked │ │ │ │
│ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │
│ │ │ │ │
│ │ │ │ retry_count < 3? │
│ │ │ ├─Yes─→ IN_PROGRESS │
│ │ │ └─No──→ FAILED │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────────────────┐ │
│ │ Database Update │ │
│ │ │ │
│ │ UPDATE v2_tasks │ │
│ │ SET status=?, ... │ │
│ │ WHERE task_id=? │ │
│ └────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────┐ │
│ │ Sync to Markdown │ │
│ │ (via sync daemon) │ │
│ └────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────┘
Orchestrator Control Loop
┌──────────────────────────────────────────────────────────────┐
│ Autonomous Orchestrator │
│ autonomous-orchestrator.py │
│ │
│ START │
│ │ │
│ ├─→ Start sync daemon │
│ ├─→ Start dispatcher │
│ ├─→ Initialize state │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ MAIN LOOP (while running) │ │
│ │ │ │
│ │ ┌────────────────────────────────┐ │ │
│ │ │ 1. Check Agent Capacity │ │ │
│ │ │ if active < max_concurrent: │ │ │
│ │ └────────┬───────────────────────┘ │ │
│ │ ▼ │ │
│ │ ┌────────────────────────────────┐ │ │
│ │ │ 2. Get Next Task │ │ │
│ │ │ task = dispatcher.next() │ │ │
│ │ └────────┬───────────────────────┘ │ │
│ │ ▼ │ │
│ │ ┌────────────────────────────────┐ │ │
│ │ │ 3. Spawn Executor │ │ │
│ │ │ executor = AgentExecutor() │ │ │
│ │ │ executor.start() # Thread │ │ │
│ │ └────────┬───────────────────────┘ │ │
│ │ ▼ │ │
│ │ ┌────────────────────────────────┐ │ │
│ │ │ 4. Monitor Active Agents │ │ │
│ │ │ for agent in active: │ │ │
│ │ │ if agent.done(): │ │ │
│ │ │ handle_completion() │ │ │
│ │ └────────┬───────────────────────┘ │ │
│ │ ▼ │ │
│ │ ┌────────────────────────────────┐ │ │
│ │ │ 5. Retry Failed Tasks │ │ │
│ │ │ retry_with_backoff() │ │ │
│ │ └────────┬───────────────────────┘ │ │
│ │ ▼ │ │
│ │ ┌────────────────────────────────┐ │ │
│ │ │ 6. Check Milestones │ │ │
│ │ │ if epic_complete(): │ │ │
│ │ │ create_checkpoint() │ │ │
│ │ └────────┬───────────────────────┘ │ │
│ │ ▼ │ │
│ │ ┌────────────────────────────────┐ │ │
│ │ │ 7. Update Metrics │ │ │
│ │ │ prometheus_metrics.update() │ │ │
│ │ └────────┬───────────────────────┘ │ │
│ │ │ │ │
│ │ └─────→ sleep(1) ─────┐ │ │
│ │ │ │ │
│ └─────────────────────────────────┘ │ │
│ ▲ │ │
│ └─────────────────────────────────┘ │
│ │
│ SHUTDOWN SIGNAL │
│ │ │
│ ├─→ Stop accepting new tasks │
│ ├─→ Wait for active agents to complete │
│ ├─→ Stop sync daemon │
│ ├─→ Create final checkpoint │
│ └─→ EXIT │
│ │
└──────────────────────────────────────────────────────────────┘
Monitoring & Observability Stack
┌─────────────────────────────────────────────────────────────┐
│ Monitoring Architecture │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Autonomous Orchestrator │ │
│ │ │ │
│ │ prometheus_client.Counter() │ │
│ │ prometheus_client.Gauge() │ │
│ │ prometheus_client.Histogram() │ │
│ └────────────────┬─────────────────────────────────┘ │
│ │ │
│ │ HTTP /metrics endpoint │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Prometheus Server │ │
│ │ (localhost:9090) │ │
│ │ │ │
│ │ - Scrape metrics every 15s │ │
│ │ - Store time-series data │ │
│ │ - Alert on thresholds │ │
│ └────────────────┬─────────────────────────────────┘ │
│ │ │
│ │ PromQL queries │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Grafana Dashboard │ │
│ │ (localhost:3000) │ │
│ │ │ │
│ │ ┌────────────────────────────────────────┐ │ │
│ │ │ Task Completion Rate (tasks/hour) │ │ │
│ │ │ ▓▓▓▓▓▓▓░░░░░░░░ 1.2 /hr │ │ │
│ │ └────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────────────────────────────┐ │ │
│ │ │ Active Agents (gauge) │ │ │
│ │ │ █ devops-engineer (1) │ │ │
│ │ │ █ security-specialist (2) │ │ │
│ │ │ █ backend-development (1) │ │ │
│ │ └────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌────────────────────────────────────────┐ │ │
│ │ │ Dispatch Latency (p95) │ │ │
│ │ │ 3.2s (target: <5s) ✅ │ │ │
│ │ └────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────┘
Metrics Exposed:
- coditect_tasks_total (counter)
- coditect_tasks_completed (counter)
- coditect_tasks_failed (counter)
- coditect_active_agents (gauge)
- coditect_dispatch_latency_seconds (histogram)
- coditect_orchestrator_uptime_seconds (gauge)
Deployment Architecture (Production)
┌─────────────────────────────────────────────────────────────┐
│ GKE Cluster │
│ (coditect-prod) │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Orchestrator Pod │ │
│ │ (Deployment, replicas: 1) │ │
│ │ │ │
│ │ Container: orchestrator:latest │ │
│ │ - autonomous-orchestrator.py │ │
│ │ - sync-daemon.py │ │
│ │ - task-dispatcher.py │ │
│ │ - agent-executor.py │ │
│ │ │ │
│ │ Volumes: │ │
│ │ - PVC: orchestrator-data (context.db) │ │
│ │ - ConfigMap: orchestrator-config.json │ │
│ │ - HostPath: /markdown (tasklist) │ │
│ └────────────┬─────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Redis Service │ │
│ │ (Task Queue Backend) │ │
│ │ │ │
│ │ - Deployment, replicas: 1 │ │
│ │ - PVC: redis-data (persistence) │ │
│ │ - Port: 6379 │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Prometheus Service │ │
│ │ (Already deployed) │ │
│ │ │ │
│ │ - Scrapes orchestrator:9090/metrics │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Grafana Service │ │
│ │ (Already deployed) │ │
│ │ │ │
│ │ - Dashboard: coditect-orchestrator │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────┘
Service Mesh:
- LoadBalancer: 136.110.206.100 (already allocated)
- Ingress: orchestrator.coditect.ai (future)
- Internal DNS: orchestrator-service.default.svc.cluster.local
Error Handling Flow
┌─────────────────────────────────────────────────────────────┐
│ Error Scenarios │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Agent Execution Failure │ │
│ │ │ │
│ │ Try: │ │
│ │ executor.execute_task() │ │
│ │ Except TaskExecutionError: │ │
│ │ retry_count++ │ │
│ │ if retry_count < 3: │ │
│ │ sleep(2^retry_count) # Exponential backoff │ │
│ │ requeue_task() │ │
│ │ else: │ │
│ │ mark_as_failed() │ │
│ │ alert_operator() │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Database Lock (Concurrent Write) │ │
│ │ │ │
│ │ Try: │ │
│ │ cursor.execute(UPDATE_SQL) │ │
│ │ Except sqlite3.OperationalError: │ │
│ │ sleep(random(0.1, 0.5)) # Random jitter │ │
│ │ retry_up_to_5_times() │ │
│ │ if still_locked: │ │
│ │ log_error("DB contention high") │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Circular Dependency Detected │ │
│ │ │ │
│ │ graph.detect_cycles() │ │
│ │ if cycle_found: │ │
│ │ rollback_dependency_creation() │ │
│ │ return Error("Circular dependency: T->A->B->T")│ │
│ │ alert_operator() │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Agent Timeout (>2 hours) │ │
│ │ │ │
│ │ executor.start_time = now() │ │
│ │ while executor.running: │ │
│ │ if now() - start_time > 7200: # 2 hours │ │
│ │ executor.kill() │ │
│ │ mark_as_timeout() │ │
│ │ log_error(f"Agent timeout: {task_id}") │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────┘
Created: December 18, 2025 Status: Design Complete See Full Plan: AUTONOMOUS-ORCHESTRATION-PLAN.md See Summary: ORCHESTRATION-IMPLEMENTATION-SUMMARY.md