Refactor a Legacy Module

Every platform has legacy modules

The DS platform has been in production for over a year. The first modules were built before the team established response helpers, before withPermission() existed, before anyone agreed on pagination standards. They work. They serve users. But they are a maintenance liability:

• Raw SQL strings in route handlers — no parameterization abstraction, no query builder.
• Manual JSON responses — NextResponse.json({ data }) instead of listResponse() or errorResponse().
• No authorization guard — the route checks session.user.role inline with an if/else chain instead of using withPermission().
• No pagination — the GET endpoint returns every row. For a table with 50 records, this was fine. For 5,000, it times out.
• No Zod validation — the POST handler trusts req.json() without schema validation.
• No data_source column — no way to tell if a record was manually entered, seeded, or synced.
• Bare catch (e) { return NextResponse.json({ error: e.message }) } — leaks stack traces.

If this list sounds familiar, you have a legacy module. This lesson walks through a systematic refactor using AI, bringing it up to the standards you built in Lessons 5-11.

Anatomy of a legacy route handler

Here is what a typical pre-standard route handler looks like. This is the vehicles module — written 14 months ago, before the platform conventions existed:

// src/app/api/vehicles/route.ts (BEFORE refactor)
import { getServerSession } from 'next-auth';
import { NextResponse } from 'next/server';
import { getPool } from '@/lib/db/connection';

export async function GET() {
  const session = await getServerSession();
  if (!session) {
    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
  }

  try {
    const pool = await getPool();
    const result = await pool.request().query('SELECT * FROM vehicles ORDER BY plate_number');
    return NextResponse.json(result.recordset);
  } catch (e: any) {
    return NextResponse.json({ error: e.message }, { status: 500 });
  }
}

export async function POST(req: Request) {
  const session = await getServerSession();
  if (!session) {
    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
  }
  if (session.user.role !== 'admin' && session.user.role !== 'operator') {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
  }

  try {
    const body = await req.json();
    const pool = await getPool();
    await pool.request()
      .input('plate', body.plateNumber)
      .input('make', body.make)
      .input('model', body.model)
      .input('year', body.year)
      .input('assigned_to', body.assignedTo)
      .query(`INSERT INTO vehicles (plate_number, make, model, year, assigned_to)
              VALUES (@plate, @make, @model, @year, @assigned_to)`);
    return NextResponse.json({ success: true }, { status: 201 });
  } catch (e: any) {
    return NextResponse.json({ error: e.message }, { status: 500 });
  }
}

Count the issues:

The refactor prompt

This is where everything you have learned comes together. The prompt references the specific platform conventions from earlier lessons:

Refactor src/app/api/vehicles/route.ts to match our current platform standards.

CURRENT STATE: The file has raw SQL, no pagination, inline role checking,
no Zod validation, no response helpers, and catches that leak error details.

REQUIRED CHANGES:

1. RESPONSE HELPERS: Import listResponse, errorResponse, successResponse from
   src/lib/api/responses.ts. Replace all NextResponse.json() calls.

2. AUTHORIZATION: Import withPermission from src/lib/auth/permissions.ts.
   - GET: wrap with withPermission('viewer')
   - POST: wrap with withPermission('operator')
   Remove all inline session.user.role checks.

3. PAGINATION (GET):
   - Import parsePagination from src/lib/api/pagination.ts
   - Accept page and pageSize from query params
   - Cap pageSize at 500
   - Use SQL OFFSET/FETCH NEXT for Azure SQL pagination
   - Include total count in a separate COUNT(*) query
   - Return via listResponse({ data, total, page, pageSize })

4. ZOD VALIDATION (POST):
   - Create src/lib/schemas/vehicle.ts with VehicleCreateSchema:
     plateNumber: string, 1-10 chars, uppercase alphanumeric
     make: string, 1-50 chars
     model: string, 1-50 chars
     year: number, 1990-2035
     assignedTo: string, optional
   - Parse request body with schema, return 400 with Zod errors on failure

