12 — API Mapping (Audit Module)

• 0. Module-wide request envelope & client policy
  • Screen: Audit log list (and filter bar)
  • Endpoint source: audit.controller.ts:17-34, audit.service.ts:37-51, audit-log.repository.ts:19-28
• Non-existent surfaces (append-only — do not build against them)
• Loading / streaming / realtime
• Client-side error mapping table (module)
• Optimistic / undo

Exact wire contract for the Audit screens → the single read endpoint. Base /api/v1; envelope per 00-shared/07. All endpoints from src/modules/audit/audit.controller.ts; business rules from audit.service.ts + audit.handler.ts + audit-log.repository.ts. Global guards: RateLimitGuard → JwtAuthGuard → RbacGuard (app.module.ts:129-133). Append-only module: no create/update/delete/export endpoints exist.

0. Module-wide request envelope & client policy

Screen: Audit log list (and filter bar)

Actual response (exact — derived from code):

{
  "success": true,
  "message": "OK",
  "data": {
    "data": [
      {
        "_id": "66f0…",
        "tenantId": "t_springfield",
        "actorId": "u_8f2a…",
        "actorType": "user",
        "action": "StudentUpdated",
        "entityType": null,
        "entityId": null,
        "occurredAt": "2026-08-02T05:02:14.000Z",
        "after": { "studentId": "s_9f1…", "changes": ["guardianPhone"] },
        "correlationId": "9a1c…",
        "before": null,
        "metadata": null,
        "isDeleted": false,
        "version": 0
      }
    ],
    "total": 1234
  },
  "timestamp": "2026-08-02T05:02:15.000Z",
  "requestId": "req_…"
}

Pagination shape deviation (critical, OQ-2): AuditService.query() returns {data, total} without meta (audit.service.ts:41-50). The envelope interceptor treats a payload as paginated only when it has both data and meta (response-envelope.interceptor.ts:25-32), so this response is wrapped as a plain object: client reads envelope.data.data[] and envelope.data.total. It does not receive meta:{page,limit,totalItems,totalPages,hasNext,hasPrevious} per the shared paginated contract (00-shared/07 §2). Client computes paging from total + requested page/limit.

Entry document fields (exact, audit-log.schema.ts:13-56 + inherited base.schema.ts:8-34):

Client flows: load(page, filters) → map → model; loadMore() → page+1 while items.length < total; pullToRefresh() → page=1 bypassing cache; changeFilter() → page=1.

Endpoint source: audit.controller.ts:17-34, audit.service.ts:37-51, audit-log.repository.ts:19-28

Non-existent surfaces (append-only — do not build against them)

Loading / streaming / realtime

Client-side error mapping table (module)

Optimistic / undo

None — read-only module; no mutations, no optimistic updates, no undo (09 §1).