committed openapi.json drifts from the backend with no CI regen gate: generated client types silently lie

[kilodesodiq-arch]

Problem

The frontend's client types are generated from a committed snapshot (app/frontend/openapi.json) with no automated check that the snapshot matches the backend's live spec. package.json provides only a manual regen:

// app/frontend/package.json
"generate:api": "openapi-typescript openapi.json -o src/lib/generated/api.ts"

The backend can export its spec (spec:export in app/backend/package.json runs scripts/export-spec.ts), but nothing links the two in CI. If the backend changes a route, DTO, or status code, openapi.json stays stale and src/lib/generated/api.ts continues to compile against the old contract.

Consequence: the typed client silently lies. A frontend developer sees a correctly-typed request that 400s (or silently misinterprets a field) at runtime because the generated types predate the backend change. This is the exact failure mode that makes a generated client worse than untyped code — false confidence — and it cannot be caught by pnpm type-check because the types are self-consistent against the stale spec.

Root cause

The spec export (backend) and type generation (frontend) are two unconnected scripts; the committed openapi.json is the single point of drift with no CI reconciliation.

Why this is architecturally hard

1. The drift gate must run across two packages. The backend must export a fresh spec in CI, then the frontend must regenerate and diff against the committed openapi.json/api.ts; wiring this into the existing per-service workflows (.github/workflows/backend-ci.yml, frontend-ci.yml) requires cross-service artifact or job orchestration, not a one-line lint.
2. The diff must be actionable. A raw JSON diff is noisy; the gate should fail with a clear "run pnpm generate:api" message and ideally show which paths/types changed, or contributors will disable it.
3. Committed-vs-generated policy is a decision. Either openapi.json/api.ts stay committed (and the gate enforces freshness) or they become generated artifacts (and build steps change); each has different implications for CI caching and local dev.

Proposed design

Add a CI step that exports the backend spec and runs the frontend's generate:api, then fails if the committed files differ. Prefer the backend exporting to a known path in CI and the frontend job comparing. Document the two-step contract in the contributing guide.

Acceptance criteria

CI

• A PR that changes a backend DTO/route without updating app/frontend/openapi.json (and src/lib/generated/api.ts) fails CI.
• A PR that regenerates the spec passes, and the failure message tells the contributor the exact command to run.

Docs

• The contributing guide documents how to keep the OpenAPI snapshot in sync across backend and frontend.

Out of scope

JWT token wiring in api-client.ts and frontend integration tests for the generated client are separate issues.

Getting started

Files: app/frontend/openapi.json, app/frontend/src/lib/generated/api.ts, app/frontend/package.json (generate:api), app/backend/package.json (spec:export), .github/workflows/frontend-ci.yml, .github/workflows/backend-ci.yml.

cd app/backend && npm run spec:export
cd app/frontend && pnpm generate:api
git diff --stat app/frontend/openapi.json app/frontend/src/lib/generated/api.ts

Good first files to read: app/frontend/package.json (the generate:api script) and .github/workflows/frontend-ci.yml to see where the gate would run.

[rudra496]

I would like to take this issue.

Implementation Plan

1. CI Drift Gate: Add a CI verification job/step in .github/workflows/ that executes \spec:export\ in the backend and runs the frontend's \generate:api\ generation script.
2. Freshness Diff: Perform a git diff verification against the committed \�pp/frontend/openapi.json\ and \�pp/frontend/src/lib/generated/api.ts. If differences exist, fail the workflow with a clean, actionable error message showing the changed definitions and providing the exact local command (
   pm run spec:export && pnpm generate:api) to sync.
3. Docs: Update the contributing guide with clear instructions for maintaining OpenAPI spec synchronization across backend updates and frontend type generation.
4. Validation: Test locally and via CI matrix with both synced and intentionally desynced spec fixtures to verify gate accuracy.

Ready to implement immediately once assigned.

[Flames4fun]

Hi! Nice to meet you — I’m @Flames4fun, a software engineer with OSS experience around API compatibility, type safety, regression testing, and CI.

I’d be glad to take this issue if it’s available. A good part of my recent OSS work has been around preventing contracts from silently drifting: in GoDiao/Free-Way#70 I built compatibility regression coverage around public API behavior, and more recently in Adamantine-guild/guildpass-integrations#395 I fixed a type-safety/parser regression and added focused contract tests so the same failure could not silently return.

For this issue, I’d follow the proposed committed-artifact approach rather than redesigning the generation model: export the backend spec deterministically in CI, regenerate the frontend client from that exact spec, diff the committed artifacts, and make the failure actionable with the regeneration command for contributors. I’d also keep the JWT/client integration work explicitly out of scope.

I’d estimate around 4–5 focused hours to have the PR ready, including testing the failing drift case, the clean regeneration path, CI behavior, and the contributing-doc update.

If that direction matches what you have in mind, I’d appreciate being assigned to it. Thanks!

[temiport25]

can i handle this issue?

[grantfox-oss]

🦊 GrantFox — @temiport25 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #434)
2. Your PR will be reviewed by the ChainForgee maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@temiport25's PR #438 was approved and merged by @kilodesodiq-arch.

🏆 @temiport25: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (710 total points). Track your full progress on GrantFox.

👏 Great work, @temiport25! Keep contributing to ChainForgee.