backend-services

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.