carmanagement/docs/project-design/API_REFACTOR_TASK_LIST.md

API Refactor Status

This file replaces the older pre-refactor task list that referenced route paths and module boundaries no longer present in the codebase.

Source of truth:

• apps/api/src/app.ts
• apps/api/src/modules/*
• apps/api/src/http/*

Refactor State

The API has already been refactored into the modular structure the old task list was aiming for.

Current structure includes:

• modules/* for route/service/repo/presenter grouping
• http/errors for centralized error types and middleware
• http/validate for request parsing helpers
• http/respond for success helpers
• module-level tests and integration tests under apps/api/src/tests

The older checklist items that referenced:

• apps/api/src/routes/*.ts
• missing test tooling
• missing shared validation helpers
• missing shared response helpers

are no longer accurate and should not be used as active work items.

Remaining Follow-Up Work

These are the only meaningful refactor follow-ups still worth tracking at a high level.

1. Keep OpenAPI coverage aligned with route growth

The API now has:

• Swagger UI at /docs
• OpenAPI JSON at /api/v1/openapi.json

But the OpenAPI document does not yet mirror every newer route group perfectly. Continue updating:

• apps/api/src/swagger/openapi.ts
• route schemas
• module docs

whenever new endpoints are added.

2. Expand integration test coverage

Integration tests exist, but the heaviest workflows still benefit from deeper coverage:

• subscription billing transitions
• marketplace reservation intake
• public booking and payment initialization
• reservation inspection and close flows
• admin billing operations

3. Reduce remaining direct Prisma orchestration in large services

The route layer is already thin in the current API. The next cleanup target is inside larger service files where orchestration still mixes:

• multi-step workflow logic
• transaction boundaries
• some direct Prisma writes

especially in:

• reservation flows
• subscription/billing flows
• admin billing flows

4. Keep docs aligned with disabled flows

Some legacy surfaces still exist as placeholders or schema remnants, for example:

• disabled Clerk webhook endpoint
• legacy clerkUserId field on Employee
• disabled renter signup/login API endpoints

Those should stay clearly marked in docs so design specs do not drift back toward removed implementations.