# 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.