letsbe/pn-new-crm
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
a653c8e0397286dd35b40c1b5e1fec5b17fe636b
pn-new-crm/PROGRESS.md
Matt Ciaccio b5d8e1ecb8 docs: update PROGRESS.md with 2026-03-26 → 2026-04-22 changelog 
Adds a 'Since 2026-03-26' section summarizing the admin/reminders
expansion, multi-address clients, full inquiry notifications feature,
and Next.js 15 build fixes. Updates the Layer 3 reminders entry to
reflect full CRUD + background processors. Marks Priority 1 push-to-
Gitea as done and splits out CI verification as its own checkbox.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-22 02:37:43 +02:00

342 lines
17 KiB
Markdown
Raw Blame History

# Port Nimara CRM - Project Progress
**Last updated:** 2026-04-22
**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
---
## 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).
---
## 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/`
- [x] **Reminders** - Full CRUD with background processors (dispatcher, reminder workers)
- Pages: `/reminders`
- API: `/api/v1/reminders/...` (CRUD, my, overdue, upcoming, complete, dismiss, snooze)
- Service: `reminders.service.ts`
- [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
- [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
- [ ] 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
- [ ] Run database migrations (`drizzle-kit migrate` against prod DB — `0000` + `0001` need to apply)
- [ ] 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 |
Reference in New Issue View Git Blame Copy Permalink