rl-docs-hub

Home · Apps · rl-main-infra · todo_api · todo_mobile

---

API Specs

GraphQL API exposed by NestJS (@nestjs/apollo) with auto-generated schema (autoSchemaFile: true).

Endpoint & Auth

• GraphQL endpoint: default NestJS GraphQL route (/graphql)
• Auth transport: Authorization: Bearer <jwt>
• Guarding strategy: @UseGuards(GqlAuthGuard) applied at resolver class level (lists/items/sync)
• JWT requirements: token payload must include sub; email and name are optional

Resolver Surface

Queries

Query	Args	Returns	Notes
todoLists	none	[TodoList!]!	Owner-scoped by JWT sub, sorted by order, then createdAt
todoItems	listId?: String	[TodoItem!]!	Owner-scoped; optional list filter; sorted by listId, position, createdAt
pullChanges	since?: String	PullChangesResult!	Incremental sync stream based on createdAt cursor

Mutations

Mutation	Args	Returns	Behavior
createTodoList	input: CreateListInput!	TodoList!	Creates list under authenticated owner
updateTodoList	input: UpdateListInput!	TodoList!	Optional optimistic concurrency via expectedVersion
deleteTodoList	id: String!	Boolean!	Deletes owner list, records sync tombstone
createTodoItem	input: CreateItemInput!	TodoItem!	Validates parent list ownership, appends position
updateTodoItem	input: UpdateItemInput!	TodoItem!	Partial update with optional version check
moveTodoItem	input: MoveItemInput!	TodoItem!	Cross-list/in-list move with new position + version bump
deleteTodoItem	id: String!	Boolean!	Deletes owner item, records sync tombstone
pushChanges	operations: [SyncOperationInput!]!, idempotencyKey?: String	SyncPushResult!	Batched sync apply; per-op conflict capture; idempotent replay

Core Types

TodoList

• id: ID!
• ownerId: String!
• title: String!
• description: String
• order: number (default 0)
• version: number (default 1)
• createdAt: Date!
• updatedAt: Date!

TodoItem

• id: ID!
• ownerId: String!
• listId: String!
• title: String!
• description: String
• completed: Boolean!
• labels: [String!]!
• dueDate: Date
• reminders: [Date!]!
• position: number
• version: number
• createdAt: Date!
• updatedAt: Date!

Sync DTOs

• SyncOperationInput: { op, entityId, entityType, payload, expectedVersion? }
• SyncPushResult: { accepted, conflicts[] }
• PullChangesResult: { cursor, changes[] } where changes are serialized JSON strings

Input Validation Rules

• CreateListInput.title: string, max 120 chars
• CreateListInput.description: optional, max 512 chars
• UpdateListInput.order: optional int >= 0
• UpdateListInput.expectedVersion: optional int >= 1
• CreateItemInput.title: max 160 chars
• CreateItemInput.description: optional, max 1000 chars
• CreateItemInput.dueDate: optional ISO date string
• UpdateItemInput.completed: optional boolean
• UpdateItemInput.expectedVersion: optional int >= 1
• MoveItemInput.toPosition: int >= 0

Sync & Conflict Semantics

pullChanges(since)

• Queries owner-scoped change log entries where createdAt > since (if provided)
• Sorted ascending by createdAt
• Hard-limited to 500 changes per pull
• Cursor is the last change timestamp; if no changes, cursor echoes since or current timestamp

pushChanges(operations, idempotencyKey)

• If idempotencyKey exists and has prior response for same owner, returns saved response immediately
• Applies each operation independently:
  • LIST:UPSERT → create or update list
  • ITEM:UPSERT → create or update item
  • ITEM:MOVE → move item
• Unsupported operations return conflict entries
• Failed operations are accumulated in conflicts; successful operations still commit
• accepted = true only when conflicts.length === 0

Mutation Flow (Mermaid)

sequenceDiagram
  autonumber
  participant C as Client
  participant G as GraphQL Resolver
  participant S as Domain Service
  participant M as MongoDB
  participant Y as SyncService

  C->>G: Mutation + Bearer JWT
  G->>G: GqlAuthGuard + User decorator
  G->>S: create/update/move/delete
  S->>M: Persist list/item document
  S->>Y: record(ownerId, type, entityId, payload)
  Y->>M: Insert change_log entry
  G-->>C: Updated entity / Boolean / SyncPushResult