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 - Use `src/server/services/standalone-services/` for Node-runtime modules consumed by cron jobs, watchers, Socket.IO, or other (non Next.JS) custom-server paths. - Keep standalone services free of Next.js and App Router runtime imports, including `next/cache`, `next/navigation`, and `next/server`. - Register persistent cron jobs with `scheduleService`; event-driven Socket.IO services need no schedule registration. - Wrap cron callback bodies in `try/catch` and log errors instead of rethrowing. - Initialize persistent standalone services from `src/server.ts`. - Before creating or moving a standalone service, read `src/server/services/standalone-services/README.md` for its consumers and placement rules. ## Reference See `REFERENCE.md` for concrete patterns covering adapters, actions, authorization, Prisma, caching, naming, and startup wiring.