Initial commit: Port Nimara CRM (Layers 0-4)
Full CRM rebuild with Next.js 15, TypeScript, Tailwind, Drizzle ORM,
PostgreSQL, Redis, BullMQ, MinIO, and Socket.io. Includes 461 source
files covering clients, berths, interests/pipeline, documents/EOI,
expenses/invoices, email, notifications, dashboard, admin, and
client portal. CI/CD via Gitea Actions with Docker builds.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 11:52:51 +01:00
# Port Nimara CRM - Project Progress
2026-04-22 02:37:43 +02:00
**Last updated:** 2026-04-22
Initial commit: Port Nimara CRM (Layers 0-4)
Full CRM rebuild with Next.js 15, TypeScript, Tailwind, Drizzle ORM,
PostgreSQL, Redis, BullMQ, MinIO, and Socket.io. Includes 461 source
files covering clients, berths, interests/pipeline, documents/EOI,
expenses/invoices, email, notifications, dashboard, admin, and
client portal. CI/CD via Gitea Actions with Docker builds.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 11:52:51 +01:00
**Repo:** https://code.letsbe.solutions/letsbe/pn-new-crm
**Domain:** pn.letsbe.solutions
**Stack:** Next.js 15 + TypeScript + Tailwind + Drizzle ORM + PostgreSQL + Redis + BullMQ + MinIO + Socket.io
---
2026-04-22 02:37:43 +02:00
## Since 2026-03-26
- **Admin surface expanded** — full admin users + roles management, admin ports + system settings management, user settings, expanded audit log, and berth CRUD completions.
- **Reminders system** — promoted from "pages only" to full CRUD with background processors.
- **Multi-address clients** — new `client_addresses` table with a partial unique index enforcing one primary address per client.
- **Inquiry notifications feature (end-to-end)** — public interest form now fires: (a) confirmation email to the inquiring client, (b) in-app notifications to CRM users with `interests.view` , (c) optional email to configured sales recipients. Public schema expanded with first/last name split, address block, and berth mooring lookup. `sendEmail` gained a plain-text fallback. Admin settings UI exposes `inquiry_contact_email` and `inquiry_notification_recipients` . Plan: `docs/superpowers/plans/2026-04-14-inquiry-notifications.md` .
- **Build/infra cleanup** — Next.js 15 static-prerender bugs fixed (Suspense boundaries around `useSearchParams` on `/portal/verify` and `/set-password` ), `.gitattributes` added to enforce LF in the index across Windows/macOS checkouts, Docker production build fixes, CI trimmed to build+push (deploy job removed).
---
Initial commit: Port Nimara CRM (Layers 0-4)
Full CRM rebuild with Next.js 15, TypeScript, Tailwind, Drizzle ORM,
PostgreSQL, Redis, BullMQ, MinIO, and Socket.io. Includes 461 source
files covering clients, berths, interests/pipeline, documents/EOI,
expenses/invoices, email, notifications, dashboard, admin, and
client portal. CI/CD via Gitea Actions with Docker builds.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 11:52:51 +01:00
## What's Been Built (Layers 0-4 Complete)
### Layer 0: Foundation (DONE)
- [x] Next.js 15 project scaffold with TypeScript strict mode
- [x] Tailwind CSS + shadcn/ui component library (full set in `src/components/ui/` )
- [x] PostgreSQL via Drizzle ORM - full schema across 12 schema files
- `berths.ts` , `clients.ts` , `documents.ts` , `email.ts` , `financial.ts` , `interests.ts` , `operations.ts` , `ports.ts` , `relations.ts` , `system.ts` , `users.ts` + `index.ts`
- [x] Better Auth integration with multi-port middleware (`src/middleware.ts` )
- [x] Redis connection (`src/lib/redis.ts` )
- [x] BullMQ queue system with 8 workers: `document-signing.ts` , `email-sync.ts` , `email.ts` , `import.ts` , `maintenance.ts` , `notifications.ts` , `reports.ts` , `webhooks.ts`
- [x] MinIO file storage service (`src/lib/services/storage.ts` , `files.ts` )
- [x] Socket.io real-time server (`src/lib/socket/server.ts` , `events.ts` )
- [x] Docker setup: `Dockerfile` (multi-stage app), `Dockerfile.worker` , `Dockerfile.dev` , `docker-compose.yml` , `docker-compose.dev.yml` , `docker-compose.prod.yml`
- [x] Dashboard layout shell with sidebar, port switcher, navigation (`src/app/(dashboard)/layout.tsx` )
- [x] Auth pages: login, reset-password, set-password
- [x] Seed script (`src/lib/db/seed.ts` )
- [x] ESLint + Prettier + Husky + lint-staged
- [x] Health check endpoint (`/api/health` )
- [x] Rate limiting (`src/lib/rate-limit.ts` )
- [x] Encryption utilities (`src/lib/utils/encryption.ts` )
- [x] Zod validators for all entities (17 validator files in `src/lib/validators/` )
### Layer 1: Core CRUD (DONE)
- [x] **Client Management ** - Full CRUD, contacts, relationships, notes, tags, duplicate detection
- Pages: list (`/clients` ), detail (`/clients/[clientId]` )
- API: full REST at `/api/v1/clients/...` (CRUD, contacts, notes, relationships, tags, restore, export-pdf, options)
- Service: `clients.service.ts`
- Components: `src/components/clients/`
- [x] **Berth Management ** - Full CRUD, specs, tags, status management, waiting list, maintenance
- Pages: list (`/berths` ), detail (`/berths/[berthId]` )
- API: full REST at `/api/v1/berths/...` (CRUD, status, tags, waiting-list, maintenance, export-pdf, options)
- Service: `berths.service.ts` , `berth-rules-engine.ts`
- Components: `src/components/berths/`
- [x] **Auth Admin ** - User management, role builder, port management
- Pages: admin/users, admin/roles, admin/ports, admin/onboarding
- API: `/api/v1/admin/users/` , `/api/v1/admin/roles/`
### Layer 2: Business Workflows (DONE)
- [x] **Interest/Pipeline Management ** - CRUD, pipeline stages, berth linking, recommendations, scoring, timeline
- Pages: list (`/interests` ), detail (`/interests/[interestId]` )
- API: full REST at `/api/v1/interests/...` (CRUD, stage, berth, notes, tags, recommendations, timeline, restore, export-pdf)
- Services: `interests.service.ts` , `interest-scoring.service.ts` , `recommendations.ts`
- Components: `src/components/interests/`
- [x] **Documents & EOI ** - Documenso integration, 3-party signing, webhook receiver, document templates
- Pages: `/documents`
- API: `/api/v1/documents/...` , `/api/v1/document-templates/...` , `/api/webhooks/documenso/`
- Services: `documents.service.ts` , `document-templates.service.ts` , `document-templates.ts` , `documenso-client.ts` , `documenso-webhook.ts` , `document-reminders.ts`
- Components: `src/components/documents/`
- [x] **Expenses & Invoices ** - CRUD, receipt scanner (AI), invoice generation, payment tracking, CSV/PDF export
- Pages: `/expenses` , `/expenses/[id]` , `/expenses/scan` , `/invoices` , `/invoices/[id]` , `/invoices/new`
- API: `/api/v1/expenses/...` (CRUD, scan-receipt, export CSV/PDF/parent-company), `/api/v1/invoices/...` (CRUD, generate-pdf, payment, send)
- Services: `expenses.ts` , `invoices.ts` , `expense-export.ts` , `receipt-scanner.ts`
- Components: `src/components/expenses/` , `src/components/invoices/`
- [x] **File Management ** - MinIO integration, folder management, upload/download/preview
- API: `/api/v1/files/...` (CRUD, upload, download, preview, folders)
- Components: `src/components/files/`
- Store: `src/stores/file-browser-store.ts`
### Layer 3: Operations (DONE)
- [x] **Email System ** - SMTP/IMAP, accounts, thread viewer, composer, AI drafts
- Pages: `/email`
- API: `/api/v1/email/...` (accounts, sync, threads, compose), `/api/v1/ai/email-draft/...`
- Services: `email-accounts.service.ts` , `email-compose.service.ts` , `email-draft.service.ts` , `email-threads.service.ts`
- Components: `src/components/email/`
- [x] **Notifications ** - Notification center, preferences, real-time via Socket.io
- Pages: (integrated in layout)
- API: `/api/v1/notifications/...` (CRUD, preferences, read-all, unread-count)
- Service: `notifications.service.ts`
- Components: `src/components/notifications/`
2026-04-22 02:37:43 +02:00
- [x] **Reminders ** - Full CRUD with background processors (dispatcher, reminder workers)
Initial commit: Port Nimara CRM (Layers 0-4)
Full CRM rebuild with Next.js 15, TypeScript, Tailwind, Drizzle ORM,
PostgreSQL, Redis, BullMQ, MinIO, and Socket.io. Includes 461 source
files covering clients, berths, interests/pipeline, documents/EOI,
expenses/invoices, email, notifications, dashboard, admin, and
client portal. CI/CD via Gitea Actions with Docker builds.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 11:52:51 +01:00
- Pages: `/reminders`
2026-04-22 02:37:43 +02:00
- API: `/api/v1/reminders/...` (CRUD, my, overdue, upcoming, complete, dismiss, snooze)
- Service: `reminders.service.ts`
Initial commit: Port Nimara CRM (Layers 0-4)
Full CRM rebuild with Next.js 15, TypeScript, Tailwind, Drizzle ORM,
PostgreSQL, Redis, BullMQ, MinIO, and Socket.io. Includes 461 source
files covering clients, berths, interests/pipeline, documents/EOI,
expenses/invoices, email, notifications, dashboard, admin, and
client portal. CI/CD via Gitea Actions with Docker builds.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 11:52:51 +01:00
- [x] **Search ** - Global search (inline in topbar), saved views
- API: `/api/v1/search/...` , `/api/v1/saved-views/...`
- Service: `search.service.ts` , `saved-views.service.ts`
- Components: `src/components/search/`
- [x] **Dashboard & Analytics ** - KPIs, pipeline summary, revenue forecast, activity feed
- Pages: `/[portSlug]` (dashboard)
- API: `/api/v1/dashboard/...` (kpis, pipeline, forecast, activity)
- Service: `dashboard.service.ts`
- Components: `src/components/dashboard/`
### Layer 4: Advanced Features (DONE)
- [x] **Webhooks ** - CRUD, delivery tracking, event mapping, test delivery, secret regeneration
- Pages: admin/webhooks
- API: `/api/v1/admin/webhooks/...`
- Services: `webhooks.service.ts` , `webhook-dispatch.ts` , `webhook-event-map.ts`
- [x] **Document Templates ** - Template management with versioning, preview, rollback
- Pages: admin/templates
- API: `/api/v1/admin/templates/...`
- Service: `document-templates.service.ts`
- [x] **AI Features ** - Interest scoring, AI email drafts, receipt scanning
- API: `/api/v1/ai/...`
- Uses OpenAI SDK
- [x] **Custom Fields ** - Dynamic custom fields for entities
- Pages: admin/custom-fields
- API: `/api/v1/admin/custom-fields/...` , `/api/v1/custom-fields/...`
- Service: `custom-fields.service.ts`
- [x] **Reports ** - Report generation with download, scheduled reports
- Pages: `/reports` , admin/reports
- API: `/api/v1/reports/...`
- Services: `reports.service.ts` , `report-generators.ts`
- [x] **Admin Tools ** - Audit log, backup, import, settings, monitoring, forms, tags
- Pages: full admin section
- API: `/api/v1/admin/...` (connections, errors, health, queues)
- Service: `system-monitoring.service.ts`
- [x] **Client Portal ** (separate Nuxt app in `client-portal/` )
- Pages: portal login, verify, dashboard, documents, interests, invoices
- API: `/api/portal/...` (auth, dashboard, documents, interests, invoices)
- Service: `portal.service.ts`
- [x] **Currency ** - Multi-currency with conversion rates
- API: `/api/v1/currency/...`
- Service: `currency.ts`
- [x] **Tags ** - Cross-entity tagging system
- API: `/api/v1/tags/...`
- Service: `tags.service.ts`
- [x] **Record Export ** - PDF export for clients, berths, interests
- Service: `record-export.ts`
- [x] **Settings & Feature Flags **
- Pages: `/settings`
- API: `/api/v1/settings/feature-flag/`
### Testing (Layer 5 - Partially Done)
- [x] 25 E2E smoke tests (Playwright) covering all major flows
- [x] 5 integration tests (Vitest): CRUD audit, custom fields, pipeline transitions, port scoping, webhook delivery
- [x] 15 unit tests (Vitest): validators, encryption, security, audit, interest scoring, query plans, webhook events, etc.
- [x] Test helpers and factories (`tests/helpers/factories.ts` )
- [x] Playwright config with global setup
### Infrastructure (DONE)
- [x] Gitea Actions CI/CD workflow (`.gitea/workflows/build.yml` )
- Lint + type-check on PR
- Docker build + push to Gitea Container Registry on main
- SSH deploy to production server
- [x] Production docker-compose (`docker-compose.prod.yml` ) using registry images
- [x] Nginx config for Docker (`nginx/nginx.conf` )
- [x] Nginx config for host/certbot (`nginx/pn.letsbe.solutions.conf` )
- [x] Environment variable template (`.env.example` )
---
## Project Stats
| Metric | Count |
| -------------------- | ----- |
| TypeScript/TSX files | 461 |
| React components | 133 |
| API route handlers | 120+ |
| DB schema files | 12 |
| Service files | 38 |
| Validator files | 17 |
| BullMQ workers | 8 |
| E2E tests | 25 |
| Integration tests | 5 |
| Unit tests | 15 |
| Pages (dashboard) | 37 |
| Pages (portal) | 6 |
| Pages (auth) | 3 |
---
## What's Left To Do
### Priority 1: Deployment & Go-Live
2026-04-22 02:37:43 +02:00
- [x] Push to Gitea (origin/main at `9d815c4` as of 2026-04-22)
- [ ] Verify CI/CD pipeline builds the latest image and pushes to the Gitea container registry
Initial commit: Port Nimara CRM (Layers 0-4)
Full CRM rebuild with Next.js 15, TypeScript, Tailwind, Drizzle ORM,
PostgreSQL, Redis, BullMQ, MinIO, and Socket.io. Includes 461 source
files covering clients, berths, interests/pipeline, documents/EOI,
expenses/invoices, email, notifications, dashboard, admin, and
client portal. CI/CD via Gitea Actions with Docker builds.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 11:52:51 +01:00
- [ ] Set up server: install Docker, nginx, configure DNS for `pn.letsbe.solutions`
- [ ] Run `certbot --nginx -d pn.letsbe.solutions` for SSL
- [ ] Configure production `.env` on server
2026-04-22 02:37:43 +02:00
- [ ] Run database migrations (`drizzle-kit migrate` against prod DB — `0000` + `0001` need to apply)
Initial commit: Port Nimara CRM (Layers 0-4)
Full CRM rebuild with Next.js 15, TypeScript, Tailwind, Drizzle ORM,
PostgreSQL, Redis, BullMQ, MinIO, and Socket.io. Includes 461 source
files covering clients, berths, interests/pipeline, documents/EOI,
expenses/invoices, email, notifications, dashboard, admin, and
client portal. CI/CD via Gitea Actions with Docker builds.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-26 11:52:51 +01:00
- [ ] Run seed data (`pnpm db:seed` )
- [ ] Verify all services start and health check passes
### Priority 2: Testing & Hardening (Layer 5 - Remaining)
- [ ] Run full E2E test suite against deployed instance and fix failures
- [ ] Run full unit/integration test suite and fix failures
- [ ] Security hardening pass (review SECURITY-GUIDELINES.md checklist)
- [ ] Performance audit (Core Web Vitals, API response times)
- [ ] Load testing with realistic data volumes
### Priority 3: Migration (Layer 6)
- [ ] NocoDB data export scripts
- [ ] Data transformation/mapping (see `NOCODB-MIGRATION-MAPPING.md` )
- [ ] PostgreSQL data import
- [ ] MinIO file reorganization
- [ ] Smoke test migrated data
- [ ] DNS/proxy switchover from old system
- [ ] Old system decommission
### Priority 4: Polish & Nice-to-Haves
- [ ] Dark mode toggle (infrastructure exists via `next-themes` )
- [ ] Mobile responsive polish pass
- [ ] Google Calendar integration for reminders
- [ ] Bulk operations UI refinement
- [ ] Email template system (MJML-based)
- [ ] Client portal deployment as separate service or subdomain
---
## Key Architecture Decisions
| Decision | Choice | Rationale |
| ------------------ | ------------------------- | ------------------------------------------------ |
| Framework | Next.js 15 (App Router) | Server Components, streaming, typed routes |
| ORM | Drizzle | Type-safe, lightweight, PostgreSQL-native |
| Auth | Better Auth | Multi-tenant, role-based, session management |
| State | Zustand + React Query | Zustand for UI state, RQ for server state |
| Queue | BullMQ + Redis | Background jobs, email sync, reports |
| Storage | MinIO | S3-compatible, self-hosted, encrypted |
| Real-time | Socket.io + Redis adapter | Notifications, live updates |
| UI | shadcn/ui + Tailwind | Accessible, customizable components |
| Signing | Documenso | Self-hosted document signing |
| AI | OpenAI | Receipt scanning, interest scoring, email drafts |
| Container Registry | Gitea built-in | Same host as git, simpler auth |
---
## File Structure Overview
```
src/
app/
(auth)/ # Login, reset-password, set-password
(dashboard)/ # Main CRM - all [portSlug] scoped pages
(portal)/ # Client-facing portal
api/ # All API routes (v1/, portal/, webhooks/, auth/, health/)
components/
admin/ # Admin panel components
berths/ # Berth management UI
clients/ # Client management UI
dashboard/ # Dashboard widgets
documents/ # Document management UI
email/ # Email client UI
expenses/ # Expense tracking UI
files/ # File browser UI
interests/ # Interest/pipeline UI
invoices/ # Invoice management UI
layout/ # Sidebar, topbar, navigation
notifications/ # Notification center
portal/ # Client portal components
reports/ # Report views
search/ # Global search
shared/ # Shared components
ui/ # shadcn/ui base components
hooks/ # React hooks
jobs/ # BullMQ job definitions
lib/
auth/ # Better Auth config
db/ # Drizzle schema, migrations, seed
queue/ # Queue definitions, workers
services/ # Business logic (38 service files)
validators/ # Zod schemas (17 validator files)
socket/ # Socket.io config
providers/ # React context providers
stores/ # Zustand stores
types/ # TypeScript type definitions
```
---
## How to Continue Development
```bash
# Clone and install
git clone https://code.letsbe.solutions/letsbe/pn-new-crm.git
cd pn-new-crm
pnpm install
# Start dev environment (needs Docker for PostgreSQL + Redis)
docker compose -f docker-compose.dev.yml up -d
cp .env.example .env # then edit with real values
pnpm dev
# Run tests
pnpm exec vitest run
pnpm exec playwright test
# Build for production
pnpm build
# Database operations
pnpm db:push # Push schema to database
pnpm db:generate # Generate migration files
pnpm db:seed # Seed with sample data
pnpm db:studio # Open Drizzle Studio GUI
```
---
## Spec Documents Reference
| Doc | Purpose |
| ------------------------------------ | ---------------------------------- |
| `01-CONSOLIDATED-SYSTEM-SPEC.md` | Full system specification |
| `02-FEATURE-INVENTORY.md` | Feature keep/cut/rethink decisions |
| `03-ARCHITECTURE-DECISIONS.md` | Architecture exploration |
| `04-ARCHITECTURE-COMPARISON.md` | Stack comparison |
| `05-FINAL-ARCHITECTURE-DECISIONS.md` | Final architecture choices |
| `06-MASTER-FEATURE-SPEC.md` | Detailed feature specifications |
| `07-DATABASE-SCHEMA.md` | Database schema design |
| `08-API-ENDPOINT-CATALOG.md` | Full API endpoint list |
| `09-BUSINESS-RULES.md` | Business logic rules |
| `10-AUTH-AND-PERMISSIONS.md` | Auth & permission model |
| `11-REALTIME-AND-BACKGROUND-JOBS.md` | Socket.io & BullMQ design |
| `12-IMPLEMENTATION-SEQUENCE.md` | Build order & dependencies |
| `13-UI-PAGE-MAP.md` | Page layout specifications |
| `14-TECHNICAL-DECISIONS.md` | Technical trade-off decisions |
| `15-DESIGN-TOKENS.md` | Design system tokens |
| `NOCODB-MIGRATION-MAPPING.md` | NocoDB to PostgreSQL mapping |
| `SECURITY-GUIDELINES.md` | Security requirements |
