Task Model Documentation

Overview

The Task model represents individual work items within projects, supporting both human and AI agent assignments. It provides flexible tracking for various methodologies (Agile, Waterfall, Hybrid) and enables the core work breakdown structure of CODITECT.

Model Structure

Core Fields

Field	Type	Description	Constraints
task_id	UUID	Unique task identifier	Primary key, auto-generated
tenant_id	UUID	Associated tenant	Foreign key to Tenant
project_id	UUID	Parent project	Foreign key to Project
parent_id	UUID (Optional)	Parent task for subtasks	Self-referential FK
title	String	Task title/summary	Required, max 255 chars
description	String (Optional)	Detailed description	Markdown supported
status	TaskStatus (Enum)	Current state	Required
priority	TaskPriority (Enum)	Urgency level	Required
task_type	TaskType (Enum)	Category of work	Required
assignee_id	UUID (Optional)	Assigned member	FK to Member (human or agent)
assignee_type	AssigneeType (Optional)	Type of assignee	Human, Agent, or System
reporter_id	UUID	Task creator	Foreign key to User
story_points	i32 (Optional)	Agile estimation	1-100 typical range
estimated_hours	f32 (Optional)	Time estimate	In hours
actual_hours	f32 (Optional)	Time tracked	Auto-calculated or manual
due_date	DateTime (Optional)	Deadline	Must be future date
tags	Vec	Labels/categories	For filtering/grouping
created_at	DateTime	Creation timestamp	Auto-set
updated_at	DateTime	Last modification	Auto-updated
metadata	JSON (Optional)	Extension data	Agent configs, custom fields

TaskStatus Enum

enum TaskStatus {
    Todo,           // Not started
    InProgress,     // Active work
    UnderReview,    // Awaiting review/QA
    Done,           // Completed
    Blocked,        // Dependencies blocking
    Cancelled       // Won't be completed
}

TaskPriority Enum

enum TaskPriority {
    Low,        // Can wait
    Medium,     // Normal priority
    High,       // Urgent
    Critical    // Drop everything
}

TaskType Enum

enum TaskType {
    UserStory,      // User-facing feature
    Bug,            // Defect fix
    Feature,        // New capability
    Epic,           // Large feature set
    SubTask,        // Part of larger task
    TechnicalDebt,  // Code improvement
    Documentation,  // Docs/wiki work
    Research        // Investigation/spike
}

AssigneeType Enum

enum AssigneeType {
    Human,      // Human team member
    Agent,      // AI agent
    System      // Automated system
}

Database Schema

Primary Storage Pattern

Key: /{tenant_id}/tasks/{task_id}
Value: JSON serialized Task object

Secondary Indexes

Project tasks: /{tenant_id}/tasks_by_project/{project_id} -> [task_ids]
Assignee tasks: /{tenant_id}/tasks_by_assignee/{assignee_id} -> [task_ids]
Status index: /{tenant_id}/tasks_by_status/{project_id}/{status} -> [task_ids]
Parent-child: /{tenant_id}/subtasks/{parent_id} -> [task_ids]
Due date: /{tenant_id}/tasks_by_due_date/{YYYY-MM-DD} -> [task_ids]

Example Data

{
  "task_id": "9f8e7d6c-5b4a-3c2d-1e0f-123456789abc",
  "tenant_id": "8eba182c-2ad7-44c5-b0ab-5a1915b6b98a",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "parent_id": null,
  "title": "Implement user authentication endpoint",
  "description": "Create POST /api/auth/login endpoint with JWT support",
  "status": "InProgress",
  "priority": "High",
  "task_type": "Feature",
  "assignee_id": "ec6d3130-6de2-4cc6-9c7a-90d25b2b1f09",
  "assignee_type": "Human",
  "reporter_id": "a03e2ace-de82-4210-a014-500b94ed6d29",
  "story_points": 5,
  "estimated_hours": 8.0,
  "actual_hours": 3.5,
  "due_date": "2025-09-01T17:00:00Z",
  "tags": ["backend", "security", "sprint-23"],
  "created_at": "2025-08-25T10:30:00Z",
  "updated_at": "2025-08-29T14:45:00Z",
  "metadata": null
}

AI Agent Integration

Agent Assignment

When assignee_type is "Agent":

{
  "assignee_id": "agent-456-uuid",
  "assignee_type": "Agent",
  "metadata": {
    "agent_config": {
      "model": "claude-3-opus",
      "temperature": 0.7,
      "max_tokens": 4000,
      "tools": ["code_writer", "test_runner", "documentation"]
    },
    "execution_context": {
      "repository_url": "https://github.com/org/repo",
      "branch": "feature/auth-endpoint",
      "environment": "development"
    }
  }
}

System Tasks

Automated tasks with assignee_type as "System":

{
  "assignee_type": "System",
  "metadata": {
    "automation_type": "scheduled",
    "schedule": "0 2 * * *",
    "script": "backup_database.sh"
  }
}

Related Code

Source Files

