pn-new-crm/docs/new-system-feature-summary.md

Port Nimara CRM — What's New & What's Improved

A client-friendly summary of the new Port Nimara CRM, framed against what the previous system provided. The new platform is a complete, purpose-built CRM that replaces a website + spreadsheet-style data store with a single integrated workspace for sales, berths, documents, communications, and reporting.

Scope note: this summary covers the features that are ready for the beta launch. The new client portal, the tenancies module, and the new invoicing module are still being finalised and are intentionally not included here.

---

At a glance

Previously, day-to-day sales work happened across three places: the public website (where enquiries landed), the back-end database tool (where data was inspected and edited), and a separate internal portal (where signing, expenses, and a handful of staff tools lived).

Now, all of that lives inside a single, branded CRM at crm.portnimara.com-style URLs (one per port). The website still publishes berths and accepts enquiries — but those enquiries flow into the CRM and are managed there, from first contact through deposit, contract, and signing.

The CRM is built on a dedicated relational database designed specifically for marina sales workflows, with real-time updates, role-based permissions, a full audit trail, and a clean modern interface that adapts to mobile.

---

Platform-level upgrades

These improvements apply across every feature area:

• Purpose-built database. The system runs on a dedicated relational database (PostgreSQL) modelled specifically for marina sales. Compared with the previous spreadsheet-style data store, it's faster on large data sets, supports rich relationships between entities (clients, companies, yachts, berths, deals, documents), and enforces data integrity so duplicates and broken links don't slip through.
• Real-time updates. When a colleague edits a deal, advances a stage, attaches a file, or completes a signing, every other open window updates within a second. No more "refresh to see what changed".
• Per-port branding and configuration. Each port has its own URL slug, logo, primary colour, default currency, timezone, and email templates. Emails, PDFs, and the in-app shell all pick up the right brand automatically.
• Granular role-based permissions. Roles are defined per resource (clients, berths, documents, expenses, reports, etc.) with separate view / create / edit / delete / export verbs. Admins can override permissions per user as well as per role.
• Full audit trail. Every meaningful change (who, what, before-and-after, when) is recorded, retained for 90 days, and searchable. Used in the activity feed, the field-history popovers, and the admin audit log.
• Backups and operational tooling. Automatic daily database backups, weekly cleanup, configurable retention windows, and a built-in system-monitoring dashboard for staff to verify the queue and integrations are healthy.
• Background job queue. Heavy or slow work (PDF generation, email sending, exports, webhook retries, bounce polling) runs on a managed queue so the interface stays responsive and nothing is silently lost.
• GDPR-ready. One-click Article 15 data exports per client, automatic 30-day cleanup of export bundles, and a permissioned hard-delete flow for Article 17 requests.
• Pluggable file storage. Files live in object storage (S3-compatible) by default, with a one-command migration script to switch backends without rewriting any code.

---

1. Sales pipeline

A complete sales CRM where the team manages every deal from first enquiry to contract.

• Kanban board across seven canonical stages (Enquiry → Qualified → Nurturing → EOI → Reservation → Deposit Paid → Contract) with drag-and-drop, per-column counts, and completed-deal hiding.
• List view with sorting, filtering, paging, card / table toggle, bulk actions, and saved views per user.
• Deal detail page with tabs for overview, EOI, contract, reservation, documents, contact log, notes, and timeline. Every field is inline-editable in place — no separate edit modal to wade through.
• Multi-berth interests. A single deal can attach multiple berths with three independent flags: which berth is the deal's primary, which are publicly "under offer", and which are included in the EOI bundle. The previous system stored at most a single berth link per enquiry.
• Auto-advancing stages. Deposits hitting their expected amount, EOI completion, contract signing, etc. move the deal forward automatically; staff can intervene if the rules need overriding.
• Pipeline rules engine. Seven configurable triggers (EOI sent, EOI signed, deposit received, contract signed, deal archived, deal completed, berth unlinked) each with auto / suggest / off modes and a per-port target berth status. Admins can tune the rules without engineering involvement.
• Outcomes. Terminal outcomes (won, lost to another marina, lost unqualified, lost no response, cancelled) are captured via an outcome dialog with required reason capture.
• Tags, notes, contact log, and activity timeline on every deal. Tags are inline-editable; notes use a single underlying engine shared across clients, deals, yachts, and companies.
• Saved views and recently-viewed. Each user can pin reusable filter+sort snapshots; recently-viewed items appear in the topbar for quick return.
• Lead scoring badge and qualification checklist. Per-port qualifying criteria are admin-defined; each deal shows a checklist and a derived score.
• Bulk actions. Change stage, add/remove tags, archive — with confirmation dialogs and audit-logged outcomes.
• Pipeline summary on each client. All a client's open and historic deals roll up onto their detail page.

