2.6 KiB
CLAUDE.md
Agent Behavior
Always use pnpm — never npm, yarn, or npx. Use pnpm exec for local binaries, pnpm dlx for one-off execution.
Never run long-running processes (dev servers, watchers, Docker) without explicit permission.
Read relevant docs before implementing — never guess endpoint behavior or payload shapes.
Use dedicated tools, not Bash — Read (not cat/head/tail), Glob (not find/ls), Grep (not grep/rg), Edit (not sed/awk). This applies to all agents and subagents.
Commands
pnpm domain:build # Required after domain changes
pnpm type-check
pnpm lint
pnpm db:migrate
pnpm db:generate
pnpm test # All tests
pnpm --filter @customer-portal/bff test # BFF tests only
Ports: Frontend :3000 | Backend :4000/api | Prisma Studio :5555
Architecture
apps/
├── portal/ # Next.js 15 (React 19, Tailwind, shadcn/ui)
└── bff/ # NestJS 11 (Prisma, BullMQ, Zod)
packages/
└── domain/ # Shared contracts, Zod schemas, provider mappers
Systems of record: WHMCS (billing, subscriptions, invoices, addresses) | Salesforce (CRM, orders) | Portal (UI + BFF orchestration)
Key Conventions
Imports (ESLint enforced):
- Import from module index:
@customer-portal/domain/billing— never root or deep paths - Provider imports (
/providers) are BFF-only, forbidden in Portal
Domain: Each module has contract.ts, schema.ts, index.ts, and providers/ (BFF-only mappers). Map once in mappers, use domain types everywhere.
Portal: Pages in app/ are thin shells — all logic lives in features/ modules. No API calls in app/. Use @/core/logger not console.log.
BFF: Integration services fetch, transform via domain mappers, return domain types. Controllers are thin — use createZodDto(schema) + ZodValidationPipe. Use nestjs-pino logger not console.log.
Validation: Zod-first. Schemas in domain, derive types with z.infer. Use z.coerce.* for query params.
Docs
| Topic | Location |
|---|---|
| Overview | docs/README.md |
| BFF patterns | docs/development/bff/integration-patterns.md |
| Portal architecture | docs/development/portal/architecture.md |
| Domain structure | docs/development/domain/structure.md |
| Salesforce | docs/integrations/salesforce/ |
| WHMCS | docs/integrations/whmcs/ |