integration-status
One typed source of truth for what the frontend can actually do against the backend.
Introduction
A small package for JavaScript and TypeScript monorepos. Every app's screens and every ask to the backend live in one typed data file. From that data it generates a markdown report that lint keeps current, and a status page each app can serve behind a flag.
In use in two client monorepos, across eight Next.js apps. Packaged as a Claude Code plugin.
The rule it enforces
Why it exists
- Several Next.js apps were being built against a backend that was still being built too.
- Nobody could say quickly which screens really worked against staging and which were still on mock data.
- Backend issues were spread across chats, tickets and memory, often without the endpoint, the exact request or the reason it mattered.
- A hand-written status doc helped, but it went out of date as soon as someone forgot to edit it.
The idea
- Treat integration status as data, not prose: one typed package lists every module and every ask.
- Each ask says where (endpoints, screens), what (the exact request) and why (what it breaks for people).
- Generate the doc and the status page from that same data, so they cannot disagree.
- Make lint fail while the generated doc is out of date.
What it gives a team
- One answer to 'what is connected?', for every app, in a page you can open in a meeting.
- Backend engineers get precise asks, grouped by priority, with a button that copies one as a ticket.
- A claimed fix stays unconfirmed until someone has measured it on staging.
- Typos fail the build: duplicate ids, links to unknown asks and missing dates are rejected.
- Changes are plain TypeScript, so they are reviewed in pull requests like any other code.
- Fixed asks are kept with their answers, so the history of the integration is never lost.
How it works
One package, one direction of flow: data in, doc and page out.
Log it as data
When a screen is wired, or a backend problem is found, update the app's module list or add an ask with where, what and why.
Validate
The report builder rejects duplicate ids, malformed dates, fixed asks without a date and modules that point at unknown asks.
Generate
pnpm status:doc renders docs/api-integration-status.md: a summary per app, module tables by area, then asks by priority.
Check
pnpm lint runs status:doc --check and fails if the committed doc does not match the data.
Share
Each app serves /integration-status when its flag is on: filterable modules, open, claimed and fixed asks, and deep links.
packages/integration-status/
├─ package.json # exports ./report, ./labels, ./types
├─ scripts/write-doc.mjs # renders and checks the markdown
└─ src/
├─ types.ts # Module, Ask and their status unions
├─ labels.ts # one set of labels for the doc and the page
├─ report.ts # validate() and getAppReport()
├─ render-doc.ts # markdown renderer
└─ data/
├─ asks.ts # every ask, merged
└─ <app>.ts # one module list per appData model
Two shapes carry everything. A Module is a screen or feature in one app. An Ask is something the frontend needs from the backend or from product, with where, what and why.
export const MODULE_STATUSES = ["connected", "partial", "ready", "blocked", "no-backend"] as const;
export interface Module {
id: string; // the page's #module-<id> anchor
area: string; // heading it is listed under
name: string;
status: ModuleStatus;
routes: ReadonlyArray<string>; // route paths
endpoints: ReadonlyArray<string>; // SDK function or "METHOD /path"
note: string; // what works, what is mock, and why
asks?: ReadonlyArray<string>; // ids of asks that stop or limit it
}
export const ASK_KINDS = ["security", "bug", "missing", "contract", "environment", "question"] as const;
export const ASK_STATUSES = ["open", "claimed", "fixed"] as const;
export interface Ask {
id: string;
title: string;
kind: AskKind;
priority: "urgent" | "high" | "normal" | "low";
audience: "backend" | "product";
status: AskStatus;
logged: string; // YYYY-MM-DD, found or last re-checked
fixed?: string; // YYYY-MM-DD, set with "claimed" or "fixed"
where: ReadonlyArray<string>; // endpoints, DTOs and screens involved
what: string; // the exact ask
why: string; // what it breaks for the people using the app
answer?: string; // what the backend answered or shipped
}An ask
Asks are written for the person who will fix them. where points at the endpoint and the screen, what is the exact request, and why says what it breaks for people using the app.
{
id: "profile-update-500",
title: "Profile update fails with a 500",
kind: "bug",
priority: "high",
audience: "backend",
status: "open",
logged: "2026-01-15",
where: ["PATCH /api/users/me", "/settings/profile"],
what: "Accept a partial body on `PATCH /api/users/me`; today any request without `phone` returns 500.",
why: "People cannot change their name or photo without also re-entering their phone number.",
}Statuses
Module status
| Status | Meaning |
|---|---|
| Connected | Wired and exercised against staging. |
| Partly connected | Wired, but part of the screen still runs on local or mock data. |
| Ready to wire | The endpoints exist; the screen is not wired yet. |
| Blocked | The endpoints exist, but an open ask stops the work. |
| No backend | No endpoint yet; the screen runs on fixtures. |
Ask kind
| Kind | Meaning |
|---|---|
| Security | A hole or exposure in the API. |
| Bug | The endpoint exists but misbehaves. |
| Missing | A screen needs an endpoint or field that does not exist. |
| Contract | Shape, naming or status code differs from the spec. |
| Staging environment | Test data, seeding or configuration. |
| Question | A product decision the screen is waiting on. |
Priority
| Priority | Use it when |
|---|---|
urgent | A security hole, or it blocks a demo. |
high | It blocks a module. |
normal | It limits a module. |
low | Nice to have. |
Ask lifecycle
Asks move forward and are never deleted. A fix is not a fix until someone has checked it.
| Status | Meaning |
|---|---|
| Open | Logged and not answered yet. |
| Claimed, not verified | The backend or the spec says it is done. Nobody has measured it on staging yet, so it still holds its screens up. |
| Fixed | Answered and checked on staging, or, for a contract-only ask, visible in the spec. Kept, never deleted. |
Why 'claimed' exists
The status page
Each app serves /integration-status when INTEGRATION_STATUS_PAGE=on. It is off by default, never indexed, and needs no sign-in, so it can be opened in a meeting.
Candidate app
Updated 2026-01-15 · staging backend
12
Connected
6
Partly connected
2
Ready to wire
3
Blocked
4
No backend
- Sign in and OTPAccountConnected
- Job searchJobsConnected
- ProfileAccountBlocked
- Saved jobsJobsPartly connected
- MessagesInboxNo backend
Profile update fails with a 500
- Where
- PATCH /api/users/me · /settings/profile
- What
- Accept a partial body on PATCH /api/users/me. Today any request without phone returns 500.
- Why
- People cannot change their name or photo without also re-entering their phone number, and the error gives them no hint.
- Summary tiles per status that filter the module list.
- Tabs for modules, open asks, claimed asks and fixed asks, with search and a priority filter.
- Ask cards with where, what and why, the modules each one blocks, and other apps it affects.
- A Copy ask button that copies an ask as plain text, ready for a ticket or a chat.
- Deep links to #module-<id> and #ask-<id> that open the right tab.
// apps/<app>/src/app/integration-status/page.tsx
import { connection } from "next/server";
import { notFound } from "next/navigation";
import { getAppReport } from "@repo/integration-status/report";
import { IntegrationStatusPage } from "@repo/ui/components/integration-status-page";
export const metadata = { robots: { index: false, follow: false } };
export default async function Page() {
await connection(); // read the flag per request: a restart, not a rebuild
if (process.env.INTEGRATION_STATUS_PAGE !== "on") notFound();
return <IntegrationStatusPage report={getAppReport("job-board")} />;
}Installation
The tool ships as a Claude Code plugin with a setup skill that scaffolds it into an existing pnpm and Turborepo monorepo. The plugin repository is private; access is available on request.
Detect the repo
Find the package scope, the apps and their dev ports, the shared UI package and the API client. Node 22.18 or later runs the TypeScript sources directly.
Add the package
Copy the package template to
packages/integration-statusand create one data file per app. List every existing screen as a module with an honest status: a status page that starts empty is never filled.Wire the scripts
Add the doc script and append the check to lint, then generate the first doc.
package.json{ "scripts": { "status:doc": "node packages/integration-status/scripts/write-doc.mjs", "lint": "oxlint --type-aware && pnpm status:doc --check" } }Add the page
Copy the UI components into the shared UI package, add the route to each app, and add
INTEGRATION_STATUS_PAGE=to each.env.example.Verify
pnpm status:doc --checkexits 0, lint and type checks pass, and the page loads with the flag on and returns 404 with it off.
Keeping it current
| When | Do |
|---|---|
| A screen is wired | Update the module's status, endpoints and note. |
| A backend problem is found | Add an ask with where, what and why, and link it from the modules it blocks. |
| The backend says it is fixed | Mark the ask claimed with the date. |
| The fix is measured on staging | Mark it fixed, record the answer, and update the modules. |
| Any of the above | Run pnpm status:doc and commit it separately as docs(integration-status): … |
Help for AI-assisted work
Limits
- Nothing is detected automatically. The data is only as good as the logging.
- The stale-doc check runs with pnpm lint. Repos without CI rely on people running it.
- It describes the integration; it does not test it.