Previously, deal management happened directly inside the back-end data tool — no kanban, no stage workflow, no auto-advance, no tags, no notes per deal, no scoring, and no per-deal timeline.

---

2. Berths

Catalog, public-facing feed, recommender, demand signals, and rich per-berth artefacts.

• Catalog with list and card views, filterable by status, area, dimensions; every field inline-editable on the detail page.
• Public berth feed at /api/public/berths and /api/public/berths/[mooringNumber] feeds the marketing site. Output mirrors the previous shape exactly so the website didn't need a rewrite; status is computed with a clear precedence (Sold > Under Offer > Available) and served from a 5-minute cache for fast page loads.
• Per-berth PDFs are versioned. Every upload creates a new version; the current version is the live one. PDFs are parsed automatically through three tiers (form-fields → OCR → optional AI), and the system flags mismatches when the mooring number on the PDF doesn't match the berth.
• Per-port brochures. Multiple brochures supported per port with one default enforced. Same upload + version flow as berth PDFs.
• Send-berth-PDF dialog. Branded email composition that attaches the berth PDF (or shares a signed-URL link when the file is over the size threshold).
• Berth recommender. A pure-SQL ranking that surfaces matching berths per deal via a four-tier ladder (A/B/C/D). Tier B uses heat scoring; weights are configurable in admin so the model can be tuned per port.
• Demand heat scoring. Per-berth demand intensity, shown on the dashboard widget and on each berth's detail panel.
• Active interests popover. Hover/tap any berth to see which deals are currently linked to it.
• Bulk price edit. A sheet for updating prices across many berths at once.
• Bulk-add berths wizard for onboarding new inventory in batches.
• Catch-up wizard to reconcile legacy state when migrating berth data.

Previously, berths were a flat list with a basic dimension filter on the public site. There was no recommender, no demand heat, no per-berth PDF versioning, no bulk price editor, and no internal berth detail page.

---

3. Yachts

First-class yacht records with proper ownership and history.

• Polymorphic ownership. A yacht can be owned by either a client (individual) or a company; the system models this correctly throughout — search, documents, pipelines, and reports all respect the discriminator.
• Ownership history. Every transfer is recorded with date and parties; previous owners are visible from the yacht detail.
• Yacht transfer dialog for moving a yacht between owners (client → client, client → company, etc.) with audit trail.
• Inline editing of all dimensions and identifiers; dimensions are normalised and validated.
• Yacht picker reused everywhere — when creating a deal, attaching a document, or filing under an entity, the same searchable picker appears.

Previously, yachts were not stored as their own records — they were free-text fields on enquiry submissions.

---

4. Companies & memberships

First-class company entities with member relationships.

• Companies list and detail with tabs for overview, members, owned yachts, and files.
• Members management. Add/remove members with active/inactive state and roles. Membership reach feeds into the documents projection (a client gets to see relevant company files automatically).
• Polymorphic ownership. Companies can own yachts and be the contractual party on a deal, mirrored across the codebase rather than improvised per surface.
• Files tab on company detail showing both directly-attached files and files reaching through related entities.

Previously, companies did not exist as a separate concept; everything was attributed to a single named individual.

---

5. Clients

The detail page each contact deserves.

