4da8ed3ae4
PR 15 (docs): the numbered spec files mostly described the new model already at the conceptual level, but two needed concrete updates: - 07-DATABASE-SCHEMA.md: schema overview now lists the new Yacht / Company / Reservation domains alongside the existing ones, names the partial unique indexes (idx_yoh_active, idx_br_active) that enforce exclusivity, and notes that yacht/company details are no longer stored on `clients`. - CLAUDE.md: the Conventions section now points future contributors at the new schema files, the polymorphic ownership pattern, the EoiContext/dual-path EOI flow, and the merge-token allow-list. Adds a pointer to the husky `.env*` block so it doesn't trip people up. References the new field-mapping doc and `assets/README.md`. Task 15.3 (Tier 4 golden-image PDF regression) is deferred — those tests need committed reference PDFs that come out of a real, manually verified EOI render. Best landed once the actual `assets/eoi-template.pdf` is in place; tracking as a follow-up. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
103 lines
5.6 KiB
Markdown
103 lines
5.6 KiB
Markdown
# Port Nimara CRM
|
|
|
|
Multi-tenant CRM for marina/port management. Built with Next.js 15 App Router (standalone output), React 19, TypeScript (strict), Tailwind CSS 3, and Drizzle ORM on PostgreSQL.
|
|
|
|
## Quick reference
|
|
|
|
```bash
|
|
pnpm dev # Start dev server
|
|
pnpm build # Production build
|
|
pnpm lint # ESLint
|
|
pnpm format # Prettier
|
|
pnpm db:generate # Generate Drizzle migrations
|
|
pnpm db:push # Push schema to DB
|
|
pnpm db:studio # Drizzle Studio GUI
|
|
pnpm db:seed # Seed database (tsx src/lib/db/seed.ts)
|
|
```
|
|
|
|
## Tech stack
|
|
|
|
- **Framework:** Next.js 15.1 App Router, `output: 'standalone'`, `experimental.typedRoutes`
|
|
- **Auth:** better-auth (session cookie: `pn-crm.session_token`)
|
|
- **Database:** PostgreSQL via `postgres` driver + Drizzle ORM
|
|
- **Queue:** BullMQ + Redis (ioredis)
|
|
- **Storage:** MinIO (S3-compatible)
|
|
- **Realtime:** Socket.IO with Redis adapter
|
|
- **UI:** Radix UI primitives, shadcn/ui components (`src/components/ui/`), Lucide icons, CVA + tailwind-merge + clsx
|
|
- **Forms:** react-hook-form + zod resolvers
|
|
- **Tables:** TanStack Table
|
|
- **State:** Zustand stores (`src/stores/`), TanStack React Query
|
|
- **PDF:** pdfme
|
|
- **Email:** nodemailer + imapflow + mailparser
|
|
- **AI:** OpenAI SDK (optional)
|
|
- **Testing:** Vitest (unit), Playwright (e2e)
|
|
- **Logging:** pino + pino-pretty
|
|
|
|
## Project structure
|
|
|
|
```
|
|
src/
|
|
app/
|
|
(auth)/ # Login/auth pages
|
|
(dashboard)/ # Main app - route: /[portSlug]/...
|
|
(portal)/ # Client portal
|
|
api/ # API routes
|
|
components/
|
|
ui/ # shadcn/ui base components
|
|
layout/ # Shell, sidebar, header
|
|
[domain]/ # Domain components (clients, invoices, berths, etc.)
|
|
shared/ # Cross-domain shared components
|
|
hooks/ # React hooks (use-auth, use-permissions, use-socket, etc.)
|
|
lib/
|
|
api/ # API client utilities
|
|
auth/ # better-auth config
|
|
db/
|
|
schema/ # Drizzle schema (one file per domain)
|
|
migrations/ # Generated Drizzle migrations
|
|
env.ts # Zod env validation (SKIP_ENV_VALIDATION=1 bypasses)
|
|
services/ # Business logic services
|
|
validators/ # Zod schemas for API input validation
|
|
utils/ # Shared utilities
|
|
middleware.ts # Auth middleware (cookie check, redirects)
|
|
providers/ # React context providers
|
|
stores/ # Zustand stores
|
|
types/ # Shared TypeScript types
|
|
```
|
|
|
|
## Conventions
|
|
|
|
- **TypeScript:** Strict mode with `noUncheckedIndexedAccess`. No `any` (ESLint error).
|
|
- **Formatting:** Prettier - single quotes, semicolons, trailing commas, 2-space indent, 100 char line width.
|
|
- **Lint:** ESLint flat config extending `next/core-web-vitals`, `next/typescript`, `prettier`. Unused vars prefixed with `_` are allowed.
|
|
- **Imports:** Use `@/*` path alias (maps to `src/*`).
|
|
- **Components:** shadcn/ui pattern - base components in `src/components/ui/`, domain components in `src/components/[domain]/`. Yacht / company / reservation domains live in `components/yachts`, `components/companies`, `components/reservations` respectively.
|
|
- **DB schema:** One file per domain in `src/lib/db/schema/`, re-exported from `index.ts`. Relations in `relations.ts`. Domain files include `clients.ts`, `yachts.ts`, `companies.ts`, `reservations.ts`, `interests.ts`, `berths.ts`, `documents.ts`, `invoices.ts`, etc.
|
|
- **Polymorphic ownership:** Yachts and invoice billing-entities use `<entity>_type` + `<entity>_id` column pairs (`'client' | 'company'`). Resolve owner identity through `src/lib/services/yachts.service.ts` / `eoi-context.ts` rather than reading the columns ad hoc — those services apply the type discriminator.
|
|
- **EOI generation:** Two pathways share the same `EoiContext` (`src/lib/services/eoi-context.ts`). Documenso pathway calls the template-generate endpoint via `documenso-payload.ts`; in-app pathway fills the same source PDF (`assets/eoi-template.pdf`) via `src/lib/pdf/fill-eoi-form.ts` (pdf-lib AcroForm). Routed through `generateAndSign(...)` in `src/lib/services/document-templates.ts` with a `pathway` parameter.
|
|
- **Merge fields:** Token catalog lives in `src/lib/templates/merge-fields.ts`; the `createTemplateSchema` validator uses `VALID_MERGE_TOKENS` as an allow-list, so unknown tokens are rejected at template creation time.
|
|
- **Routes:** Multi-tenant via `[portSlug]` dynamic segment. Typed routes enabled.
|
|
- **Pre-commit:** Husky + lint-staged runs ESLint fix + Prettier on staged `.ts`/`.tsx` files. The hook also blocks `.env*` files (including `.env.example`) from being committed; pass them via a separate workflow if needed.
|
|
|
|
## Environment
|
|
|
|
Copy `.env.example` to `.env` for local dev. See `src/lib/env.ts` for the full schema. Set `SKIP_ENV_VALIDATION=1` to bypass validation (used in Docker build).
|
|
|
|
## Docker
|
|
|
|
- `Dockerfile` - Production multi-stage build (deps -> build -> runner)
|
|
- `Dockerfile.dev` - Dev with bind-mounted source
|
|
- `Dockerfile.worker` - BullMQ worker process
|
|
- `docker-compose.yml` / `docker-compose.dev.yml` / `docker-compose.prod.yml`
|
|
|
|
## Architecture docs
|
|
|
|
Numbered spec files in repo root (`01-CONSOLIDATED-SYSTEM-SPEC.md` through `15-DESIGN-TOKENS.md`) contain detailed architecture decisions, feature specs, DB schema docs, API catalog, and implementation sequence.
|
|
|
|
Domain-specific references:
|
|
|
|
- `docs/eoi-documenso-field-mapping.md` — canonical mapping from `EoiContext`
|
|
paths to the Documenso template's `formValues` keys, with the matching
|
|
AcroForm field names used by the in-app pathway.
|
|
- `assets/README.md` — what the in-app EOI source PDF must contain and how
|
|
to override its path in dev/test.
|