rl-docs-hub

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

---

Architecture

High-Level Design

todo_api is a monolithic NestJS GraphQL service with modular boundaries for auth, list/item domain logic, and synchronization support.

Runtime Components

• Apollo GraphQL server (Nest GraphQL module)
• Passport JWT strategy for request authentication
• Mongoose models for persistence
• Domain services (ListsService, ItemsService)
• Sync service for change recording and idempotency state

Module Topology

graph TD
  A[AppModule] --> B[AuthModule]
  A --> C[SyncModule]
  A --> D[ListsModule]
  A --> E[ItemsModule]

  D --> C
  E --> C
  E --> D

  B --> F[JwtStrategy + Passport JWT]
  C --> G[SyncService]
  D --> H[ListsResolver + ListsService]
  E --> I[ItemsResolver + ItemsService]

Request Lifecycle

flowchart LR
  Client -->|Bearer JWT| GraphQLResolver
  GraphQLResolver --> Guard[GqlAuthGuard]
  Guard --> Strategy[JwtStrategy.validate]
  Strategy -->|user.sub| ResolverMethod
  ResolverMethod --> DomainService
  DomainService --> Mongo[(MongoDB)]
  DomainService --> SyncService
  SyncService --> Mongo
  ResolverMethod --> Response

Auth Model

• JWT secret from JWT_SECRET (dev-secret fallback in local/dev)
• Accepted algorithms: HS256, RS256
• JwtStrategy.validate requires payload.sub; otherwise unauthorized
• @User() decorator extracts req.user and enforces authenticated principal
• All list/item/sync resolvers are protected by @UseGuards(GqlAuthGuard)

Domain Behavior

Lists

• Owner-scoped CRUD (ownerId always derived from JWT subject)
• Optimistic concurrency supported via expectedVersion
• Successful writes emit sync events:
  • LIST_UPSERT
  • LIST_DELETE

Items

• Owner-scoped CRUD + move operation
• create validates parent list ownership and auto-appends position
• move supports list transfer and position update in one mutation
• Optimistic concurrency supported via expectedVersion
• Successful writes emit sync events:
  • ITEM_UPSERT
  • ITEM_MOVE
  • ITEM_DELETE

Sync & Conflict Strategy

Pull side

• pullChanges(since) returns owner-specific chronological change log records
• Cursor is timestamp-based (createdAt of latest returned change)
• Batch limit is 500 changes per pull call

Push side

• pushChanges applies each operation independently
• Failed operations are captured as conflicts; successful operations still persist
• Overall accepted flag becomes false if any conflict occurs
• Conflicts include entityId and textual reason

Conflict mechanics

• Version mismatch (when expectedVersion provided) throws conflict exceptions
• Missing resources (e.g., list/item not found) also surface as conflicts
• Unsupported op/entity combinations are rejected per operation

Idempotency Strategy

pushChanges optionally accepts idempotencyKey:

1. Lookup by (ownerId, key)
2. If found, return previously stored response immediately
3. If absent, process operations and persist response using upsert ($setOnInsert)

This guarantees replay safety for mobile retries/timeouts without duplicate effects.

Sync Push Execution (Mermaid)

sequenceDiagram
  autonumber
  participant C as Client
  participant R as SyncResolver
  participant S as SyncService
  participant L as ListsService
  participant I as ItemsService

  C->>R: pushChanges(operations, idempotencyKey)
  R->>S: resolveIdempotent(ownerId, key)
  alt key exists
    S-->>R: previous response
    R-->>C: return cached response
  else no record
    loop each operation
      R->>R: parse payload JSON
      alt LIST:UPSERT
        R->>L: create/update (with expectedVersion)
      else ITEM:UPSERT
        R->>I: create/update (with expectedVersion)
      else ITEM:MOVE
        R->>I: move (with expectedVersion)
      else unsupported
        R->>R: append conflict
      end
    end
    R->>S: saveIdempotent(ownerId, key, response)
    R-->>C: SyncPushResult
  end