• Single detail page with tabs for overview, deals, yachts, companies, files, contact log, and notes.
• Inline editing everywhere. Name, addresses, phone numbers, emails, sales rep, communication preferences — all editable in place via small inline fields.
• Multi-channel contacts. Multiple emails and phone numbers per client, with primary flagging and canonical normalisation (phone numbers are normalised to a single international format for reliable search and matching).
• Audit-driven field history. Click any field's history icon to see who changed it, when, and what the previous value was.
• Tags, notes, and contact log — all the same shared components as elsewhere, so the experience is consistent.
• Pipeline summary. All a client's deals — open and closed — roll up onto their detail page.
• Smart archive / smart restore. Archive a client and the system handles cascading state (related deals, files) intelligently; restore previews exactly what will come back.
• Hard-delete with bulk variant behind a permission gate, for genuine "remove from the system" requests.
• GDPR Article 15 export button. One click queues a ZIP bundle (JSON + readable HTML) and emails the client a signed download link; the bundle auto-deletes after 30 days.
• Dedup engine. The system surfaces probable duplicates and offers a merge flow that consolidates linked records, notes, files, and audit trail correctly.
• Send-documents dialog for branded multi-attachment sends from any client.

Previously, contact records were flat rows in the back-end tool — no detail page, no inline editing, no audit history, no GDPR export, no dedup, no per-client deal roll-up.

---

6. Documents hub

A nestable folder tree per port with intelligent auto-filing.

• Tree of folders with nestable subfolders, drag-and-drop move, rename, soft-rescue delete (children re-parent rather than disappear).
• System folders for each entity type — Clients/, Companies/, Yachts/ — auto-populated with per-entity subfolders the first time a record needs one.
• Auto-filing on signing. When a Documenso envelope completes, the signed PDF lands in the right entity folder automatically based on who owns the deal — no manual filing needed.
• Aggregated view across relationships. Open a client and you also see files attached to their companies and yachts, grouped under clear headings (Directly Attached / From Company / From Yacht / From Client). Each group is capped to keep the view skimmable; deeper drill-down is one click away.
• Rich file preview. PDFs render inline; images preview at sensible sizes; everything else gets an icon, type label, and download.
• Upload for signing dialog. Send any file straight into a Documenso signing flow without leaving the documents hub.
• In-flight workflow tracker — see which envelopes are mid-signing across the same aggregated reach.
• Permissions scoped by role: separate view and manage_folders verbs; system folders are immutable via API to keep the structure clean.
• Recent files surface in the topbar and global search.

Previously, file management lived in the separate internal portal as a flat S3 file browser with no folder tree, no auto-filing, no aggregated-by-entity view, and no signing-integration on individual files.

---

7. EOI generation & Documenso signing

Template-driven EOIs with multi-berth support and resilient signing.

• Two pathways from one underlying model. EOIs can be generated through Documenso templates (the primary path) or filled into the in-app EOI PDF directly. Both share the same data context, so any change to a deal is reflected identically.
• Multi-berth EOI ranges. When an EOI bundles multiple berths, the document automatically renders a compact range ("A1–A3, B5–B7") in the Berth Number field, and the CRM UI shows the full set as chips. The catalogued merge tokens are enforced at template-creation time so a mistyped placeholder cannot silently slip into a generated document.
• Configurable signing order. Parallel or sequential signing per port, with a tri-state default ("use template default / always parallel / always sequential").
• Automation modes per deal: manual (staff sends each step), sequential auto (system advances on each signature), or concurrent auto (everyone signs at once). Mode changes are audit-logged.
• Idempotent webhook handling. Documenso retries don't double-write; status changes are normalised across both supported API versions; the system polls every 5 minutes as a safety net if a webhook is missed.
• Rejection reasons captured when a signer declines.
• Reminders and voids. The CRM surfaces send-reminder and void-envelope actions directly from the deal detail.
• Embedded signing card for clients to sign in-app where appropriate.
• External EOI upload. Record an EOI that was signed outside the system (PDF upload + counterparty list) without breaking the rest of the deal flow.
• Webhook health card in admin shows recent deliveries, failures, and a "test now" affordance.
• Per-port Documenso configuration. Each port can target its own Documenso instance, API key, signing order, and redirect URL.

Previously, signing was a Documenso embed hosted from the internal portal with token-based redirects, no multi-berth range support, no idempotent webhook handling, no automation modes, and no health diagnostics in the UI.

