# Generated by Pluribus 0.1.0 on 2026-03-08 — do not edit manually
# Source: pluribus.md | Skill: cursor
# Project: Orbital — Multi-tenant logistics SaaS

## Project Overview

You are assisting the **Orbital** engineering team — 5 backend engineers building a multi-tenant SaaS for logistics operations. TypeScript monorepo using NestJS, PostgreSQL (drizzle-orm), and BullMQ. All engineers use shared conventions.

## Tech Stack

- TypeScript 5.4 (strict mode) + Node.js 22 LTS
- NestJS 10 with Fastify adapter
- PostgreSQL 16 via drizzle-orm (NO raw SQL in application code)
- BullMQ + Redis 7 for job queues
- Jest 29 + Supertest for testing
- pnpm workspaces monorepo
- ESLint flat config + Prettier (2-space, single quotes, trailing commas)

## Code Conventions

- `async/await` only — never `.then()/.catch()`
- No `any` — use `unknown` with explicit narrowing
- Named exports only — no default exports, no barrel files
- File naming: `kebab-case.ts`
- NestJS pattern: `<feature>.module.ts`, `<feature>.service.ts`, `<feature>.controller.ts`
- Error handling: always use `AppError` from `packages/core/errors` — never throw plain strings or generic `Error`
- No circular dependencies (enforced by ESLint)
- No `@ts-ignore` or `@ts-expect-error`

## Testing

- Unit tests for all service methods with side effects
- Integration tests for all controller endpoints via Supertest
- Use test factories from `test/factories/` — never construct objects manually in tests
- Inject mocks via DI — no module-level `jest.mock()`
- Test naming: `describe('<Unit>', () => { it('should <behavior> when <condition>', ...) })`

## Pull Requests

- PRs must be < 400 lines (excluding generated files and migrations)
- Every PR needs at least one test covering the new behavior
- Migrations must be reviewed by Ana (`@ana/tech-lead`) before merge
- No self-merging — minimum 1 approval required
- Fill the PR description template: What, Why, How, Risk, Test plan

## AI Review Rules

When reviewing code:
- Check for correctness, type safety, and convention violations (not style — Prettier handles that)
- Flag missing error handling in async paths
- Flag raw SQL outside drizzle-orm
- Flag new endpoints without integration tests
- Flag new endpoints without declared RBAC role
- Never suggest approving a PR with failing CI

## Constraints (Non-negotiable)

- NO raw SQL — all queries through drizzle-orm schema types
- NO `any` type — use `unknown` and narrow
- NO secrets in the repository — ever
- NO new direct dependencies without an ADR in `docs/adr/`
- NO bypassing RBAC — every endpoint declares its required role
- NO modifying migration files after they've been applied to staging or production
- NO `console.log` in production code — use `packages/core/logger`
- NO singleton mutable state outside of NestJS module providers

## Goals

- Correctness over speed — a broken feature costs more than a slow one
- Consistent codebase across all 5 engineers
- PR cycle time under 24 hours
- Zero production incidents from merged code
- Junior team members learn through Claude's explanations, not just receive generated code

## Anti-patterns to Avoid

- Fat controllers: business logic belongs in services
- Barrel files that re-export everything
- Data transforms inside schema migration files
- Returning HTTP 200 for business errors — use proper status codes + `AppError.httpStatus`
- `console.log` in production paths
- Optimistic locking without retry loop