optima/.github/copilot-instructions.md

Copilot / AI Agent Instructions for ttscm-api

Purpose: make AI coding agents immediately productive in this repository by describing architecture, conventions, workflows, and helpful code pointers.

-- Big picture: This is a TypeScript API service (runs on Bun) using the Hono framework. The HTTP surface is implemented in src/api where small router files are mounted on a versioned router in src/api/server.ts (see the /v1 mount). Typical request flow is:

• router (in src/api/routers/*) → controller (in src/controllers/*) → manager (in src/managers/*) → module / generated/prisma for persistence and external integrations.

• Keep each layer focused: routers handle routing & middleware, controllers handle request validation and high-level orchestration, managers encapsulate domain/persistence logic, modules provide shared utilities (external API clients, helpers).

• Runtime / tooling: The project runs on Bun. Dev command: npm run dev (runs bun --watch src/index.ts). DB tooling uses Prisma; generated client lives under generated/prisma (do NOT edit generated files). Key scripts in package.json:

  • dev — start the server with Bun in watch mode
  • db:gen — prisma generate
  • db:push — prisma migrate dev --skip-generate

• Data layer: Prisma schema is at prisma/schema.prisma. The app imports the generated Prisma client from generated/prisma/client.ts (or generated/prisma/browser.ts in browser contexts). Always run the db:gen script after updating schema.prisma.

• Routing & controllers: Example flow: a request hits a router in src/api/routers/* → router delegates to a controller in src/controllers/* → controller calls a manager in src/managers/* for domain/persistence logic. Important concrete patterns:

  • src/api/server.ts mounts v1 and uses v1.route("/auth", require("./routers/authRouter").default) style requires; preserve this shape when adding routes.
  • Router files export a default Hono router object (CommonJS module.exports/export default mixture is used across the codebase).
  • Controllers are single-export modules named like CompanyController.ts with named methods per action (e.g., fetch, update). Prefer small methods that call into managers/*.
  • Managers are thin domain layers (e.g., managers/companies.ts) that wrap generated/prisma calls and other I/O. Keep side effects here, keep controllers pure orchestration.
  • Use src/modules/api-utils/apiResponse.ts for every HTTP response shape (successful/created/error/internalError/zodError).
  • Use Zod schemas in controllers for request validation; server-level app.onError maps ZodError to apiResponse.zodError.

API layout & conventions (how to add a new endpoint)

• Add router: create src/api/routers/<thing>Router.ts exporting a Hono router and mount it in src/api/server.ts under the v1 router.
• Add controller: create src/controllers/<Thing>Controller.ts exporting functions for each action. Controllers should validate input with Zod, call managers, and return apiResponse.* results.
• Add manager: create src/managers/<things>.ts for persistence/domain logic. Use the generated Prisma client (generated/prisma/client.ts) here; do not import Prisma directly in controllers.
• Add modules/types: if needed, add helpers to src/modules/* and runtime types to src/types/*.
• Middleware & auth: use src/api/middleware/authorization.ts for protecting routes; follow existing token/session patterns from src/controllers/SessionController.ts and src/Errors/*.
• Error handling: throw repository-specific errors from src/Errors/* (include status, name, message, optional cause) and let src/api/server.ts map them via apiResponse.error.
• Naming: prefer plural manager filenames (companies.ts) and singular controller names (CompanyController.ts) — follow existing files.

Examples & notable files

• src/api/server.ts — mounts v1, registers cors, central onError handler and notFound response.

• src/api/routers/companyRouter.ts and src/controllers/CompanyController.ts — canonical example for adding company endpoints.

• src/api/user/@me/* — nested route example (use Hono sub-routers for subpaths).

• src/modules/cw-utils/* — external API integrations; keep interfaces stable and return domain objects consumed by managers.

• Validation & errors: Zod is used for input validation; Zod errors are handled centrally in src/api/server.ts via apiResponse.zodError. Application errors use custom error classes in src/Errors/* (e.g., AuthenticationError.ts, GenericError.ts). When creating errors, follow the shape used in existing errors (include status, name, message, and optional cause).

• Response pattern: Use the apiResponse helpers in src/modules/api-utils/apiResponse.ts for formatting responses and status codes (successful, created, error, internalError, zodError).

• Auth & external integrations: Microsoft OAuth flow is under src/api/auth/* and src/modules/fetchMicrosoftUser.ts. If touching authentication, follow existing redirect/refresh patterns in src/api/auth and preserve token-refresh semantics.

• ConnectWise integration: Utilities for ConnectWise interactions live in src/modules/cw-utils/* (e.g., fetchCompanyConfigurations.ts). These modules often call external APIs and return domain data; preserve the module contracts (input types and returned shapes) when refactoring.

• Generated files and CI: generated/ is a build artifact. Do not modify. When updating Prisma models, run npm run db:gen and commit changes to generated/prisma only if that's the established workflow.

• Files to inspect for context / examples:

  • src/api/server.ts — central error handling, router mounting, CORS and not-found handling.
  • src/modules/api-utils/apiResponse.ts — response shaping used across controllers.
  • src/controllers/CompanyController.ts — example controller calling managers.
  • src/modules/cw-utils/fetchCompanyConfigurations.ts — example external integration utility.
  • generated/prisma/client.ts — generated Prisma client imports; avoid editing.

• Coding conventions & patterns specific to this repo:

  • Prefer the existing layered architecture: routers → controllers → managers → modules.
  • Use the apiResponse helpers for all HTTP responses.
  • Throw or propagate repository-specific custom errors (from src/Errors/*) rather than returning bare objects.
  • Keep TypeScript types in src/types/* and use Zod for runtime checks.
  • Avoid else statements — prefer ternary operators, early returns, or other control flow patterns. Only use else if there is absolutely no other way.

• Local dev / quick checks:

  • Start dev server: npm run dev
  • Regenerate Prisma client: npm run db:gen
  • Apply DB migrations locally: npm run db:push

• When editing generated or infra files: if you need to change generated/prisma/* (rare), explain why in the PR and show commands used to regenerate.

• Documentation sync (IMPORTANT): Whenever you add, remove, or modify API routes or permission nodes, you must update all three of the following files to keep them in sync:

  1. src/types/PermissionNodes.ts — the single source of truth for all permission node definitions, categories, descriptions, and usedIn references.
  2. PERMISSIONS.md — human-readable documentation of all permission nodes; must strictly reflect the data in PermissionNodes.ts.
  3. API_ROUTES.md — comprehensive documentation of all API routes, including method, path, auth requirements, permissions, request/response examples. Always verify that new routes have their required permissions listed in PermissionNodes.ts, that PERMISSIONS.md tables match the TS file exactly, and that API_ROUTES.md includes full documentation for every mounted route. Run through all three files at the end of any route or permission change to catch discrepancies.

If anything here is unclear or you'd like more examples (e.g., a walk-through editing a controller + manager + test run), tell me which area to expand and I'll iterate.