OpenParable
Skip to content
← Back to skills

Backend Patterns

Development
backend-patterns

Backend Patterns is an Agent Skill for development published in the YosemiteCrew/Yosemite-Crew repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when working in apps/backend — new endpoints, controllers, services, models, queues/workers, or integrations. Covers the Router to Controller to Service to Model architecture, Zod validation, Prisma/PostgreSQL data access, Winston logging, BullMQ jobs, and FHIR/IDEXX/Merck integrations.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/YosemiteCrew/Yosemite-Crew/blob/HEAD/.claude/skills/backend-patterns/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/backend-patterns, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Backend Patterns — Yosemite Crew

Description

Use this skill when working on apps/backend. Covers Express.js architecture, service/controller patterns, validation, error handling, and healthcare-specific integrations.

TRIGGER: any task in apps/backend — new endpoints, services, models, or integrations.


Architecture

apps/backend/src/
  routers/        ← Express route definitions (thin — just register handlers)
  controllers/    ← Request/response handling, input validation
  services/       ← Business logic (no req/res objects here)
  models/         ← Prisma models (PostgreSQL); legacy Mongoose only, no new usage
  queues/         ← BullMQ job definitions
  workers/        ← BullMQ worker processors
  integrations/   ← External services (IDEXX, Merck, Stripe, Firebase, AWS)

Pattern: Router → Controller → Service → Model

Controllers call services. Services call models. Never put business logic in controllers or routers.


Validation

Use Zod for request validation. Never trust raw req.body.

import { z } from 'zod';

const CreateAppointmentSchema = z.object({
  patientId: z.string().uuid(),
  date: z.string().datetime(),
});

// In controller:
const data = CreateAppointmentSchema.parse(req.body);

Database

  • PostgreSQL via Prisma is the database for all new code; Prisma owns schema + migrations (see @yosemite-crew/database).
  • No new Mongoose/MongoDB. Legacy Mongoose models may still exist, but do not add new models or queries — this matches apps/backend/AGENTS.md.
  • Never access data directly from controllers — always go through services/models.

Authentication

AWS Cognito is the auth provider. Use jsonwebtoken + jwks-rsa for token verification. Never roll custom auth.


Background Jobs

BullMQ is the queue system. Jobs go in queues/, processors in workers/.

// Never process jobs inline in a request handler
// Always enqueue and let a worker handle async operations
await emailQueue.add('send-reminder', { appointmentId });

Healthcare Integrations

  • FHIR types from @yosemite-crew/fhir — use these, never invent custom health data shapes.
  • IDEXX and Merck integrations live in src/integrations/ — extend there, never inline.

Logging

Use Winston for all logging. Never use console.log in production code.

import logger from 'src/utils/logger';
logger.info('Appointment created', { appointmentId });
logger.error('Payment failed', { error, userId });

Gotchas

  • Do not refactor backend architecture unless explicitly asked — the user's CLAUDE.md is explicit about this.
  • Zod .parse() throws on invalid input — use .safeParse() when you want to handle errors gracefully.
  • BullMQ jobs are persisted in Redis — make job processors idempotent.
  • All Stripe webhook handlers must verify the signature before processing.
  • Firebase Admin SDK is initialized once — never re-initialize it in a handler.