Tasks - Work Management & Scheduling

Domain: Tasks Location: api/nextango/apps/tasks/ Last Updated: 2025-12-21

Overview

The Tasks app provides comprehensive work management capabilities including task creation, assignment workflows, priority tracking, deadline management, delivery scheduling, and completion tracking. Supports store operations, employee workflows, and delivery logistics with Sanity CMS synchronization.

Core Documentation

FileDescription
models.mdTask, DeliverySchedule, TaskAssignment models
serializers.mdTask API serializers and validation
views.mdTask management API endpoints
services.mdTaskService, scheduling, assignment logic
signals.mdTask lifecycle signals and notifications
examples.mdUsage examples and patterns

Key Features

Task Management

  • Task creation - Create tasks with title, description, priority
  • Task assignment - Assign tasks to employees
  • Priority levels - Low, medium, high, urgent priority
  • Due dates - Deadline tracking and overdue detection
  • Status tracking - Pending, in_progress, completed, cancelled
  • Task dependencies - Tasks can depend on other tasks

Assignment Workflows

  • Employee assignment - Assign to specific employees
  • Role-based assignment - Assign to managers, staff, etc.
  • Store-specific tasks - Tasks scoped to specific stores
  • Reassignment - Transfer tasks between employees
  • Bulk assignment - Assign multiple tasks at once

Priority & Scheduling

  • Priority-based sorting - Urgent tasks bubble to top
  • Deadline tracking - Track due dates and overdue tasks
  • Recurring tasks - Daily, weekly, monthly recurring tasks
  • Time estimates - Estimated completion time
  • Actual time tracking - Track actual time spent

Delivery Scheduling

  • Delivery schedules - Schedule deliveries to stores
  • Time windows - Delivery time windows
  • Delivery status - Pending, in_transit, delivered, cancelled
  • Store assignment - Delivery destination stores
  • Notes and instructions - Delivery-specific notes

Completion Tracking

  • Completion status - Mark tasks complete
  • Completion notes - Document completion details
  • Completion photos - Photo evidence of completion
  • Completion timestamp - Track when completed
  • Completion verification - Manager verification

Notifications & Alerts

  • Assignment notifications - Notify on task assignment
  • Deadline alerts - Alert before deadline
  • Overdue alerts - Notify when task overdue
  • Completion notifications - Notify on task completion
  • Reassignment notifications - Notify on reassignment

API Endpoints

Task Management

EndpointMethodDescriptionDoc Reference
/tasks/GET, POST, PUT, PATCH, DELETETask CRUD operationsviews.md
/tasks/{id}/GET, PUT, PATCH, DELETEIndividual task operationsviews.md
/tasks/{id}/assign/POSTAssign task to employeeviews.md
/tasks/{id}/complete/POSTMark task completeviews.md
/tasks/{id}/cancel/POSTCancel taskviews.md

Task Filtering

EndpointMethodDescriptionDoc Reference
/tasks/by_store/GETGet tasks for storeviews.md
/tasks/by_employee/GETGet employee tasksviews.md
/tasks/overdue/GETGet overdue tasksviews.md
/tasks/high_priority/GETGet high priority tasksviews.md
/tasks/pending/GETGet pending tasksviews.md

Delivery Scheduling

EndpointMethodDescriptionDoc Reference
/delivery-schedules/GET, POST, PUT, PATCH, DELETEDelivery schedule CRUDviews.md
/delivery-schedules/{id}/GET, PUT, PATCH, DELETEIndividual schedule operationsviews.md
/delivery-schedules/by_store/GETGet store delivery schedulesviews.md
/delivery-schedules/{id}/mark_delivered/POSTMark delivery completeviews.md

Full endpoint documentation: views.md

