PSA/docs/archive/controller-pattern-analysis-report.md

Controller Pattern Analysis Report

Executive Summary

Analysis of all API v1 routes in /home/coder/alga-psa/server/src/app/api/v1/ reveals two distinct controller patterns being used:

• V2 Controllers: 66 routes (20%)
• Standard Controllers: 255 routes (80%)

Controller Patterns

V2 Controller Pattern

Routes using V2 controllers follow this pattern:

• Import controllers with "V2" suffix (e.g., ApiContactControllerV2)
• No try-catch blocks in route handlers
• Controller instantiated once and methods called directly
• Example:

import { ApiContactControllerV2 } from 'server/src/lib/api/controllers/ApiContactControllerV2';

const controller = new ApiContactControllerV2();

export async function GET(request: Request) {
  return await controller.list()(request as any);
}

Standard Controller Pattern

Routes using standard controllers follow this pattern:

• Import controllers without V2 suffix (e.g., AssetController)
• Include try-catch blocks with handleApiError middleware
• Controller instantiated inside each handler
• Example:

import { AssetController } from 'server/src/lib/api/controllers/AssetController';
import { handleApiError } from 'server/src/lib/api/middleware/apiMiddleware';

export async function GET(request: Request) {
  try {
    const controller = new AssetController();
    return await controller.list()(request as any);
  } catch (error) {
    return handleApiError(error);
  }
}

V2 Controllers by Resource

Resource	Count	Controller
time-entries	12	ApiTimeEntryControllerV2
teams	11	ApiTeamControllerV2
users	8	ApiUserControllerV2
tickets	8	ApiTicketControllerV2
projects	7	ApiProjectControllerV2
roles	6	ApiRoleControllerV2
contacts	5	ApiContactControllerV2
companies	5	ApiCompanyControllerV2
permissions	4	ApiPermissionControllerV2

Standard Controllers by Resource

Controller	Routes	Primary Resources
QuickBooksController	31	integrations/quickbooks
FinancialController	25	financial
InvoiceController	25	invoices
WebhookController	24	webhooks
WorkflowController	23	workflows
TimeSheetController	23	time-sheets
ContractLineController	17	contract-lines
AssetController	15	assets
AutomationController	14	automation
TagController	10	tags
CategoryController	9	categories
UserController	9	users (subset)
ProjectController	8	projects (subset)
MetadataController	8	meta
PermissionRoleController	5	plan-bundles, user-roles
TeamController	4	teams (subset)

Key Observations

1. Migration in Progress: The presence of both patterns suggests an ongoing migration from standard controllers to V2 controllers.

2. Core Resources Using V2: Critical resources like users, teams, contacts, companies, and permissions have been migrated to V2 controllers.

3. Complex Modules Still Standard: Larger, more complex modules (QuickBooks integration, financial, invoices, webhooks, workflows) still use standard controllers.

4. Error Handling Difference: V2 controllers appear to handle errors internally, while standard controllers use explicit try-catch blocks with middleware.

5. Instantiation Pattern: V2 controllers are instantiated once outside handlers, while standard controllers are instantiated per request.

Recommendations

1. Complete Migration: Consider migrating remaining standard controllers to V2 pattern for consistency.

2. Priority Order: Focus on high-usage modules first (financial, invoices, webhooks).

3. Documentation: Document the differences and migration guide for developers.

4. Testing: Ensure comprehensive tests during migration, especially for error handling behavior changes.