230a61c520
- Introduced a new `AccountStatusResult` interface to standardize account status detection across systems. - Updated the `VerificationWorkflowService` to merge handoff data with discovered account status. - Enhanced error handling in `GlobalAuthGuard` and `LocalAuthGuard` to include structured error codes for better clarity in unauthorized responses. - Refined WHMCS and Salesforce integration schemas to ensure consistent data validation and coercion.
66 lines
2.9 KiB
Markdown
66 lines
2.9 KiB
Markdown
# 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.
|
|
|
|
**Never run destructive git commands** — `git stash`, `git checkout -- .`, `git restore .`, `git reset --hard`, `git clean`, or any command that discards uncommitted work. If you need to check pre-existing state, use `git diff` or `git status` — never stash or discard the working tree.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
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/` |
|