social-app/docs/protocols/models/todo.md

Todo Data Protocol

Scope

Defines the backend/frontend data contract for /api/v1/todos.

Field Definitions

• id: string (UUID)
• owner_id: string (UUID)
• title: string, 1..255
• description: string or null, max 1000
• priority: int, quadrant value in [1, 4]
• order: int, zero-based ordering inside the same priority bucket, >= 0
• status: enum string: pending | done | canceled
• completed_at: datetime string or null
• created_at: datetime string
• updated_at: datetime string
• schedule_items: array

Request Contracts

Create Todo (POST /api/v1/todos)

• required: title
• optional: description, priority, order, schedule_item_ids
• order omitted: backend assigns append position in the target quadrant.

Update Todo (PATCH /api/v1/todos/{todo_id})

• optional: title, description, priority, order, status, schedule_item_ids
• order is interpreted inside the todo's final priority quadrant.

Ordering Rules

• Todo list API returns items sorted by priority ASC, then order ASC.
• Drag reorder in same quadrant updates order to a continuous sequence starting from 0.
• Drag move across quadrants updates both priority and order, and source/target quadrants should both stay contiguous from 0.

Compatibility Notes

• due_at is removed from todo protocol.
• Clients must not send or depend on due_at for todo ordering.