| name | backend-services |
| description | Create and update QuickStack backend services, adapters, standalone services, and server actions using the project's established singleton, adapter, caching, and error-handling patterns. Use when editing files under src/server/services, src/server/adapter, src/server/utils, src/server.ts, or related server-side actions and backend utilities. |
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.