---

8. Email send-outs

Branded, audited, configurable outbound mail.

• Per-port branded templates. Every transactional email (invites, signing notifications, residential and berth enquiries, contract-related comms, digests, etc.) shares a single branded shell — port logo, blurred overhead background, consistent typography — that picks up the port's branding automatically.
• Configurable send-from accounts. Each port can configure its human send-from (e.g. sales@portnimara.com) and its automation send-from (e.g. noreply@portnimara.com). SMTP/IMAP credentials are encrypted at rest; API endpoints return only "is set" markers, never the password.
• Compose dialog with rich body (markdown rendered safely with a strict allow-list), multi-attachment, and live preview.
• Smart attachment handling. Files over a configurable per-port size threshold ship as 24-hour signed-URL links instead of attaching directly, keeping email deliverable.
• Send rate limit (50 sends/user/hour) to protect deliverability reputation.
• Email audit log. Every send is recorded with recipient list, body, attachments, and links; admin can browse the full send log.
• Inbound bounce monitoring. A scheduled job (every 15 minutes) reads non-delivery reports and matches them back to the original send so staff know a message bounced.
• Email threads stitched together — replies to a CRM-originated email are threaded under the original.
• Tracked-link composer. Generate per-recipient tracked links so opens and click-throughs can be attributed back.
• Per-port template overrides. Admin can override any transactional template per port without touching code.
• Notification digests. Hourly digest assembled from each user's unread notifications above a threshold.

Previously, transactional email was sent via Gmail SMTP from string-template builders, with no per-port branding override, no send audit log, no bounce monitoring, no attachment-threshold logic, no rate limiting, and no per-template overrides without a redeploy.

---

9. Reports

Live Sales and Operational dashboards, plus a custom builder, scheduling, and exports.

• Sales report with KPI strip (deals open, EOIs sent this month, deposits received, win rate, average days-in-stage, conversion by source, etc.), pipeline funnel, stage-velocity chart, source-conversion chart, rep leaderboard, deal-heat panel, win-rate-over-time line, and supporting detail tables. Every filter (stage, lead category, outcome) applies live.
• Operational report with an operational heatmap and signing-box plot — used to spot bottlenecks in the signing/operations pipeline.
• Custom report builder (MVP). Pick an entity, choose columns, pick a date range, and run. Four entities are live at launch; additional entities and column-level controls roll out incrementally.
• Save / load / save-as templates. Any report configuration can be saved as a named template with an optional shareable link, then re-run on demand.
• Scheduled runs. Weekly, monthly, or quarterly cadences; system runs the report on schedule and (optionally) emails the recipients a branded PDF. Run history is browsable in admin.
• PDF exports are server-side rendered with a branded cover page. CSV and Excel exports also available client-side from every list.
• Status badges for each scheduled run so admin can see at a glance which schedules are healthy.
• Charts use a mix of standard chart libraries — simple bars/lines/pies on top of a strong charting library, with heatmaps and funnels handled by a separate engine tuned for that purpose.

Previously, there were no in-system reports. Staff exported NocoDB views to spreadsheets and built reporting by hand each time.

---

10. Admin

A purpose-built admin surface organised into seven domain groups.

• Admin sections browser that groups every admin page under: Brand & Communication, Sales Workflow, Catalog, Identity & Access, Inbox & Data Quality, Integrations, and System & Observability.
• 42 dedicated admin pages covering: AI usage caps, audit log, backups, berths, branding, brochures, custom fields, Documenso health, duplicates, email accounts, email templates, error log, forms, inquiries, invitations, monitoring, OCR, onboarding, pipeline rules, ports, "pulse" health indicators, qualification criteria, reminders, reports admin, residential stages, roles, sends log, settings, storage, tags, templates, users, vocabularies, webhooks, and website analytics.
• Permissions UI. Browse roles, edit role definitions, browse users, and assign per-user overrides through a visual permission matrix.
• Settings registry. A single source of truth for every configurable setting, with sections for email, Documenso, storage, pipeline auto-advance, AI providers, application URLs, operations toggles, residential partner integration, and more. Settings are per-port and validated.
• System monitoring dashboard. Service health, queue depth, queue detail, reconcile state — all in one place.
• Port configuration for adding new ports with their own branding, currency, timezone, and email background.
• Webhooks admin for dispatching CRM events outward to external systems.
• Tags, vocabularies, and custom fields that tenants can shape themselves without engineering involvement.
• Forms admin for creating supplemental info-request forms (used in qualification, residential, etc.).
• Onboarding checklist and banner to guide new ports through setup.

