443 lines
16 KiB
Markdown
443 lines
16 KiB
Markdown
# 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
|
|
```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)
|
|
}
|
|
```
|
|
|
|
## API Architecture
|
|
|
|
### MCP Server Extension
|
|
|
|
#### New MCP Tools for Task Management
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```sql
|
|
-- 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
|
|
```sql
|
|
-- 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. |