5. SAFE ERRORS: Use errorResponse() which internally calls formatSafeError().
   Remove all catch blocks that return e.message directly.

6. DATA PROVENANCE: Add data_source column to the INSERT statement.
   Value: 'manual' for API-created records.

7. REPLACE SELECT *: Explicitly list columns in the SELECT query.

Do NOT change the database schema. Do NOT change the URL path. The API contract
(request/response shape) for existing consumers should remain backward-compatible
where possible -- the response envelope shape changes (from bare array to
{ data, total, page, pageSize }) but that is an expected migration.

The refactor checklist

Use this checklist for every legacy module. Each item maps to a lesson where the standard was established:

Steps 1-7 are in the prompt above. Steps 8-10 are follow-up tasks.

Update the SWR hook

The frontend must match the new response shape. Here is the typical change:

// BEFORE: bare array response
const { data: vehicles } = useSWR<Vehicle[]>('/api/vehicles', fetcher);

// AFTER: envelope response
const { data: response } = useSWR<ListResponse<Vehicle>>(
  `/api/vehicles?page=${page}&pageSize=${pageSize}`,
  fetcher
);
const vehicles = response?.data ?? [];
const total = response?.total ?? 0;

This change also unlocks pagination in the DataGrid:

<DataGrid
  rows={vehicles}
  rowCount={total}
  paginationMode="server"
  paginationModel={{ page: page - 1, pageSize }}
  onPaginationModelChange={(model) => {
    setPage(model.page + 1);
    setPageSize(model.pageSize);
  }}
/>

Handle the edge case: modules with consumers

Some legacy modules have other modules that depend on their API response shape. The vehicles module might be consumed by a fleet dashboard, a maintenance scheduler, and a reporting pipeline. Changing the response envelope breaks all of them.

Two strategies:

Strategy 1: Versioned response (recommended for high-traffic modules)

Add a query parameter: /api/vehicles?format=v2. Default to the legacy bare-array format for backward compatibility. New consumers use format=v2 to get the envelope. Deprecate v1 after all consumers migrate.

Strategy 2: Update all consumers in one PR (recommended for low-traffic modules)

If the vehicles API has 2-3 consumers and they are all in the same repo, refactor everything together. Search for /api/vehicles across the codebase, update each consumer to handle the new envelope, and merge it all in one PR. This is faster and avoids maintaining two formats.

Search the codebase for all files that fetch from /api/vehicles. For each one:
1. Show the current code that processes the response
2. Show the updated code to handle the new { data, total, page, pageSize } envelope
3. If the consumer doesn't need pagination, it can just access .data and ignore the rest

The full refactor workflow

Refactoring priorities

Not all legacy modules need to be refactored at the same urgency. Here is how to prioritize:

Key takeaways

• Legacy module refactoring is the most common real-world task on the DS platform. Building new modules from scratch is the exception.
• The refactor follows a predictable sequence: response helpers, authorization, pagination, validation, safe errors, provenance, column listing. Each step maps to a lesson where the standard was established.
• AI handles the mechanical transformation. You specify the target standards, the AI applies them. Your job is verifying the output and coordinating with consumers.
• The response envelope change is a breaking change. Plan for it: either version the API or update all consumers in the same PR.
• Prioritize by risk. Missing withPermission() and leaked error messages are audit findings. Missing pagination is a performance problem. Missing provenance is a data lineage gap. Fix them in that order.
• Everything from Lessons 4-14 converges here. Authorization, response helpers, pagination, Zod validation, provenance, DensityGate, testing, accessibility — this lesson is the proof that the platform standards work as a coherent system.

What’s next

The Testing & Quality lane is complete. In the next lane — Infrastructure & Delivery — you will instrument your application with Azure Application Insights telemetry, configure Key Vault secrets with Managed Identity, set up Azure DevOps git workflows, and build a deployment pipeline that packages and ships your application to Azure Government.