backend-services

# Backend Services ## Quick Start For QuickStack backend work, follow the existing service architecture: - Use one class per file with a default-exported singleton instance. - Keep service dependencies as module imports of other singleton services or adapters. - Route Prisma and external API access through adapters, not directly from services. - Throw `ServiceException` or `FormValidationException` for expected domain failures. - After a mutation affecting cached reads, invalidate the matching tags in `finally`. ## Service Pattern When creating or editing a service: - Put business logic in `src/server/services/`. - Export a singleton instance as the file default export. - Accept primitives or shared model types as inputs. - Import dependencies at module scope; do not instantiate sibling services. ## Adapters And Actions - Put external integrations in `src/server/adapter/` using the same singleton export pattern. - Use adapters for Prisma, Kubernetes, S3, and Longhorn access. - Wrap server actions with `simpleAction` or `saveFormAction`. - Perform authorization checks inside the action callback before calling the service. ## Mutation Rules - After a mutation affecting cached reads, call `revalidateTag()` in `finally`. - Use the matching `Tags.*` helper; never hardcode cache tag strings. - Use transactions when multiple writes must succeed or fail together. ## Standalone Services - Place cron and background jobs in `src/server/services/standalone-services/`. - Register cron jobs with `scheduleService`. - Wrap cron callback bodies in `try/catch` and log errors instead of rethrowing. - Initialize standalone services from `src/server.ts`. ## Reference See `REFERENCE.md` for concrete patterns covering adapters, actions, authorization, Prisma, caching, naming, and startup wiring.