contract-synchronization

name	contract-synchronization
description	Playbook for managing API contract schemas, generating client code, and verifying backend/frontend synchronization.

API Contract & Multi-Project Synchronization Playbook

This playbook defines the standards and workflows for maintaining absolute contract compliance and synchronization between backend and frontend sub-projects in a monorepo workspace.

---

1. Shared Schema: The Single Source of Truth

To prevent API contract mismatch and runtime integration errors:

• Define a Contract: Place a machine-readable API specification (e.g., openapi.yaml, schema.json, or shared Type Definitions) in a shared directory at the root of the workspace or in the backend's public docs directory (e.g., docs/openapi.yaml).
• Never Define Types Manually: The frontend must not manually recreate request/response interfaces or endpoint routes. All API-related types, endpoints, and HTTP client bindings must be derived from the shared schema.

---

2. Automated Frontend Client Codegen

To synchronize changes instantly from Backend $\rightarrow$ Frontend:

• Codegen Trigger: When backend API models are modified, run the client code generator (e.g. openapi-generator-cli, orval, or custom typescript generators) to regenerate types and fetching hooks inside the frontend directory (e.g. app/frontend/src/api/).
• Check-in Policy: Generated client files MUST be checked into source control along with the API contract modification. The build pipeline will fail if the code generator produces unstaged changes.

---

3. Double-Sided Contract Verification

Validation must happen on both ends of the interface boundary:

A. Backend-Side Verification

• Validate that the actual endpoints match the declared API specification.
• Use schema-driven test runners (e.g., Schemathesis in Python, or openapi-validator in Node.js) to dynamically fuzz or test backend routes against the OpenAPI file:

  schemathesis run docs/openapi.yaml --base-url http://localhost:8000/api
  

B. Frontend-Side Verification

• Ensure the frontend build process strictly compiles against the generated TypeScript definitions.
• Running npm run build or tsc --noEmit in the frontend directory serves as the final gate to verify that all API components, arguments, and data shapes match the backend payload.

---

4. Multi-Project Validation Gate

When validation is run, the agent must check all projects. The root validation script validate.py reads .agents/projects.json to automatically run tests in each sub-directory (e.g., app/backend and app/frontend), ensuring that changes in one module do not break the tests in the other.