breakpilot-compliance/AGENTS.typescript.md

AGENTS.typescript.md — TypeScript / Next.js Conventions

Applies to: admin-compliance/, developer-portal/, breakpilot-compliance-sdk/, consent-sdk/, dsms-node/ (where applicable).

Layered architecture (Next.js 15 App Router)

app/
├── <route>/
│   ├── page.tsx              # Server Component by default. ≤200 LOC.
│   ├── layout.tsx
│   ├── _components/          # Private folder; not routable. Colocated UI.
│   │   └── <Component>.tsx   # Each file ≤300 LOC.
│   ├── _hooks/               # Client hooks for this route.
│   ├── _server/              # Server actions, data loaders for this route.
│   └── loading.tsx / error.tsx
├── api/
│   └── <domain>/route.ts     # Thin handler. Delegates to lib/server/<domain>/.
lib/
├── <domain>/                 # Pure helpers, types, schemas (zod). Reusable.
└── server/<domain>/          # Server-only logic; uses "server-only" import.
components/                   # Truly shared, app-wide components.

Server vs Client: Default is Server Component. Add "use client" only when you need state, effects, or browser APIs. Push the boundary as deep as possible.

API routes (route.ts)

• One handler per HTTP method, ≤40 LOC.
• Validate input with zod. Reject invalid → 400.
• Delegate to lib/server/<domain>/. No business logic in route.ts.
• Always return NextResponse.json(..., { status }). Never throw to the framework.

export async function POST(req: Request) {
  const parsed = CreateDSRSchema.safeParse(await req.json());
  if (!parsed.success) return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
  const result = await dsrService.create(parsed.data);
  return NextResponse.json(result, { status: 201 });
}

Page components

• Pages >300 lines must be split into colocated _components/.
• Server Components fetch data; pass plain objects to Client Components.
• No data fetching in useEffect for server-renderable data.
• State management: prefer URL state (searchParams) and Server Components over global stores.

Types

• lib/sdk/types.ts is being split into lib/sdk/types/<domain>.ts. Mirror backend domain boundaries.
• All API DTOs are zod schemas; infer types via z.infer.
• No any. No as unknown as. If you reach for it, the type is wrong.

Tests

• Unit: Vitest (*.test.ts/*.test.tsx), colocated.
• Hooks: @testing-library/react renderHook.
• E2E: Playwright (tests/e2e/), one spec per top-level page, smoke happy path minimum.
• Snapshot tests sparingly — only for stable output (CSV, JSON-LD).
• Coverage target: 70% on lib/, smoke coverage on app/.

Tooling

• tsc --noEmit clean (strict mode, noUncheckedIndexedAccess: true).
• ESLint with @typescript-eslint, eslint-config-next, type-aware rules on.
• prettier.
• next build clean. No // @ts-ignore. // @ts-expect-error only with a comment explaining why.

Performance

• Use next/dynamic for heavy client-only components.
• Image: next/image with explicit width/height.
• Avoid waterfalls — Promise.all for parallel data fetches in Server Components.

What you may NOT do

• Put business logic in a page.tsx or route.ts.
• Reach across module boundaries (e.g. admin-compliance importing from developer-portal).
• Use dangerouslySetInnerHTML without explicit sanitization.
• Call backend APIs directly from Client Components when a Server Component or Server Action would do.
• Change a public API route's path/method/schema without updating SDK consumers in the same change.
• Create a file >500 lines.
• Disable a lint or type rule globally to silence a finding — fix the root cause.