api-integration

Purpose

Produce tested integration code connecting the platform's layers: REST route handlers in the main app (project.json -> mainApp), ORM queries, server-side WebSocket clients for device/edge telemetry (project.json -> device), and SSE endpoints fanning real-time data to browsers. Generated code follows project conventions; patterns use Drizzle ORM — adapt to the project's actual ORM (project.json -> stack.db).

Rules (never violate)

• Verify the real ORM schema before writing; STOP and ask if table or column names are missing or ambiguous — never code against a guessed schema.
• Always getDb() (lazy init), await auth() with 401 on authenticated routes, dynamic = 'force-dynamic' on session/env-reading routes, Zod on all external data.
• Never hardcode environment-specific values (URLs, hostnames, API keys) — use getServerEnv(); refuse if asked.
• Every useEffect opening an EventSource/WebSocket returns a cleanup function.
• Never overwrite an existing file without reading it and informing the user first.
• After any write, run api-contract to verify field alignment across layers.

Resources

• Read resources/integration-patterns.md when writing code — the six reference patterns (REST handler, ORM queries, lazy DB init, WebSocket, SSE, EventSource hook).
• Read resources/procedure-and-checks.md when executing a task — the 8-step procedure, self-check, common mistakes, escalation, failure modes, and a full worked example.

How to use

What it does

Writes the integration code connecting your layers: a REST route handler, an ORM query, a server-side WebSocket client ingesting device telemetry, or an SSE endpoint fanning it out. It checks your real schema before writing, then applies project conventions throughout.

When to use it

• A new route handler under apps/<mainApp>/src/app/api/**/route.ts.
• An ORM select, insert, update, or delete in a handler or Server Component.
• A WebSocket telemetry subscription, SSE endpoint, or browser EventSource hook.