Initial commit

.cursor/rules/03-backend-api.mdc

@@ -0,0 +1,83 @@
+---
+description: Fastify backend, API design, Prisma, auth, and error handling
+globs: apps/api/**/*
+alwaysApply: false
+---
+
+You are working on the backend in `apps/api`.
+
+## Backend framework
+- Use Fastify as the default backend framework.
+- Prefer Fastify plugins and encapsulation patterns over ad hoc global behavior.
+
+## API design
+- Keep business logic out of route handlers.
+- Route handlers should be thin and focused on:
+  - validation
+  - auth/context
+  - calling application services
+  - shaping responses
+- Prefer explicit service-layer or domain-layer boundaries for business logic.
+
+## Validation and contracts
+- Validate all incoming requests with Zod or approved schema wrappers.
+- Validate file uploads and all user-controlled input.
+- Avoid trusting frontend input.
+- Use explicit schemas for request and response shapes where practical.
+
+## API documentation
+- Maintain Swagger/OpenAPI support.
+- New or changed endpoints should update the API schema/docs as part of the work.
+- Keep API docs accurate and usable.
+
+## Data access
+- Prefer Prisma as the default ORM unless explicitly directed otherwise.
+- Use Postgres as the primary relational database.
+- Store relational/domain data in Postgres.
+- Store document/image metadata in Postgres and file binaries in appropriate storage.
+- Avoid leaking raw ORM/database logic into unrelated layers.
+
+## Auth and permissions
+- Roles and permissions are first-class concerns.
+- Design with support for:
+  - board members
+  - treasurers
+  - owners
+  - tenants
+  - future administrative roles
+- Support passwordless authentication patterns:
+  - magic link
+  - OIDC
+  - passkeys
+- Do not hard-code assumptions that one deployment always maps to one HOA.
+- Self-hosted mode supports single tenancy.
+- SaaS mode must remain compatible with future or current multi-tenant architecture decisions.
+
+## Auditing
+- All destructive or sensitive actions must be auditable.
+- Deletions and other important changes should be recorded in an audit log.
+- Prefer soft-delete or explicit audit-aware flows where appropriate.
+- Do not implement silent destructive behavior.
+
+## Error handling
+- Use explicit, typed, and user-safe error handling.
+- Never use silent catch blocks.
+- Do not swallow errors.
+- Return structured, predictable error responses.
+
+**Example:**
+
+```typescript
+// BAD: silent catch
+try {
+  await doSomething();
+} catch {}
+
+// GOOD: log, type, rethrow or return structured error
+try {
+  await doSomething();
+} catch (e) {
+  logger.error({ err: e }, 'doSomething failed');
+  throw new ServiceError('Operation failed', { cause: e });
+}
+```