directus-task-management/docs/architecture.md

Directus Task Management Suite - System Architecture

System Architecture Overview

High-Level Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude Code   │    │     BMad Core    │    │   Task Master   │
│     Agents      │    │   Methodology    │    │   CLI System    │
│   (10+ agents)  │    │  (Templates &    │    │  (Granular      │
│                 │    │   Workflows)     │    │   Tracking)     │
└─────────┬───────┘    └─────────┬────────┘    └─────────┬───────┘
          │                      │                       │
          │              ┌───────▼────────┐              │
          │              │                │              │
          └─────────────►│   Directus     │◄─────────────┘
                         │ Task Management│
                         │     Suite      │
                         │                │
                         └───────┬────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
    ┌─────────▼─────────┐ ┌─────▼─────┐ ┌─────────▼─────────┐
    │  Directus CMS     │ │ MCP Server│ │   Web Interface   │
    │ (enias.zeabur.app)│ │ Extension │ │ (Admin Dashboard) │
    │                   │ │ (40+ tools│ │                   │
    └───────────────────┘ │ + new TM) │ └───────────────────┘
                          └───────────┘

Data Architecture

Core Collections Design

1. projects Collection

-- Project hierarchy and organization
projects {
  id: uuid (primary key)
  name: string (required, indexed)
  description: text
  status: enum ['active', 'on_hold', 'completed', 'archived']
  parent_project: uuid (foreign key to projects.id, nullable)
  repository_url: string (nullable)
  bmad_workflow_type: enum ['greenfield', 'brownfield', 'maintenance']
  task_master_project_id: string (nullable, for integration)
  priority: enum ['low', 'medium', 'high', 'critical']
  start_date: date (nullable)
  due_date: date (nullable)
  completion_percentage: integer (0-100, computed field)
  created_by: uuid (foreign key to directus_users.id)
  assigned_to: uuid (foreign key to directus_users.id, nullable)
  metadata: json (flexible field for project-specific data)
  tags: array of strings (m2m relation to project_tags)
  created_at: timestamp (auto)
  updated_at: timestamp (auto)
}

2. tasks Collection

-- Core task entity with rich metadata
tasks {
  id: uuid (primary key)
  title: string (required, indexed)
  description: text
  status: uuid (foreign key to task_statuses.id)
  priority: enum ['lowest', 'low', 'medium', 'high', 'highest']
  task_type: enum ['feature', 'bug', 'enhancement', 'research', 'maintenance']
  complexity: enum ['trivial', 'minor', 'major', 'critical']
  story_points: integer (1-21, fibonacci scale)
  
  -- Project relationships
  project: uuid (foreign key to projects.id, required)
  parent_task: uuid (foreign key to tasks.id, nullable)
  epic: uuid (foreign key to tasks.id, nullable, for BMad epics)
  
  -- Assignment and ownership
  created_by: uuid (foreign key to directus_users.id)
  assigned_to: uuid (foreign key to directus_users.id, nullable)
  ai_agent_assigned: string (nullable, for Claude Code agent assignment)
  reviewer: uuid (foreign key to directus_users.id, nullable)
  
  -- Time and progress
  estimated_hours: decimal (nullable)
  actual_hours: decimal (computed from time_entries)
  progress_percentage: integer (0-100)
  start_date: date (nullable)
  due_date: date (nullable)
  completed_at: timestamp (nullable)
  
  -- Integration fields
  task_master_id: string (nullable, for Task Master sync)
  github_issue_url: string (nullable)
  bmad_story_id: string (nullable)
  external_refs: json (flexible for various integrations)
  
  -- AI and automation
  ai_generated: boolean (default false)
  ai_context: json (prompts, agent data, etc.)
  auto_status_updates: boolean (default false)
  
  -- Metadata
  acceptance_criteria: text
  definition_of_done: text
  notes: text
  attachments: array of uuids (foreign key to directus_files)
  tags: array of strings (m2m relation to task_tags)
  
  created_at: timestamp (auto)
  updated_at: timestamp (auto)
}

3. task_statuses Collection

-- Customizable status definitions aligned with workflows
task_statuses {
  id: uuid (primary key)
  name: string (required, unique)
  slug: string (required, unique, indexed)
  description: text
  color: string (hex color for UI)
  icon: string (icon identifier)
  category: enum ['todo', 'in_progress', 'review', 'done', 'blocked']
  is_final: boolean (default false)
  auto_transition_rules: json (conditions for automatic status changes)
  workflow_type: enum ['bmad', 'task_master', 'github', 'custom']
  sort_order: integer
  active: boolean (default true)
  created_at: timestamp (auto)
  updated_at: timestamp (auto)
}

4. task_dependencies Collection

