PSA/server/docs/AI_CODING_GUIDE.md

AI Coding Assistant Guide

This document provides guidance for AI coding assistants working with the Alga PSA codebase.

Prerequisites

• Node.js 20.0.0 or higher is required for this project
• Understanding of TypeScript, Next.js 14, and PostgreSQL
• Familiarity with REST API design patterns

Key Architectural Patterns

1. V2 Controller Pattern

All new APIs should use the V2 controller pattern located in /src/lib/api/controllers/. This pattern:

• Handles authentication inline to avoid circular dependencies
• Uses Zod schemas for validation
• Implements consistent error handling
• Supports tenant isolation

Example structure:

export class ApiXxxControllerV2 extends ApiBaseControllerV2 {
  constructor() {
    super(xxxService, {
      resource: 'xxx',
      createSchema: createXxxSchema,
      updateSchema: updateXxxSchema,
      querySchema: xxxListQuerySchema,
      permissions: {
        create: 'create',
        read: 'read',
        update: 'update',
        delete: 'delete',
        list: 'read'
      }
    });
  }
}

2. Service Layer Pattern

Business logic should be in service files located in /src/lib/services/:

• Keep controllers thin
• Services handle database operations
• Use transactions for data consistency
• Implement proper error handling

3. Database Patterns

• Use Knex.js for database queries
• Always include tenant isolation (tenant_id)
• Use migrations for schema changes
• Follow naming conventions (snake_case for DB, camelCase for JS)

4. Testing Requirements

All new features must include:

• E2E tests in /src/test/e2e/
• Test factories for data generation
• Both positive and negative test cases
• Authentication and authorization tests

Common Tasks

Adding a New API Endpoint

1. Create the V2 controller in /src/lib/api/controllers/
2. Define Zod schemas in /src/lib/schemas/
3. Update route files in /src/app/api/v1/
4. Write E2E tests
5. Update documentation

Modifying Database Schema

1. Create a migration file: npm run migrate:make <name>
2. Write up and down migrations
3. Run migrations: npm run migrate
4. Update TypeScript interfaces
5. Update affected services and controllers

Working with Authentication

• REST APIs use API keys (X-API-KEY header)
• Web interface uses session-based auth
• Always verify tenant context
• Check permissions before operations

Code Quality Standards

TypeScript

• Use strict mode
• Define proper interfaces
• Avoid any types
• Use type guards where needed

Error Handling

• Use consistent error classes
• Return appropriate HTTP status codes
• Include helpful error messages
• Log errors appropriately

Performance

• Use database indexes appropriately
• Implement pagination for list endpoints
• Cache frequently accessed data
• Optimize N+1 queries

Important Files and Directories

• /src/lib/api/controllers/ - V2 API controllers
• /src/lib/services/ - Business logic services
• /src/lib/schemas/ - Zod validation schemas
• /src/app/api/v1/ - API route definitions
• /src/test/e2e/ - End-to-end tests
• /migrations/ - Database migrations
• /docs/ - Project documentation

Debugging Tips

1. Check logs in /logs/ directory
2. Use npm run test:watch for TDD
3. Verify tenant context in all queries
4. Check API key permissions
5. Review error responses for clues

Common Pitfalls to Avoid

1. Circular Dependencies: Use inline authentication in V2 controllers
2. Missing Tenant Context: Always include tenant_id in queries
3. Inadequate Validation: Use Zod schemas for all inputs
4. Poor Error Messages: Provide clear, actionable error messages
5. Skipping Tests: Always write E2E tests for new features

Getting Help

• Review existing V2 controllers for examples
• Check /docs/api-migration-summary.md for patterns
• Look at test files for usage examples
• Follow established conventions in the codebase