Instruction file imported from tajbinkhan/tms-api (.github/instructions/api-module-style.instructions.md). Copyright stays with the author.

TMS API Module And Coding Style

Enforcement Level

• Treat every rule in this file as a hard default.
• Only deviate when the user explicitly asks for an exception.

Module And Folder Pattern

• Create each feature in src/app/<feature-name>/.
• Keep this baseline file set for each feature:
  • <feature-name>.module.ts
  • <feature-name>.controller.ts
  • <feature-name>.service.ts
  • <feature-name>.schema.ts
  • @types/<feature-name>.types.ts for return and response shape typing.
• Add optional subfolders only when needed by feature complexity, such as services/, strategies/, storage/, or helper files.
• Register every new feature module in src/app.module.ts under imports.

Controller Pattern

• Define route scope with @Controller('<feature-route>').
• Validate all query and body input with Zod safeParse from local schema files.
• If validation fails, throw BadRequestException with issue messages joined from Zod errors.
• Return API responses using createApiResponse(...) from the shared interceptor for consistent response shape.
• For POST, PUT, PATCH, and DELETE, use @UseGuards(JwtAuthGuard) by default.
• Public mutating endpoints are allowed only as explicit exceptions (for example, contact submission); when used, keep the intent clear in code.

Schema Pattern

• Build field validation from shared validators in src/core/validators/commonRules.
• Build listing query schemas from baseQuerySchema(...) plus feature-specific extensions.
• Define sortable fields as readonly SortableField[] and use as const.
• Export all DTO and query types with z.infer<typeof ...> from the same schema file.

Service Pattern

• Keep business logic in service classes; controllers should stay thin.
• Extend DrizzleService and inject DATABASE_CONNECTION in the constructor.
• Use schema from src/database/schema and Drizzle query helpers (eq, and, or, ilike, etc.).
• Use transactions for multi-table writes or complex create/update operations.
• Throw NotFoundException when an entity does not exist.
• For list endpoints, use PaginationManager and orderByColumn for consistent pagination and sorting behavior.
• Return publicId as outward id in response payload types.

Coding Style

• Match repository formatting: tabs, single quotes, semicolons, trailing commas, print width around 100.
• Keep imports grouped and sorted by the existing formatter setup.
• Prefer explicit types from schema inference and module @types files.
• Keep changes minimal and localized; do not refactor unrelated files.

Verification After Changes

• Run pnpm lint in the API workspace.
• Run pnpm build in the API workspace.
• If DB schema logic changes, run the relevant pnpm db:* command required by the task.