v0.70.0: Delivery schedule endpoints (/delivery-schedules/*) are now active. The DeliverySchedule model stores recurring or one-off delivery windows per store, including capacity limits and cutoff times.

Architecture Highlights

Task State Machine

Tasks flow through well-defined states:

PENDING → IN_PROGRESS → COMPLETED
    ↓                        ↑
CANCELLED ←──────────────────┘

Read more: models.md

Priority-Based Organization

Tasks organized by priority for efficient workflow:

  • Urgent (priority 4) - Immediate attention required
  • High (priority 3) - Important, complete today
  • Medium (priority 2) - Standard tasks
  • Low (priority 1) - Nice to have

Read more: services.md

Service Layer Architecture

Task logic centralized in service classes:

  • TaskService - Task lifecycle management
  • AssignmentService - Assignment and reassignment logic
  • SchedulingService - Delivery scheduling
  • NotificationService - Task notifications

Read more: services.md

Signal-Based Notifications

Signals trigger notifications on task events:

  • Assignment notifications
  • Deadline alerts
  • Completion notifications
  • Overdue alerts

Read more: signals.md

Getting Started

1. Understand the Models

Start with models.md to understand:

  • Task model (title, description, priority, due_date, status)
  • DeliverySchedule model (delivery_date, time_window, store, status)
  • TaskAssignment model (task, employee, assigned_date)
  • Task state machine and priority levels

2. Review Task Service

Read services.md to understand:

  • Task creation workflow
  • Assignment logic
  • Priority-based sorting
  • Deadline tracking
  • Completion workflow

3. Explore Task Flows

Check views.md to learn:

  • Task CRUD operations
  • Assignment and reassignment
  • Filtering and querying
  • Delivery scheduling

4. Study Notification System

Review signals.md for:

  • Assignment notifications
  • Deadline alerts
  • Completion notifications
  • Notification delivery

Key Architectural Decisions

  1. State machine pattern - Clear task lifecycle management
  2. Priority-based organization - Efficient workflow management
  3. Service layer - Business logic centralized
  4. Signal-based notifications - Automatic notification delivery
  5. Store-scoped tasks - Tasks organized by location
  6. Flexible assignment - Support individual and role-based assignment

Common Use Cases

  • Store opening tasks - Daily opening checklist for employees
  • Inventory tasks - Stock counting, restocking tasks
  • Maintenance tasks - Equipment maintenance, cleaning schedules
  • Delivery coordination - Schedule and track deliveries
  • Compliance tasks - Regular compliance checks and audits
  • Manager assignments - Manager-level approval tasks
  • Recurring tasks - Daily, weekly, monthly recurring tasks
  • High priority alerts - Urgent tasks requiring immediate attention
  • Task delegation - Reassign tasks to different employees

Service Methods

TaskService

Task Management:

  • create_task(task_data) - Create new task
  • update_task(task_id, updates) - Update task details
  • assign_task(task_id, employee_id) - Assign to employee
  • reassign_task(task_id, new_employee_id) - Reassign task
  • complete_task(task_id, completion_notes) - Mark complete
  • cancel_task(task_id, reason) - Cancel task

Task Querying:

  • get_tasks_by_store(store_id, filters) - Get store tasks
  • get_tasks_by_employee(employee_id, filters) - Get employee tasks
  • get_overdue_tasks(store_id=None) - Get overdue tasks
  • get_high_priority_tasks(store_id=None) - Get urgent tasks
  • get_pending_tasks(store_id=None) - Get pending tasks

Priority Management:

  • update_priority(task_id, new_priority) - Update task priority
  • escalate_priority(task_id) - Increase priority
  • sort_by_priority(tasks) - Sort tasks by priority

SchedulingService

Delivery Scheduling:

  • create_delivery_schedule(schedule_data) - Schedule delivery
  • update_delivery_schedule(schedule_id, updates) - Update schedule
  • mark_delivered(schedule_id, notes) - Mark delivery complete
  • cancel_delivery(schedule_id, reason) - Cancel delivery
  • get_store_schedules(store_id, date_range) - Get store deliveries

Recurring Tasks:

  • create_recurring_task(task_data, frequency) - Create recurring task
  • generate_recurring_instances(recurring_task) - Generate instances
  • update_recurring_series(recurring_task_id, updates) - Update series

NotificationService

Notification Management:

  • notify_assignment(task_id, employee_id) - Send assignment notification
  • notify_deadline(task_id) - Send deadline alert
  • notify_overdue(task_id) - Send overdue alert
  • notify_completion(task_id) - Send completion notification

Full documentation: services.md

Next Steps

  1. Start with models.md - Understand the data structure
  2. Then services.md - Learn task management logic
  3. Review views.md - Explore API endpoints
  4. Check signals.md - See notification system
  5. Study serializers.md - Understand validation

Was this page helpful?