Playbook: Update a Backend Contract and Regenerate the Frontend

This playbook documents one of the highest-value fullstack AI workflows in Cabloy.

When to use this playbook

Use this playbook when a backend API contract changes and the frontend should be brought back into sync.

Typical triggers include:

• DTO field changes
• controller parameter or response changes
• validation changes
• OpenAPI metadata changes
• relation or DTO inference changes that affect API shape

Step 1: Update the backend contract at the correct layer

Inspect which backend layer actually owns the change:

• controller
• dto
• entity
• validation rule
• inferred DTO path
• OpenAPI configuration

Relevant docs:

• Validation Guide
• OpenAPI Guide
• DTO Guide
• DTO Infer and Generation

Step 2: Verify the backend contract output

Before touching the frontend, verify that the backend-side contract change is really reflected in the generated OpenAPI output.

That may include:

• rebuilding or running the backend
• checking Swagger / OpenAPI JSON
• confirming the contract shape matches intent

Step 3: Detect the edition and frontend target

Before regenerating frontend artifacts:

1. detect Basic vs Start
2. verify the relevant frontend flavor
3. confirm whether the change affects Admin, Web, or both

Step 4: Regenerate the frontend-side contract artifacts

Use the Zova OpenAPI and REST-generation path rather than manually updating request code first.

Representative commands may include:

npm run zova :openapi:generate ...
cd zova && npm run build:rest:cabloyBasicAdmin
cd zova && npm run build:rest:cabloyBasicWeb

For Start, use the Start-specific flavor paths from that repo.

Step 5: Inspect affected frontend layers

After regeneration, inspect which frontend layers need follow-up changes:

• API services
• generated SDK
• model-managed data access
• schema-driven UI
• page or component assumptions

Step 6: Verify the end-to-end loop

Use a verification path that checks both sides:

• backend contract correctness
• regenerated frontend artifacts
• typecheck/build for the affected frontend edition or flavor

AI rule of thumb

A good fullstack contract update workflow is usually:

1. change backend contract
2. verify OpenAPI output
3. detect edition and target flavor
4. regenerate frontend contract artifacts
5. inspect downstream breakage
6. verify end to end

Not:

1. change backend DTO
2. hand-edit a few frontend request types
3. leave the contract loop out of sync