Software Design Document: CODITECT Task Orchestrator
1. Executive Summary
The CODITECT Task Orchestrator is an atomic task management and agentic orchestration system that decomposes large project plans into database-stored tasks with intelligent agent assignment, dependency resolution, and execution tracking.
1.1 Key Metrics
| Metric | Value |
|---|---|
| Token Reduction | 84% (95K → 15.5K per session) |
| Task Decomposition | 500+ atomic tasks |
| Agent Matching | Semantic + historical affinity |
| Dependency Types | 3 (blocks, informs, relates) |
2. C4 Architecture Diagrams
2.1 System Context (Level 1)
┌─────────────────────────────────────────────────────────────────────────────┐
│ SYSTEM CONTEXT │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Human │ │ Claude │ │
│ │ Developer │ │ Code CLI │ │
│ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │
│ │ Uses Uses │ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ CODITECT Task Orchestrator │ │
│ │ │ │
│ │ Decomposes project plans into atomic tasks, manages │ │
│ │ agent assignment, tracks execution, and learns from │ │
│ │ outcomes to improve future task routing. │ │
│ │ │ │
│ └───────────────────────────┬───────────────────────────────── │ │
│ │ │ │
│ ┌────────────────────┼────────────────────┐ │ │
│ │ │ │ │ │
│ ▼ ▼ ▼ │ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ CODITECT │ │ CODITECT │ │ GitHub │ │ │
│ │Cloud Backend│ │ Core │ │ API │ │ │
│ │[External] │ │[Framework] │ │ [External] │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
2.2 Container Diagram (Level 2)
┌─────────────────────────────────────────────────────────────────────────────┐
│ CONTAINER DIAGRAM │
│ [CODITECT Task Orchestrator] │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Task Orchestrator │ │
│ │ ┌────────────────────────────────────────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │
│ │ │ │ REST API │ │ Task │ │ Agent Dispatcher │ │ │ │
│ │ │ │ Server │ │ Decomposer │ │ │ │ │ │
│ │ │ │ │ │ │ │ • Affinity scoring │ │ │ │
│ │ │ │ FastAPI │ │ Markdown │ │ • Circuit breaker │ │ │ │
│ │ │ │ Python │ │ Parser │ │ • Load balancing │ │ │ │
│ │ │ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ └────────────────┼─────────────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ▼ │ │ │
│ │ │ ┌───────────────────────┐ │ │ │
│ │ │ │ Dependency Resolver │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ • Graph traversal │ │ │ │
│ │ │ │ • Ready task calc │ │ │ │
│ │ │ │ • Blocker detection │ │ │ │
│ │ │ └───────────┬───────────┘ │ │ │
│ │ │ │ │ │ │
│ │ └──────────────────────────┼──────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌──────────────────────────┼──────────────────────────────────┐ │ │
│ │ │ Data Layer │ │ │ │
│ │ │ ▼ │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │
│ │ │ │ PostgreSQL │ │ pgvector │ │ Neo4j │ │ │ │
│ │ │ │ │ │ │ │ (Optional) │ │ │ │
│ │ │ │ Tasks │ │ Embeddings │ │ Dependency Graph │ │ │ │
│ │ │ │ Executions │ │ Similarity │ │ Visualization │ │ │ │
│ │ │ │ Affinities │ │ Search │ │ │ │ │ │
│ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
2.3 Component Diagram (Level 3)
┌─────────────────────────────────────────────────────────────────────────────┐
│ COMPONENT DIAGRAM │
│ [Task Orchestrator - Core] │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ API Layer (src/api/) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │ │
│ │ │ /tasks │ │ /agents │ │/dependencies│ │ /import │ │ │
│ │ │ routes │ │ routes │ │ routes │ │ routes │ │ │
│ │ │ │ │ │ │ │ │ │ │ │
│ │ │ CRUD + Query│ │ Recommend │ │ Graph API │ │ Bulk ops │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └─────┬──────┘ │ │
│ │ │ │ │ │ │ │
│ │ └────────────────┼────────────────┼────────────────┘ │ │
│ └──────────────────────────┼────────────────┼──────────────────────────┘ │
│ │ │ │
│ ┌──────────────────────────┼────────────────┼──────────────────────────┐ │
│ │ Core Layer (src/core/) │ │ │
│ │ ▼ ▼ │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐ │ │
│ │ │ models.py │ │ │
│ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │
│ │ │ │AtomicTask │ │TaskDep │ │AgentAffin │ │TaskExec │ │ │ │
│ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │SQLAlchemy │ │SQLAlchemy │ │SQLAlchemy │ │SQLAlchemy │ │ │ │
│ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │ │
│ │ └─────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ decomposer.py │ │dependency_ │ │ task_queue.py │ │ │
│ │ │ │ │resolver.py │ │ │ │ │
│ │ │ • Markdown parse│ │ │ │ • Priority queue │ │ │
│ │ │ • Task classify │ │ • Graph queries │ │ • Ready task fetch │ │ │
│ │ │ • Embedding gen │ │ • Blocker detect│ │ • Batch operations │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Workers Layer (src/workers/) │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │
│ │ │ dispatcher.py │ │ executor.py │ │metrics_collector.py │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ • Agent match │ │ • Task exec │ │ • Usage tracking │ │ │
│ │ │ • Affinity calc │ │ • Retry logic │ │ • Performance agg │ │ │
│ │ │ • Circuit break │ │ • Timeout mgmt │ │ • Learning update │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
3. Component Specifications
3.1 API Server (FastAPI)
| Attribute | Value |
|---|---|
| Framework | FastAPI 0.109+ |
| Runtime | Python 3.11+ |
| Port | 8080 |
| Auth | JWT via CODITECT auth service |
Responsibilities:
- REST API endpoints for task management
- Request validation (Pydantic schemas)
- Rate limiting
- OpenAPI documentation
3.2 Task Decomposer
| Attribute | Value |
|---|---|
| Input | Markdown project plans |
| Output | AtomicTask records |
| Parser | Regex-based markdown |
| Classifier | Rule-based + ML |
Responsibilities:
- Parse PILOT plan markdown
- Extract task hierarchy (Track.Section.Task.Subtask)
- Classify task types and domains
- Generate embeddings for semantic search
- Infer dependencies from context
3.3 Agent Dispatcher
| Attribute | Value |
|---|---|
| Algorithm | Weighted affinity scoring |
| Fallback | Default track agents |
| Protection | Circuit breaker pattern |
Affinity Score Formula:
score = (
semantic_similarity * 0.4 +
historical_success_rate * 0.3 +
domain_expertise * 0.2 +
availability * 0.1
)
3.4 Dependency Resolver
| Attribute | Value |
|---|---|
| Storage | PostgreSQL + optional Neo4j |
| Algorithm | DAG traversal |
| Caching | Ready task materialized view |
Responsibilities:
- Compute task readiness
- Detect blocking dependencies
- Identify parallelizable tasks
- Visualize dependency graph
3.5 Metrics Collector
| Attribute | Value |
|---|---|
| Metrics | Execution time, tokens, success rate |
| Aggregation | Exponential moving average |
| Storage | agent_task_affinity table |
Responsibilities:
- Track execution outcomes
- Update agent affinity scores
- Generate performance reports
- Feed learning loop
4. Data Flow Diagrams
4.1 Task Import Flow
┌─────────────────────────────────────────────────────────────────┐
│ TASK IMPORT FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ PILOT Plan │───────▶│ Decomposer │───────▶│ Database │ │
│ │ (Markdown) │ parse │ │ insert │ PostgreSQL │ │
│ └─────────────┘ └──────┬──────┘ └────────────┘ │
│ │ │
│ │ generate │
│ ▼ │
│ ┌─────────────┐ ┌────────────┐ │
│ │ OpenAI │───────▶│ pgvector │ │
│ │ Embeddings │ store │ │ │
│ └─────────────┘ └────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
4.2 Task Execution Flow
┌─────────────────────────────────────────────────────────────────┐
│ TASK EXECUTION FLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ /orient │───────▶│ Orchestrator│───────▶│ Agent │ │
│ │ Command │ request│ API │ dispatch│ Dispatch │ │
│ └─────────────┘ ready └──────┬──────┘ └─────┬──────┘ │
│ │ │ │
│ │ query │ execute │
│ ▼ ▼ │
│ ┌─────────────┐ ┌────────────┐ │
│ │ Task Queue │ │Claude Code │ │
│ │ (Ready │◀───────│ Session │ │
│ │ Tasks) │ result └────────────┘ │
│ └─────────────┘ │
│ │ │
│ │ update │
│ ▼ │
│ ┌─────────────┐ │
│ │ Metrics │ │
│ │ Collector │ │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
4.3 Learning Feedback Loop
┌─────────────────────────────────────────────────────────────────┐
│ LEARNING FEEDBACK LOOP │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ Execution │ │
│ │ Complete │ │
│ └──────┬──────┘ │
│ │ │
│ │ record │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │task_execu- │───────▶│ Metrics │───────▶│agent_task_ │ │
│ │tions table │aggregate│ Collector │ update │ affinity │ │
│ └─────────────┘ └─────────────┘ └─────┬──────┘ │
│ │ │
│ │ inform │
│ ▼ │
│ ┌────────────┐ │
│ │ Agent │ │
│ │ Dispatcher │ │
│ │ (next run) │ │
│ └────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
5. Interface Specifications
5.1 Internal Interfaces
| Interface | Provider | Consumer | Protocol |
|---|---|---|---|
| Task API | API Server | /orient command | REST/JSON |
| Agent API | API Server | Agent Dispatcher | REST/JSON |
| DB Access | PostgreSQL | All components | SQLAlchemy |
| Vector Search | pgvector | Task Queue | SQL |
5.2 External Interfaces
| Interface | System | Protocol | Purpose |
|---|---|---|---|
| Cloud Sync | CODITECT Cloud | REST/JWT | Task synchronization |
| PILOT Plan | File System | Read | Source document |
| Session Log | CODITECT Core | File | Execution context |
| Embeddings | OpenAI API | REST | Vector generation |
6. Deployment Architecture
6.1 Production Deployment
┌─────────────────────────────────────────────────────────────────┐
│ PRODUCTION DEPLOYMENT │
│ (Google Cloud) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Cloud Run │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ Task Orchestrator API (Python/FastAPI) │ │ │
│ │ │ │ │ │
│ │ │ • Auto-scaling 0-10 instances │ │ │
│ │ │ • 512MB memory, 1 vCPU │ │ │
│ │ │ • Concurrency: 100 requests/instance │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ VPC Connector │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Cloud SQL │ │
│ │ ┌──────────────────────┐ ┌──────────────────────────┐ │ │
│ │ │ PostgreSQL 15 │ │ pgvector extension │ │ │
│ │ │ │ │ │ │ │
│ │ │ • db-f1-micro │ │ • Vector similarity │ │ │
│ │ │ • 3.75GB RAM │ │ • HNSW index │ │ │
│ │ │ • 10GB SSD │ │ │ │ │
│ │ └──────────────────────┘ └──────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Cloud Memorystore │ │
│ │ ┌──────────────────────────────────────────────────────┐ │ │
│ │ │ Redis │ │ │
│ │ │ • Rate limiting cache │ │ │
│ │ │ • Session state (optional) │ │ │
│ │ └──────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
6.2 Local Development
┌─────────────────────────────────────────────────────────────────┐
│ LOCAL DEVELOPMENT │
│ (Docker Compose) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ orchestrator-api │ │
│ │ • Port 8080 │ │
│ │ • Hot reload enabled │ │
│ │ • Volume mount: ./src:/app/src │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────┼─────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ db │ │ redis │ │ neo4j │ │
│ │ │ │ │ │ (optional)│ │
│ │ pgvector/ │ │ redis:7 │ │ │ │
│ │ pgvector │ │ alpine │ │ │ │
│ │ :pg15 │ │ │ │ │ │
│ │ │ │ Port 6379 │ │ Port 7474 │ │
│ │ Port 5432 │ │ │ │ Port 7687 │ │
│ └───────────┘ └───────────┘ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
7. Security Considerations
7.1 Authentication
- All API requests require valid JWT from CODITECT auth service
- Tenant isolation via
X-Tenant-IDheader - API keys for service-to-service communication
7.2 Authorization
| Action | Required Role |
|---|---|
| Read tasks | orchestrator:read |
| Create/update tasks | orchestrator:write |
| Admin operations | orchestrator:admin |
7.3 Data Protection
- All data at rest encrypted (Cloud SQL encryption)
- TLS 1.3 for all network communication
- Sensitive fields (execution logs) stored with field-level encryption
- Audit logging for all state changes
8. Performance Considerations
8.1 Response Time Targets
| Endpoint | P50 Target | P99 Target |
|---|---|---|
| GET /tasks/ready | 50ms | 200ms |
| POST /tasks/{id}/start | 30ms | 100ms |
| GET /tasks/search | 100ms | 500ms |
| GET /dependencies/graph | 150ms | 750ms |
8.2 Throughput Targets
| Metric | Target |
|---|---|
| Concurrent users | 100 |
| Requests per second | 500 |
| Tasks per import batch | 1000 |
8.3 Optimization Strategies
- Materialized view for ready tasks
- Connection pooling (PgBouncer)
- Vector index (IVFFlat) for semantic search
- Query result caching (Redis)
- Pagination for list endpoints
9. Monitoring & Observability
9.1 Metrics
| Metric | Type | Source |
|---|---|---|
| Request latency | Histogram | FastAPI middleware |
| Task completion rate | Counter | Application |
| Agent success rate | Gauge | Application |
| Database connections | Gauge | PostgreSQL |
| Circuit breaker state | Gauge | Application |
9.2 Logging
| Level | Use Case |
|---|---|
| ERROR | Failures, exceptions |
| WARN | Circuit breaker trips, retries |
| INFO | Task state transitions |
| DEBUG | Query execution, cache hits |
9.3 Alerts
| Alert | Condition | Severity |
|---|---|---|
| High error rate | >5% 5xx responses | Critical |
| Circuit open | Any agent circuit open | Warning |
| Slow queries | P99 >1s | Warning |
| Connection pool exhausted | Available <5% | Critical |
10. Appendix
10.1 Technology Stack
| Component | Technology | Version |
|---|---|---|
| API Framework | FastAPI | 0.109+ |
| ORM | SQLAlchemy | 2.0+ |
| Database | PostgreSQL | 15+ |
| Vector Extension | pgvector | 0.5+ |
| Graph DB (optional) | Neo4j | 5.x |
| Cache | Redis | 7+ |
| Containerization | Docker | 24+ |
| Orchestration | Docker Compose / Cloud Run | - |
10.2 Related Documents
Design Documents:
- tdd-task-orchestrator.md - Technical specifications
Local ADRs:
- ADR-069: Atomic Task Management System
- ADR-070: Task Dependency Graph
- ADR-071: Agent-Task Matching
- ADR-072: Execution Tracking
- ADR-073: Learning Feedback Loop
External ADRs (coditect-core/internal/architecture/adrs/):
- ADR-068: Large Project Plan Token Economics (motivation)
- ADR-052: Intent-Aware Context Management
- ADR-053: Cloud Context Sync Architecture
- ADR-054: Track Nomenclature Extensibility
Document Version: 1.0.0 Last Updated: January 13, 2026 Author: Claude Opus 4.5 Review Status: Draft