Previously, "admin" meant opening the back-end data tool directly to edit rows, with no permissions model, no role assignments, no settings UI, no monitoring, and no onboarding flow.

---

11. Search

A fast, fuzzy, permission-aware global search.

• Topbar search across every entity — clients, residential clients, yachts, companies, deals, berths, invoices, expenses, documents, files, reminders, brochures, tags, plus navigation/settings deep-links.
• Multiple match strategies. Full-text search for documents, partial-word matching for names and titles, fuzzy trigram matching so "Jhon" still finds "John", canonical phone-number matching that ignores formatting differences, and direct ID lookup for paste-a-record-id workflows.
• Affinity ranking. Results you've recently touched are promoted, so "your John" appears above "some other John".
• Cross-port super-admin pass. Super-admin users see other-port matches in a separate, clearly-labelled section.
• Permission-aware. Viewers don't see search results they couldn't open.
• Mobile search overlay designed for thumb reach.
• Highlighted match terms so the relevant substring jumps out in each result.
• Admin search across the 7 IA domains — every admin page is reachable from the topbar with a keyword.

Previously, "search" meant filtering a single NocoDB table at a time. There was no global search, no cross-entity matching, no fuzzy matching, no affinity ranking, and no admin deep-link search.

---

12. Activity feed & notifications

A unified activity feed and a notification engine for both in-app and email.

• Dashboard activity widget shows recent meaningful events across the port.
• Per-entity activity feed on every client, deal, berth, yacht, and company detail page.
• Standardised verb vocabulary — created, updated, archived, restored, merged, transferred, sent, signed, completed, rejected, voided, and so on. Historical legacy-stage events are re-mapped to the current vocabulary so the timeline reads consistently.
• My reminders rail on the dashboard surfaces due and overdue follow-ups.
• Reminders engine with admin configuration (cadence, severity, recipients).
• Alert engine. Rule-based alerts evaluated every 5 minutes — admins define the rules; the engine generates notifications when they fire.
• In-app inbox in the topbar.
• Hourly notification digest email when unread items pass a threshold.

Previously, there was no in-system activity feed, no reminders engine, and no rule-based alerting.

---

13. Analytics

Website analytics, email-open tracking, and outcome events feeding into a privacy-respecting analytics platform.

• Website-analytics dashboard in the CRM with: realtime visitors panel, world map of visitors, sessions list, session detail sheet, weekly heatmap, pageviews chart, top referrers / pages / devices, and per-metric detail shells.
• Per-port project linking to a Umami analytics project — outcome events from the CRM (EOI sent, deposit received, etc.) cross-post to the same project so marketing and sales metrics share a timeline.
• Email-open pixel. Branded sends include a small open-tracking pixel; opens are recorded against the original send and surface in the send audit log.
• Admin → website-analytics for configuring the link to the Umami project.

Previously, website analytics lived only in the standalone analytics tool; there was no integration of marketing analytics into the sales surface.

---

14. Mobile & responsive design

Designed mobile-first; every list, sheet, and dialog is touch-friendly.

• Dedicated mobile shell when the viewport is small: a mobile topbar, bottom tab bar, and a "more" sheet for overflow navigation.
• Card mode toggle on every list. Switch lists between table and card view; card view is the default on mobile.
• Mobile search overlay designed for thumb reach.
• Responsive tab strips that collapse intelligently.
• Touch-tuned form controls. Phone input, country picker, and timezone picker are all built for mobile keyboards.

Previously, the back-end data tool the team used was not designed for phone use; staff worked from a laptop by necessity.

---

15. Security & compliance

A defensive posture across the stack.

