new-domain

New Backend Domain — GitGazer

Scaffold a new feature module in the Lambda API following the project's controller-centric domain layout. Each domain is a self-contained folder under apps/lambdas/api/src/domains/.

When to Use

• Adding a new REST resource or feature area (e.g. /api/<thing>)
• Grouping a set of related endpoints + business logic + tests

Not for: a single extra route on an existing resource (just add it to that domain's *.routes.ts).

File Layout

Create apps/lambdas/api/src/domains/<domain>/ with:

Reference implementation to copy patterns from: apps/lambdas/api/src/domains/integrations/.

Procedure

1. Create the folder and files from the templates above. Rename things / Thing to your resource.

2. Register the router in apps/lambdas/api/src/shared/router/index.ts:

   import thingsRoutes from '@/domains/things/things.routes';
   // ...inside createApp(), with the other includeRouter calls:
   app.includeRouter(thingsRoutes);
   

   The global middleware chain (compress → cors → authenticate → originCheck) is applied by createApp — do not re-add it per domain.

3. Write controllers that wrap every tenant-scoped query in withRlsTransaction (see the refactor skill for the boundary rules). Default role is reader; pass userName: gitgazerWriter.name for writes.

4. Add tests colocated as *.test.ts. Mock @gitgazer/db/client and all AWS clients — never hit real services.

5. Verify: cd apps/lambdas/api && pnpm run test:unit && pnpm run lint.

Conventions (enforced — see backend.instructions.md)

• Imports: @/ for apps/lambdas/api/src, @gitgazer/db/* for the shared package. Never ../../../.
• Auth context: handlers receive AppRequestContext; use the addUserIntegrationsToCtx middleware to populate reqCtx.appContext.integrations / integrationRoles.
• Authorization: gate state-changing routes with requireRole('admin' | 'owner' | ...) from @/shared/middleware/require-role.
• Responses: return a Response with JSON.stringify(...) and an HttpStatusCodes status; throw BadRequestError / UnauthorizedError / etc. from @aws-lambda-powertools/event-handler/http for errors.
• Logging: getLogger() from @gitgazer/backend-core/logger (AWS Powertools structured logging).
• AWS clients: import pre-configured clients from @/shared/clients/ — never instantiate SDK clients in a controller.

Checklist

• <domain>.routes.ts exports default a Router and is registered via app.includeRouter(...)
• All tenant-scoped DB access goes through withRlsTransaction with the correct role
• State-changing routes protected with requireRole(...)
• Inputs validated; errors thrown as Powertools HTTP errors
• Colocated *.test.ts with @gitgazer/db/client + AWS mocked
• pnpm run test:unit and pnpm run lint pass