Instruction file imported from Kevan-Y/Themoo (.github/instructions/backend.instructions.md). Copyright stays with the author.

Backend Rules (services/core/)

Before Committing

• Always run pnpm test:run from services/core/ to verify no tests are broken.
• Run pnpm tsc from services/core/ to catch type errors.
• If @starter/sdk imports fail, run pnpm --filter @starter/sdk build first.

Adding a Feature

Every feature lives in src/features/<name>/. Handler → service → DynamoDB:

1. Handler (<name>Handler.ts) — parse + validate input, call service, return response.
2. Service — pure business logic, receives RequestWithAuth, calls DynamoDB.
3. Never put DynamoDB calls directly in the handler.

Error Handling

• Throw AppException(message, StatusCode.XXX) — app.onError serializes it automatically.
• Use ErrorMessage[StatusCode.XXX].genericXxx for standard messages, never raw strings.

DynamoDB

• All writes that touch multiple items must use TransactWriteCommand.
• Access pattern is always PK = USER#<clerkUserId> — never query without this.

Testing

• Test files live in src/features/<name>/__tests__/.
• Use vitest — no jest globals; import describe, it, expect from vitest.