Krow-workspace/docs/MILESTONES/M4/planning/m4-v2-frontend-migration-guide.md

M4 V2 Frontend Migration Guide

Status: Active
Last updated: 2026-03-11
Audience: Web and mobile frontend developers

1) Purpose

This document tells frontend exactly how to migrate toward the v2 backend services on this branch.

It is intentionally strict about readiness:

1. core-api-v2 is ready for frontend integration now for uploads, signed URLs, model calls, and verification workflows.
2. command-api-v2 now has a first real write slice backed by the v2 SQL schema and verified through live smoke tests.
3. query-api-v2 now has a first real read slice backed by the v2 SQL schema and verified through live smoke tests.

Frontend should not assume all three services are ready just because they are deployed.

2) Live dev service URLs

1. Core API v2: https://krow-core-api-v2-e3g6witsvq-uc.a.run.app
2. Command API v2: https://krow-command-api-v2-e3g6witsvq-uc.a.run.app
3. Query API v2: https://krow-query-api-v2-e3g6witsvq-uc.a.run.app

3) Readiness summary

Service	Status	Frontend guidance
core-api-v2	Ready now with persistence caveat	Use for file upload, signed URLs, model calls, rapid order helpers, and verification flows
command-api-v2	First production slice	Use for documented v2 write flows only
query-api-v2	First production slice	Use for documented v2 read flows only

4) Non-negotiable migration rules

1. Do not point undocumented read screens to query-api-v2 yet.
2. Do not replace undocumented order, shift, or staffing mutations with command-api-v2 yet.
3. Do move all new service-style frontend work to core-api-v2.
4. Do use command/query v2 for the routes listed in this document when building the new v2 clients.
5. Any new frontend abstraction should separate:
   • core service client
   • command service client
   • query service client
   • legacy Data Connect access
6. Build the frontend with switchable adapters so the command/query cutover is a client config change, not a rewrite.

5) Auth and headers

All protected v2 routes currently require Firebase ID token:

Authorization: Bearer <firebase-id-token>

All services return:

1. X-Request-Id response header
2. Standard error envelope:

{
  "code": "STRING_CODE",
  "message": "Human readable message",
  "details": {},
  "requestId": "uuid"
}

Additional rule for command routes:

Idempotency-Key: <unique-per-user-action>

6) What frontend can migrate now

6.1 Move to core-api-v2 now

1. File uploads
2. Signed download URL generation
3. Rapid order voice transcription
4. Rapid order structured parsing
5. Generic model invocation
6. Verification job creation
7. Verification status polling
8. Manual verification review and retry

6.2 Keep on existing stack for now

1. Business reads
2. Staff reads
3. Shift lists and details outside the documented order detail shape
4. Applications lists and details not yet served by query v2
5. Payments and reporting reads

6.3 Move to command/query v2 now for the new v2 clients

1. Order creation
2. Order update
3. Order cancel
4. Shift assign staff
5. Shift accept
6. Shift status change
7. Attendance clock-in and clock-out
8. Favorite staff add and remove
9. Staff review create
10. Order list
11. Order detail
12. Favorite staff list
13. Staff review summary
14. Assignment attendance detail

7) Core API v2 routes frontend can use today

Use this service for backend capabilities that should not run directly from the client.

Important caveat:

1. File storage is real and backed by Google Cloud Storage.
2. Verification job state is not yet persisted to the v2 SQL schema.
3. Frontend can integrate with these routes now, but do not treat verification history as mission-critical durable state yet.

Base URL:

https://krow-core-api-v2-e3g6witsvq-uc.a.run.app

Routes:

1. POST /core/upload-file
2. POST /core/create-signed-url
3. POST /core/invoke-llm
4. POST /core/rapid-orders/transcribe
5. POST /core/rapid-orders/parse
6. POST /core/verifications
7. GET /core/verifications/:verificationId
8. POST /core/verifications/:verificationId/review
9. POST /core/verifications/:verificationId/retry
10. GET /health

For request and response examples, use:

1. docs/MILESTONES/M4/planning/m4-core-api-frontend-guide.md
2. docs/MILESTONES/M4/planning/m4-api-catalog.md

8) Command API v2 routes ready for the first migration slice

These routes are deployed and backed by the v2 SQL schema. They enforce auth, policy gate, and idempotency.

Base URL:

https://krow-command-api-v2-e3g6witsvq-uc.a.run.app

Routes:

1. POST /commands/orders/create
2. POST /commands/orders/:orderId/update
3. POST /commands/orders/:orderId/cancel
4. POST /commands/shifts/:shiftId/change-status
5. POST /commands/shifts/:shiftId/assign-staff
6. POST /commands/shifts/:shiftId/accept
7. POST /commands/attendance/clock-in
8. POST /commands/attendance/clock-out
9. POST /commands/businesses/:businessId/favorite-staff
10. DELETE /commands/businesses/:businessId/favorite-staff/:staffId
11. POST /commands/assignments/:assignmentId/reviews
12. GET /health
13. GET /readyz

Implemented now:

