directus-task-management/docs/architecture/data-architecture.md

# Data Architecture

## Core Collections Design

### 1. `projects` Collection
```sql
-- 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
```sql
-- 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
```sql
-- 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
```sql
-- 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
```sql
-- 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
```sql
-- 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
```sql
-- 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
```sql
-- 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
```sql
-- 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
```sql
-- 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)
}
```