-- Task relationship and dependency management
task_dependencies {
  id: uuid (primary key)
  dependent_task: uuid (foreign key to tasks.id)
  dependency_task: uuid (foreign key to tasks.id)
  dependency_type: enum ['blocks', 'relates_to', 'duplicates', 'subtask_of']
  is_hard_dependency: boolean (default true)
  created_by: uuid (foreign key to directus_users.id)
  created_at: timestamp (auto)
  
  -- Ensure no circular dependencies
  CONSTRAINT unique_dependency UNIQUE (dependent_task, dependency_task)
  CONSTRAINT no_self_dependency CHECK (dependent_task != dependency_task)
}

5. task_time_entries Collection

-- Time tracking and progress data
task_time_entries {
  id: uuid (primary key)
  task: uuid (foreign key to tasks.id)
  user: uuid (foreign key to directus_users.id, nullable)
  ai_agent: string (nullable, for automated time tracking)
  description: text
  hours: decimal (required)
  entry_type: enum ['manual', 'automatic', 'estimated', 'actual']
  work_type: enum ['development', 'testing', 'review', 'research', 'meeting']
  billable: boolean (default false)
  started_at: timestamp (nullable)
  ended_at: timestamp (nullable)
  created_at: timestamp (auto)
}

6. task_templates Collection

-- Reusable task patterns for BMad methodology
task_templates {
  id: uuid (primary key)
  name: string (required, indexed)
  description: text
  template_type: enum ['bmad_epic', 'bmad_story', 'feature', 'bug_fix', 'maintenance']
  workflow_stage: enum ['planning', 'development', 'testing', 'deployment']
  
  -- Template data
  title_template: string (with placeholders)
  description_template: text
  acceptance_criteria_template: text
  default_priority: enum ['lowest', 'low', 'medium', 'high', 'highest']
  default_complexity: enum ['trivial', 'minor', 'major', 'critical']
  estimated_hours: decimal (nullable)
  
  -- BMad integration
  bmad_agent_assignment: string (nullable)
  required_skills: array of strings
  checklist_items: json (array of checklist items)
  
  -- Usage tracking
  usage_count: integer (default 0)
  last_used: timestamp (nullable)
  
  created_by: uuid (foreign key to directus_users.id)
  created_at: timestamp (auto)
  updated_at: timestamp (auto)
}

Integration Collections

7. task_ai_contexts Collection

-- AI agent context and prompt data
task_ai_contexts {
  id: uuid (primary key)
  task: uuid (foreign key to tasks.id)
  ai_agent_type: string (claude_code, bmad_agent, etc.)
  context_type: enum ['prompt', 'result', 'feedback', 'error']
  context_data: json (prompts, responses, metadata)
  execution_timestamp: timestamp
  success: boolean
  tokens_used: integer (nullable)
  execution_time_ms: integer (nullable)
  created_at: timestamp (auto)
}

8. task_bmad_workflows Collection

-- BMad methodology integration
task_bmad_workflows {
  id: uuid (primary key)
  task: uuid (foreign key to tasks.id)
  bmad_phase: enum ['analysis', 'planning', 'development', 'review', 'deployment']
  bmad_agent: string (pm, architect, dev, qa, etc.)
  workflow_step: string
  step_status: enum ['pending', 'in_progress', 'completed', 'skipped']
  step_data: json (agent-specific data and results)
  execution_order: integer
  started_at: timestamp (nullable)
  completed_at: timestamp (nullable)
  created_at: timestamp (auto)
}

9. task_external_refs Collection

-- Links to external systems (Task Master, GitHub, etc.)
task_external_refs {
  id: uuid (primary key)
  task: uuid (foreign key to tasks.id)
  system_type: enum ['task_master', 'github', 'gitlab', 'jira', 'linear']
  external_id: string (required)
  external_url: string (nullable)
  sync_status: enum ['synced', 'out_of_sync', 'error']
  last_sync: timestamp (nullable)
  sync_data: json (system-specific sync information)
  bidirectional_sync: boolean (default false)
  created_at: timestamp (auto)
  updated_at: timestamp (auto)
}

Supporting Collections

10. project_tags and task_tags Collections

-- Tag management for organization
project_tags {
  id: uuid (primary key)
  name: string (required, unique)
  color: string (hex color)
  description: text (nullable)
  created_at: timestamp (auto)
}

task_tags {
  id: uuid (primary key)
  name: string (required, unique)
  color: string (hex color)
  description: text (nullable)
  created_at: timestamp (auto)
}

API Architecture

MCP Server Extension

New MCP Tools for Task Management

// Task CRUD operations
mcp__directus__create_task(data: TaskCreateData)
mcp__directus__update_task(id: string, data: TaskUpdateData)
mcp__directus__get_task(id: string, include_relations?: boolean)
mcp__directus__list_tasks(filters?: TaskFilters, pagination?: Pagination)
mcp__directus__delete_task(id: string)

// Project operations
mcp__directus__create_project(data: ProjectCreateData)
mcp__directus__get_project_tasks(project_id: string, filters?: TaskFilters)
mcp__directus__update_project_progress(project_id: string)

