rl-docs-hub

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

---

API Specs

todo_mobile currently performs sync writes through GraphQL and expects Auth0-issued identity context to be accepted by backend auth middleware.

Environment Contracts

From app env (Env):

• AUTH0_DOMAIN
• AUTH0_CLIENT_ID
• AUTH0_REDIRECT_URI
• GRAPHQL_ENDPOINT

Auth Flow Contract (Client)

1. Client starts Auth0 WebAuth login.
2. Auth0 redirects to configured callback URI.
3. Client stores idToken securely.
4. Client requires biometric unlock for subsequent access.

The current GraphQL client uses HttpLink without an auth header injector. Backend integration is expected to add/standardize bearer token forwarding in a follow-up.

GraphQL Operations (Implemented)

Mutation: upsertTodo

mutation UpsertTodo($input: TodoInput!) {
  upsertTodo(input: $input) {
    id
    version
    updatedAt
  }
}

Variables shape (current expectation)

$input is forwarded from queued SyncJob.payload and is expected to represent a full todo payload.

{
  "id": "uuid",
  "listId": "uuid",
  "title": "string",
  "description": "string",
  "dueDate": "2026-03-06T12:00:00.000Z",
  "labels": ["work", "urgent"],
  "reminderAt": "2026-03-06T11:45:00.000Z",
  "completed": false,
  "updatedAt": "2026-03-06T10:00:00.000Z",
  "deleted": false,
  "version": 2,
  "force": false
}

• force is optionally set by client during clientWins conflict replay.
• On conflict, backend is expected to surface an error containing CONFLICT.

Expected Backend Schema (Minimum)

scalar DateTime

input TodoInput {
  id: ID!
  listId: ID!
  title: String!
  description: String
  dueDate: DateTime
  labels: [String!]
  reminderAt: DateTime
  completed: Boolean
  updatedAt: DateTime!
  deleted: Boolean
  version: Int
  force: Boolean
}

type Todo {
  id: ID!
  version: Int!
  updatedAt: DateTime!
}

type Mutation {
  upsertTodo(input: TodoInput!): Todo!
}

Sync Interaction Sequence

sequenceDiagram
    participant App as todo_mobile
    participant Hive as Hive syncQueue
    participant API as GraphQL API

    App->>Hive: enqueue(SyncJob)
    App->>App: detect connectivity restored
    App->>Hive: read queued jobs
    loop each job
      App->>API: mutation upsertTodo(input: payload)
      alt success
        App->>Hive: delete job
      else conflict error contains "CONFLICT"
        App->>App: apply conflict strategy
        App->>API: retry with merged/forced payload
      end
    end