d7efede122
Some checks failed
Pull Request Checks / Code Quality & Security (push) Has been cancelled
Security Audit / Security Vulnerability Audit (push) Has been cancelled
Security Audit / Dependency Review (push) Has been cancelled
Security Audit / CodeQL Security Analysis (push) Has been cancelled
Security Audit / Check Outdated Dependencies (push) Has been cancelled
- Migrate all molecule components (DataTable, PaginationBar, FilterDropdown, AlertBanner, FormField, SectionCard, SubCard, MetricCard, AnimatedCard, OtpInput) to shadcn/ui primitives with legacy backups and comparison stories - Install 24 shadcn/ui primitives (accordion, alert, badge, button, card, checkbox, collapsible, dialog, dropdown-menu, input-otp, input, label, pagination, popover, radio-group, select, separator, sheet, skeleton, table, tabs, toggle-group, toggle, tooltip) with barrel exports - Replace 69 raw HTML elements across all features with shadcn components: 35+ <button> → Button, 5 <select> → Select, 15+ <label> → Label, 6 <input type=checkbox> → Checkbox, 7 <input type=radio> → RadioGroup - Add TextRotate animation component and integrate into hero section with rotating service names (Internet, Phone Plans, VPN, IT Support, Business) - Add destructive color token aliases for error state consistency - Add CLAUDE.md rules for shadcn migration process Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
75 lines
3.5 KiB
Markdown
75 lines
3.5 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.
|
|
|
|
**shadcn/ui Component Migration**: When creating or migrating a component to shadcn/ui, always:
|
|
|
|
1. Place the raw shadcn primitive in `components/ui/` (install via `pnpm dlx shadcn@latest add <component>`)
|
|
2. Create an enhanced atom wrapper in `components/atoms/` that preserves the existing public API
|
|
3. Save the old implementation as `<component>.legacy.tsx` for reference
|
|
4. Add a `ComparisonWithLegacy` story in the component's `.stories.tsx` that renders Legacy (left) vs shadcn/ui (right) in a 2-column grid
|
|
5. Export the new ui component from `components/ui/index.ts`
|
|
6. Use `text-destructive` instead of `text-danger`/`text-red-*` for error colors (shadcn convention)
|
|
|
|
## 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/` |
|