• Model Definition: /src/models/task.rs
• Repository: /src/db/repositories/task_repository.rs
• Assignment Model: /src/models/task_assignment.rs
• API Handler: /src/api/handlers/task_handlers.rs
• DTO: /src/api/dto/task.rs
• Tests: /src/db/repositories/tests/task_repository_tests.rs

Key Methods

impl Task {
    fn new(tenant_id: Uuid, project_id: Uuid, ...) -> Self
    fn assign_to(&mut self, assignee_id: Uuid, assignee_type: AssigneeType)
    fn transition_status(&mut self, new_status: TaskStatus) -> Result<()>
    fn add_subtask(&self, subtask: Task) -> Result<()>
    fn calculate_progress(&self) -> f32
    fn is_overdue(&self) -> bool
}

Repository Operations

trait TaskRepository {
    async fn create(&self, task: &Task) -> Result<()>
    async fn get_by_id(&self, tenant_id: &Uuid, task_id: &Uuid) -> Result<Option<Task>>
    async fn list_by_project(&self, tenant_id: &Uuid, project_id: &Uuid) -> Result<Vec<Task>>
    async fn list_by_assignee(&self, tenant_id: &Uuid, assignee_id: &Uuid) -> Result<Vec<Task>>
    async fn update(&self, task: &Task) -> Result<()>
    async fn delete(&self, tenant_id: &Uuid, task_id: &Uuid) -> Result<()>
}

API Endpoints

Create Task

• POST /api/projects/{project_id}/tasks
• Body: CreateTaskRequest
• Response: Task
• Auth: Project member

Get Task

• GET /api/tasks/{task_id}
• Response: Task with subtasks
• Auth: Project member or viewer

Update Task

• PUT /api/tasks/{task_id}
• Body: UpdateTaskRequest
• Response: Task
• Auth: Assignee or Manager

List Tasks

• GET /api/tasks?project_id={uuid}&assignee_id={uuid}&status={status}
• Response: Vec<TaskSummary>
• Auth: Authenticated user

Assign Task

• POST /api/tasks/{task_id}/assign
• Body: { assignee_id, assignee_type }
• Response: Task
• Auth: Manager or self-assignment

Relationships

Many-to-One

• Tenant: Each task belongs to one tenant
• Project: Each task belongs to one project
• Reporter: Created by one user
• Parent Task: Optional parent for subtasks

One-to-One (Optional)

• Assignee: Can be assigned to one member (human or agent)

One-to-Many

• Subtasks: Task can have multiple subtasks
• Comments: Task discussions/updates
• Attachments: Related files/documents
• Work Logs: Time tracking entries

Business Rules

Task Creation

1. Must belong to active project
2. Title required, description optional
3. Reporter must be project member
4. Initial status is "Todo"
5. Due date must be within project timeline

Status Transitions

Todo -> InProgress -> UnderReview -> Done
  |         |              |
  |         +-> Blocked    +-> InProgress (rework)
  |         |
  +-------> Cancelled

Assignment Rules

1. Human Assignment

   • Must be project member
   • Can self-assign if permitted
   • Notification sent on assignment

2. Agent Assignment

   • Agent must be configured for project
   • Appropriate permissions required
   • Execution context provided

3. System Assignment

   • For automated/scheduled tasks
   • No manual intervention needed
   • Logs execution results

Hierarchy Rules

• Subtasks inherit project from parent
• Parent task status affected by subtasks
• Cannot delete parent with active subtasks
• Epic type can have UserStory children

Performance Considerations

Indexing Strategy

1. Project Index: Fast project task lists
2. Assignee Index: Personal task lists
3. Status Index: Kanban board queries
4. Due Date Index: Deadline tracking

Query Optimization

• Denormalized summary for lists
• Lazy load descriptions
• Batch subtask queries
• Cache frequently accessed tasks

Agile Integration

Story Points

• Fibonacci sequence (1,2,3,5,8,13,21)
• Used for velocity calculation
• Aggregated at epic level

Sprint Support

"metadata": {
  "sprint_id": "sprint-23",
  "sprint_start": "2025-08-19",
  "sprint_end": "2025-09-02",
  "acceptance_criteria": [
    "Endpoint responds with JWT",
    "Invalid credentials return 401",
    "Rate limiting implemented"
  ]
}

Automation Features

Workflow Triggers

• Status changes trigger workflows
• Due date reminders
• SLA breach alerts
• Completion notifications

AI Agent Execution

• Agent picks up assigned tasks
• Executes based on metadata config
• Updates status and logs
• Requests review when complete

Security Considerations

1. Access Control

   • View: Project members only
   • Edit: Assignee or manager
   • Delete: Manager only
   • Cross-project access blocked

2. Data Privacy

   • Tasks inherit project security
   • Sensitive data in metadata encrypted
   • Audit trail for all changes
   • Agent access logged

Future Extensions

1. Dependencies

   • Task-to-task dependencies
   • Critical path analysis
   • Gantt chart support

2. Advanced Estimation

   • Three-point estimation
   • Monte Carlo simulation
   • Historical velocity analysis

3. AI Enhancement

   • Auto-assignment based on skills
   • Effort prediction
   • Risk identification

---

Last Updated: 2025-08-29 Version: 1.0