1. POST /commands/orders/create
2. POST /commands/orders/:orderId/update
3. POST /commands/orders/:orderId/cancel
4. POST /commands/shifts/:shiftId/change-status
5. POST /commands/shifts/:shiftId/assign-staff
6. POST /commands/shifts/:shiftId/accept
7. POST /commands/attendance/clock-in
8. POST /commands/attendance/clock-out
9. POST /commands/businesses/:businessId/favorite-staff
10. DELETE /commands/businesses/:businessId/favorite-staff/:staffId
11. POST /commands/assignments/:assignmentId/reviews

Live verification completed on 2026-03-11:

1. order create
2. order update
3. order cancel
4. shift assign staff
5. shift accept
6. shift status change
7. attendance clock-in
8. attendance clock-out
9. favorite add
10. favorite list
11. review create
12. review summary
13. order list/detail
14. attendance detail

Order creation request contract:

{
  "tenantId": "uuid",
  "businessId": "uuid",
  "vendorId": "uuid",
  "orderNumber": "ORD-1001",
  "title": "Cafe Event Staffing",
  "serviceType": "EVENT",
  "shifts": [
    {
      "shiftCode": "SHIFT-1",
      "title": "Morning Shift",
      "startsAt": "2026-03-11T08:00:00.000Z",
      "endsAt": "2026-03-11T16:00:00.000Z",
      "requiredWorkers": 2,
      "roles": [
        {
          "roleCode": "BARISTA",
          "roleName": "Barista",
          "workersNeeded": 2
        }
      ]
    }
  ]
}

Order creation success response:

{
  "orderId": "uuid",
  "orderNumber": "ORD-1001",
  "status": "OPEN",
  "shiftCount": 1,
  "shiftIds": ["uuid"],
  "idempotencyKey": "abc-123",
  "requestId": "uuid"
}

Important:

1. This is the first real write slice, not the full command surface.
2. Frontend should migrate only the documented routes.
3. Reuse one idempotency key per user action and never retry with a new key unless the UI is creating a brand new action.
4. The old 501 placeholders for order update, order cancel, shift status change, and shift assign staff are now implemented.

9) Query API v2 routes ready for the first migration slice

Base URL:

https://krow-query-api-v2-e3g6witsvq-uc.a.run.app

Current routes:

1. GET /health
2. GET /healthz
3. GET /readyz
4. GET /query/tenants/:tenantId/orders
5. GET /query/tenants/:tenantId/orders/:orderId
6. GET /query/tenants/:tenantId/businesses/:businessId/favorite-staff
7. GET /query/tenants/:tenantId/staff/:staffId/review-summary
8. GET /query/tenants/:tenantId/assignments/:assignmentId/attendance

Frontend can point the new v2 clients to these routes now. Frontend should not point any undocumented screen, list, detail page, dashboard, or reporting view to query-api-v2 yet.

10) Recommended frontend adapter shape

Frontend should isolate backend calls behind service adapters instead of calling routes inline in screens.

Suggested split:

1. coreApiClient
2. commandApiClient
3. queryApiClient
4. legacyDataConnectClient

Suggested cutover plan:

1. Move service-style operations to coreApiClient first.
2. Add commandApiClient now as the write path for the documented v2 write routes.
3. Add queryApiClient now as the read path for the documented v2 read routes.
4. Keep everything else on legacyDataConnectClient until the replacement route exists.
5. Expand migration route-by-route instead of big-bang switching whole apps.

11) Frontend implementation checklist

1. Add three environment variables:
   • CORE_API_V2_BASE_URL
   • COMMAND_API_V2_BASE_URL
   • QUERY_API_V2_BASE_URL
2. Add shared auth header injection using Firebase ID token.
3. Add shared response envelope parsing.
4. Add request ID logging in frontend network layer.
5. Add Idempotency-Key generation utility for command calls.
6. Build command/query clients behind feature flags or adapter switches.
7. Start integration with core-api-v2, command-api-v2, and query-api-v2 for the documented routes only.

12) Frontend do and do not

Do:

1. Treat core-api-v2 as the real backend entrypoint for uploads, model work, and verification.
2. Treat documented command/query v2 routes as the real backend entrypoint for the first v2 domain slice.
3. Build migration-safe abstractions now.
4. Keep old reads and writes isolated so they can be swapped cleanly later.

Do not:

1. Hardcode v2 command success as if business action is complete.
2. Point undocumented dashboards or reports to query v2 yet.
3. Remove current Data Connect code until the replacement route actually exists and is verified.

13) Practical migration sequence

1. Replace existing upload helpers with core-api-v2.
2. Replace signed URL generation with core-api-v2.
3. Point rapid order helpers to core-api-v2.
4. Point attire and document verification flows to core-api-v2.
5. Introduce command client wrapper with idempotency header support.
6. Point new v2 order creation, shift accept, attendance, favorites, and reviews flows to command-api-v2.
7. Point new v2 order list/detail, favorites, review summary, and attendance detail screens to query-api-v2.
8. Point new v2 order update, order cancel, shift assign, and shift status flows to command-api-v2.
9. Keep payments, reports, and remaining scheduling mutations on the legacy stack until the replacement routes exist.