// Status and workflow management
mcp__directus__transition_task_status(task_id: string, new_status: string)
mcp__directus__get_available_transitions(task_id: string)
mcp__directus__bulk_status_update(task_ids: string[], new_status: string)

// Dependency management
mcp__directus__add_task_dependency(task_id: string, dependency_id: string, type: DependencyType)
mcp__directus__get_task_dependencies(task_id: string)
mcp__directus__validate_dependency_graph(task_ids: string[])

// AI integration
mcp__directus__create_ai_task(prompt: string, context: AIContext)
mcp__directus__update_task_ai_context(task_id: string, context_data: AIContextData)
mcp__directus__get_ai_task_suggestions(project_id: string, current_context: string)

// BMad integration
mcp__directus__create_bmad_epic(epic_data: BMadEpicData)
mcp__directus__create_bmad_stories(epic_id: string, story_count: number)
mcp__directus__update_bmad_workflow_step(task_id: string, step_data: BMadStepData)

// Template operations
mcp__directus__apply_task_template(template_id: string, variables: TemplateVariables)
mcp__directus__create_task_template(template_data: TaskTemplateData)

// Integration operations
mcp__directus__sync_with_task_master(project_id: string)
mcp__directus__create_github_integration(task_id: string, repo_url: string)
mcp__directus__bulk_import_tasks(source: ImportSource, mapping: FieldMapping)

// Reporting and analytics
mcp__directus__get_project_analytics(project_id: string, date_range?: DateRange)
mcp__directus__get_task_completion_metrics(filters?: ReportFilters)
mcp__directus__generate_velocity_report(team_id: string, sprint_period: number)

Integration Architecture

Task Master Integration

Task Master Projects ←→ Directus Projects
Task Master Tasks ←→ Directus Tasks
Task Master Status ←→ Directus Status Workflow

Sync Strategy:
- Bidirectional sync with conflict resolution
- Task Master remains CLI-focused
- Directus provides web UI and AI integration
- Sync triggers on both systems for real-time updates

BMad Methodology Integration

BMad Templates → Directus Task Templates
BMad Workflows → Directus Workflow Steps
BMad Agents → Directus AI Context Tracking

Integration Points:
- Epic creation from BMad planning phase
- Story breakdown using BMad agent workflows
- Status transitions aligned with BMad methodology
- Agent assignment and context preservation

Claude Code Agent Integration

Agent Workflows → Task Context Updates
Task Assignments → Agent Work Context
Task Completion → Automated Status Updates

Integration Patterns:
- Tasks provide context for agent operations
- Agents update progress automatically
- Task dependencies inform agent prioritization
- Agent results captured in AI context collections

Performance and Scalability Design

Database Optimization

• Indexing Strategy: Composite indexes on frequently queried combinations
• Partitioning: Tasks partitioned by project and date for large datasets
• Caching Layer: Redis cache for frequently accessed task data
• Query Optimization: GraphQL query complexity limits and batching

API Performance

• Pagination: Cursor-based pagination for large result sets
• Field Selection: GraphQL field selection to minimize data transfer
• Caching: HTTP caching headers and ETags for unchanged data
• Rate Limiting: Per-user and per-agent rate limiting

Integration Performance

• Async Processing: Background jobs for heavy operations (sync, reports)
• Batch Operations: Bulk APIs for multiple task operations
• Event-Driven Updates: WebSocket notifications for real-time updates
• Circuit Breakers: Fallback strategies for external system failures

Future Evolution: Strategic + Tactical Web Management

Phase 3: Strategic Planning Collections

-- Future collections for web-based BMad planning management
bmad_projects {
  id: uuid (primary key)
  name: string (required)
  description: text
  bmad_phase: enum ['planning', 'development', 'review', 'complete']
  planning_documents: json (PRDs, architecture, research)
  user_stories: relation (link to tactical tasks)
  methodology_compliance: json (BMad workflow tracking)
  strategic_metrics: json (high-level KPIs)
  created_at: timestamp (auto)
}

planning_documents {
  id: uuid (primary key)
  title: string (required)
  content: text (rich text/markdown)
  document_type: enum ['prd', 'architecture', 'research', 'validation']
  bmad_project: uuid (foreign key to bmad_projects.id)
  version: integer (document versioning)
  status: enum ['draft', 'review', 'approved', 'archived']
  created_at: timestamp (auto)
}

Enhanced Task Schema for Cross-Level Links

-- Enhanced tasks collection for strategic/tactical integration
tasks {
  -- ... existing fields ...
  strategic_level: enum ['epic', 'user_story', 'task', 'subtask']
  bmad_project: uuid (foreign key to bmad_projects.id, nullable)
  parent_user_story: uuid (foreign key to tasks.id, nullable)
  strategic_importance: enum ['low', 'medium', 'high', 'critical']
  -- ... rest of schema
}

This architecture provides a robust foundation for the Directus task management suite while maintaining seamless integration with existing systems and supporting future evolution to unified strategic and tactical web management.