scaffolding-api-routes

name	scaffolding-api-routes
description	Reads API_Contracts.md artifacts and rebuilds the legacy Express routes as modern Next.js Route Handlers or Server Actions. Use when following a legacy audit artifact to scaffold out a new Express API routes.

Scaffolding Modern API Routes

Translate legacy Express route definitions and middleware chains into modern Next.js Route Handlers with built-in validation and unified session management.

Objective

Rebuild the documented API surface to ensure 1:1 functional parity with the legacy system, focusing on mapping Express Middlewares to Next.js Route Guards.

Instructions for the Scaffold Subagent

Copy this checklist and track your progress:

Task Progress:
- [ ] Step 1: Analyze API Contracts
- [ ] Step 2: Establish Route Architecture
- [ ] Step 3: Map Middleware to Guards
- [ ] Step 4: Implement Zod-Backed Request Validation
- [ ] Step 5: Implement Resource Handlers

Step 1. Analyze API Contracts

Locate and read docs/legacy-audit/API_Contracts.md. Identify:

• Primary Routes & Sub-routes: Map these to the Next.js App Router (e.g., /api/[resource]/[sub-resource]/route.ts).
• Legacy Middleware Requirements: Identify routes protected by Passport, custom "owner-only" checks, or roles.

Step 2. Establish Route Architecture

Create the folder structure in src/app/api/ representing the resources. Ensure that:

• Dynamic Segments (e.g., [id]) are used for resource-specific operations (GET single, PUT, DELETE).
• Index Segments (e.g., /api/posts/route.ts) are used for collection operations (GET list, POST new).

Step 3. Map Middleware to Guards

Translate legacy Express middleware chains into Modular Route Guards:

• Authentication: Map requiresLogin to a getServerSession(authOptions) check.
• Authorization (Ownership): Map resourceAuth.hasAuthorization to a "Resource Ownership Guard" (e.g., if (resource.user_id !== session.user.id) throw Unauthorized).
• Authorization (Roles): Map role-specific middleware to logic that checks session.user.role.

Step 4. Implement Zod-Backed Request Validation

For every incoming request (POST, PUT, PATCH):

• Use the Zod Schemas defined in src/lib/models/schema.ts (from Step 3) to validate req.json().
• Ensure the API returns a standard 422 Unprocessable Entity or 400 Bad Request with a detailed error payload if validation fails.

Step 5. Implement Resource Handlers

Write the GET, POST, PUT, PATCH, and DELETE functions.

• Strict Response Envelopes: Match the Common Response Envelope identified in the audit (e.g., whether to return a raw object or a wrapped { data: ... }).
• Pagination & Sorting: Implement skip, limit, and sort parameters to mirror the legacy behavior precisely.
• Status Code Parity: Match the exact success and error status codes documented in API_Contracts.md.