• Authentication via better-auth with session cookies; branded login, reset-password, and set-password surfaces.
• CRM invitations with a token-based admin-driven invite flow.
• Granular RBAC. Per-resource, per-action permissions — applied at the service layer, not just the UI.
• Audit log everywhere. All meaningful actions recorded with severity tier; 90-day retention configurable.
• GDPR Article 15 exports (one-click bundle, signed download, 30-day cleanup) and Article 17 hard-delete with restore preview.
• PII masking at audit-write time. Old metadata still expires per retention; new metadata is masked before insertion.
• Magic-byte PDF validation on every upload path (both in-server and presigned-PUT).
• Timing-safe webhook verification for Documenso (no leaky string comparisons).
• Defense-in-depth port scoping on every aggregated query — even joins double-check port_id so a cross-tenant leak would have to bypass multiple checks.
• 30-second timeouts on object-storage calls so a slow MinIO/S3 host can't stall the application.
• Per-port encryption-at-rest for SMTP/IMAP credentials.
• Pre-commit hooks block accidental commits of secrets (.env files including .env.example).

Previously, the public website ran public forms straight into the data store with reCAPTCHA only; there was no audit log on website-originated changes, no permission model on the public surface, no GDPR-Article-15 export tooling, and no PDF content validation.

---

16. Multi-tenancy at port level

The platform is designed from the ground up for multiple ports.

• Per-port URL slug. Each port has its own URL prefix, brand, and configuration.
• Per-port branding — logo, primary colour, default currency, timezone, branded email background.
• Per-port email templates — every transactional template can be overridden per port from admin, without engineering involvement.
• Per-port Documenso configuration — API version (v1 or v2), API key, signing order, redirect URL.
• Per-port storage backend — choose S3-compatible or filesystem per port; switch with a single migration script.
• Per-port currency and timezone flow through the scheduler, the dashboard's timezone-drift banner, the recommender's deposit defaults, and every report.
• Per-port sales settings — qualification criteria, pipeline rules, recommender weights, send-from accounts, and AI budgets are all scoped to the port.
• Cross-port super-admin search — super-admins see other-port matches in a clearly-labelled secondary section; otherwise all queries scope to the current port.

Previously, the system was effectively single-tenant — a separate deployment would have been needed to onboard a second port.

---

What's net-new (not present in the previous system at all)

• A full sales CRM with kanban, list, detail, inline editing, stages, outcomes, tags, notes, scoring, and qualification — for staff.
• Yachts, companies, and memberships as first-class entities (the previous system had no concept of these).
• A nestable documents hub with auto-filing and cross-relationship aggregation.
• Reports — Sales and Operational dashboards plus a custom builder, with templates and scheduled runs.
• Global cross-entity search with fuzzy matching and affinity ranking.
• An activity feed, reminders, alert engine, and notification digest.
• Per-port multi-tenancy (branding, configuration, currency, timezone, Documenso, storage).
• Granular role-based permissions with per-user overrides.
• A comprehensive audit log surfaced in the activity feed, field-history popovers, and admin audit log.
• GDPR Article 15 export tooling and Article 17 hard-delete with restore preview.
• Background job queue + scheduled cron jobs for reliability.
• Real-time UI updates across every open session.
• Mobile-first design with a dedicated mobile shell.
• Website-analytics dashboard inside the CRM (with email-open tracking and event cross-posting).

What stays similar but is improved

• Berth catalog and public berth feed. The data the marketing site sees is the same shape it always was, served from a faster, properly-cached endpoint backed by the new database. The internal side adds versioned per-berth PDFs, brochures, a recommender, and demand heat scoring.
• EOI generation and Documenso signing. EOIs still flow through Documenso, but with multi-berth ranges, configurable signing order, automation modes, idempotent webhook handling, a 5-minute polling safety net, in-product reminders and voids, external-EOI upload, and a webhook health diagnostic.
• Transactional email. Still SMTP-backed, but now with per-port branded templates, configurable send-from accounts, audited sends, bounce monitoring, attachment-threshold smart handling, and rate limits.
• Public enquiry intake. The website still accepts enquiries, but they now land in a managed inbox in the CRM with deduping, owner assignment, and full audit, instead of becoming raw rows in the data store.