pn-new-crm/docs/features-list.md

# Port Nimara CRM — Feature List

A complete, purpose-built CRM for marina/port management: a single integrated workspace for sales, berths, documents, communications, and reporting, with the public website's berth feed and enquiry intake flowing directly into it. Multi-tenant by design — one branded instance per port.

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

---

## Platform foundations

Apply across every feature area:

- **Purpose-built relational database (PostgreSQL)** modelled specifically for marina sales — fast on large data sets, rich relationships between entities (clients, companies, yachts, berths, deals, documents), and enforced data integrity.
- **Real-time updates.** Edits, stage changes, file attachments, and completed signings propagate to every open window within a second.
- **Per-port branding and configuration.** Each port has its own URL slug, logo, primary colour, default currency, timezone, and email templates, applied automatically to emails, PDFs, and the in-app shell.
- **Granular role-based permissions.** Defined per resource (clients, berths, documents, expenses, reports, etc.) with separate view / create / edit / delete / export verbs. Per-user overrides on top of per-role definitions.
- **Full audit trail.** Every meaningful change (who, what, before-and-after, when) recorded, retained 90 days, and searchable — surfaced in the activity feed, field-history popovers, and admin audit log.
- **Backups and operational tooling.** Automatic daily database backups, weekly cleanup, configurable retention, and a built-in system-monitoring dashboard.
- **Background job queue.** PDF generation, email sending, exports, webhook retries, and bounce polling run on a managed queue so the interface stays responsive.
- **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.** Object storage (S3-compatible) by default, with a one-command migration script to switch backends.

---

## 1. Sales pipeline

- **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.
- **Multi-berth interests.** A single deal can attach multiple berths with three independent flags: which berth is primary, which are publicly "under offer", and which are included in the EOI bundle.
- **Auto-advancing stages.** Deposits hitting their expected amount, EOI completion, contract signing, etc. move the deal forward automatically; staff can override.
- **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. Admin-tunable.
- **Outcomes.** Terminal outcomes (won, lost to another marina, lost unqualified, lost no response, cancelled) captured via an outcome dialog with required reason.
- **Tags, notes, contact log, and activity timeline** on every deal.
- **Saved views and recently-viewed.** Pin reusable filter+sort snapshots; recently-viewed items appear in the topbar.
- **Lead scoring badge** and **qualification checklist.** Per-port qualifying criteria are admin-defined; each deal shows a checklist and derived score.
- **Bulk actions.** Change stage, add/remove tags, archive — with confirmation dialogs and audit-logged outcomes.
- **Pipeline summary on each client.** All open and historic deals roll up onto the client detail page.

---

## 2. Berths

- **Catalog with list and card views**, filterable by status, area, and dimensions; every field inline-editable on the detail page.
- **Public berth feed** at `/api/public/berths` and `/api/public/berths/[mooringNumber]` for the marketing site; status computed with a clear precedence (Sold > Under Offer > Available), served from a 5-minute cache.
- **Versioned per-berth PDFs.** Every upload creates a new version; the current version is live. Three-tier automatic parsing (form-fields → OCR → optional AI), with mooring-number mismatch flagging.
- **Per-port brochures.** Multiple brochures per port with one enforced default; same upload + version flow as berth PDFs.
- **Send-berth-PDF dialog.** Branded email composition that attaches the berth PDF (or a signed-URL link when over the size threshold).
- **Berth recommender.** Pure-SQL ranking surfacing matching berths per deal via a four-tier ladder (A/B/C/D); Tier B uses heat scoring with admin-configurable weights.
- **Demand heat scoring.** Per-berth demand intensity, shown on the dashboard widget and each berth's detail panel.
- **Active interests popover.** Hover/tap any berth to see which deals are currently linked.
- **Bulk price edit.** A sheet for updating prices across many berths at once.
- **Bulk-add berths wizard** for onboarding inventory in batches.
- **Catch-up wizard** to reconcile legacy state when migrating berth data.

---

## 3. Yachts

- **Polymorphic ownership.** A yacht can be owned by a client or a company; respected throughout search, documents, pipelines, and reports.
- **Ownership history.** Every transfer recorded with date and parties; previous owners 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 normalised and validated.
- **Reusable yacht picker** — the same searchable picker appears when creating a deal, attaching a document, or filing under an entity.

---

## 4. Companies & memberships

- **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 the documents projection so a client sees relevant company files automatically.
- **Polymorphic ownership.** Companies can own yachts and be the contractual party on a deal.
- **Files tab** showing both directly-attached files and files reaching through related entities.

---

## 5. Clients

- **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.
- **Multi-channel contacts.** Multiple emails and phone numbers per client, with primary flagging and canonical phone normalisation for reliable search and matching.
- **Audit-driven field history.** Per-field history icon shows who changed a value, when, and the previous value.
- **Tags, notes, and contact log** via shared components for a consistent experience.
- **Pipeline summary.** All a client's deals (open and closed) roll up onto the detail page.
- **Smart archive / smart restore.** Archiving cascades related state intelligently; restore previews exactly what comes back.
- **Hard-delete with bulk variant** behind a permission gate.
- **GDPR Article 15 export button.** One click queues a ZIP bundle (JSON + readable HTML) and emails a signed download link; auto-deletes after 30 days.
- **Dedup engine.** Surfaces probable duplicates and offers a merge flow that consolidates linked records, notes, files, and audit trail.
- **Send-documents dialog** for branded multi-attachment sends from any client.

---

## 6. Documents hub

- **Folder tree** with nestable subfolders, drag-and-drop move, rename, and soft-rescue delete (children re-parent rather than disappear).
- **System folders per entity type** — `Clients/`, `Companies/`, `Yachts/` — auto-populated with per-entity subfolders on first use.
- **Auto-filing on signing.** When a signing envelope completes, the signed PDF lands in the correct entity folder automatically, based on who owns the deal.
- **Aggregated view across relationships.** A client's files plus files attached to their companies and yachts, grouped under clear headings (Directly Attached / From Company / From Yacht / From Client), each group capped for skimmability.
- **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 signing flow from the hub.
- **In-flight workflow tracker** — which envelopes are mid-signing across the aggregated reach.
- **Permissions** scoped by role: separate `view` and `manage_folders` verbs; system folders immutable via API.
- **Recent files** surfaced in the topbar and global search.

---

## 7. EOI generation & document signing

- **Two pathways from one model.** EOIs generated through document-signing templates (primary) or filled into the in-app EOI PDF directly; both share the same data context.
- **Multi-berth EOI ranges.** Bundled berths render a compact range ("A1–A3, B5–B7") in the Berth Number field; the CRM shows the full set as chips. Catalogued merge tokens are enforced at template-creation time.
- **Configurable signing order.** Parallel or sequential per port, with a tri-state default (use template default / always parallel / always sequential).
- **Automation modes** per deal: manual, sequential auto (advances on each signature), or concurrent auto (everyone signs at once). Mode changes audit-logged.
- **Idempotent webhook handling.** Retries don't double-write; status changes normalised across both supported API versions; 5-minute polling safety net for missed webhooks.
- **Rejection reasons captured** when a signer declines.
- **Reminders and voids** surfaced directly from the deal detail.
- **Embedded signing card** for in-app signing where appropriate.
- **External EOI upload.** Record an EOI signed outside the system (PDF + counterparty list).
- **Webhook health card** in admin showing recent deliveries, failures, and a "test now" action.
- **Per-port signing configuration** — provider instance, API key, signing order, redirect URL.

---

## 8. Email send-outs

- **Per-port branded templates.** Every transactional email (invites, signing notifications, residential and berth enquiries, contract comms, digests, etc.) shares one branded shell that applies the port's branding automatically.
- **Configurable send-from accounts.** Per-port human send-from (e.g. `sales@portnimara.com`) and automation send-from (e.g. `noreply@portnimara.com`). SMTP/IMAP credentials encrypted at rest; APIs return only "is set" markers.
- **Compose dialog** with rich body (markdown rendered safely with a strict allow-list), multi-attachment, and live preview.
- **Smart attachment handling.** Files over a per-port size threshold ship as 24-hour signed-URL links instead of attaching.
- **Send rate limit** (50 sends/user/hour) to protect deliverability.
- **Email audit log.** Every send recorded with recipient list, body, attachments, and links; admin-browsable.
- **Inbound bounce monitoring.** A scheduled job (every 15 minutes) reads non-delivery reports and matches them to the original send.
- **Email threads** — replies to a CRM-originated email are threaded under the original.
- **Tracked-link composer.** Per-recipient tracked links for open and click-through attribution.
- **Per-port template overrides** from admin, without code changes.
- **Notification digests.** Hourly digest assembled from each user's unread notifications above a threshold.

---

## 9. Reports

- **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. All filters (stage, lead category, outcome) apply live.
- **Operational report** with an operational heatmap and signing-box plot for spotting signing/operations bottlenecks.
- **Custom report builder (MVP).** Pick an entity, choose columns, pick a date range, and run. Four entities live at launch; more entities and column-level controls roll out incrementally.
- **Save / load / save-as templates.** Any report configuration saved as a named template with an optional shareable link, re-runnable on demand.
- **Scheduled runs.** Weekly, monthly, or quarterly cadences; runs on schedule and optionally emails recipients a branded PDF. Run history browsable in admin.
- **PDF exports** server-side rendered with a branded cover page; CSV and Excel exports available client-side from every list.
- **Status badges** for each scheduled run.
- **Charts** combining standard bars/lines/pies with dedicated heatmap and funnel rendering.

---

## 10. Admin

- **Organised admin surface** grouping all settings into clear domains: Brand & Communication, Sales Workflow, Catalog, Identity & Access, Inbox & Data Quality, Integrations, and System & Observability.
- **Permissions UI.** Browse roles, edit role definitions, browse users, and assign per-user overrides via a visual permission matrix.
- **Settings registry.** A single, validated source of truth for every configurable setting, scoped per port.
- **System monitoring dashboard.** Service health, queue depth, and reconcile state in one place.
- **Port configuration** for adding new ports with their own branding, currency, timezone, and email background.
- **Self-service customisation.** Tags, vocabularies, custom fields, and supplemental info-request forms that tenants can shape themselves, without engineering involvement.
- **Onboarding checklist** to guide new ports through setup.

---

## 11. 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 for documents, partial-word for names and titles, fuzzy trigram matching ("Jhon" finds "John"), canonical phone-number matching that ignores formatting, and direct ID lookup.
- **Affinity ranking.** Recently-touched results are promoted.
- **Cross-port super-admin pass.** Super-admins see other-port matches in a separate, clearly-labelled section.
- **Permission-aware.** Viewers don't see results they couldn't open.
- **Mobile search overlay** designed for thumb reach.
- **Highlighted match terms** in each result.
- **Admin search across the seven IA domains** — every admin page reachable from the topbar by keyword.

---

## 12. Activity feed & notifications

- **Dashboard activity widget** showing 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, etc. Legacy events re-mapped to the current vocabulary.
- **My reminders rail** on the dashboard surfacing due and overdue follow-ups.
- **Reminders engine** with admin configuration (cadence, severity, recipients).
- **Alert engine.** Rule-based alerts evaluated every 5 minutes; admins define rules, the engine generates notifications when they fire.
- **In-app inbox** in the topbar.
- **Hourly notification digest email** when unread items pass a threshold.

---

## 13. Analytics

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

---

## 14. Mobile & responsive design

- **Dedicated mobile shell** on small viewports: mobile topbar, bottom tab bar, and a "more" sheet for overflow navigation.
- **Card mode toggle on every list** — switch between table and card view; card view defaults 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 built for mobile keyboards.

---

## 15. Security & compliance

- **Authentication via `better-auth`** with session cookies; branded login, reset-password, and set-password surfaces.
- **CRM invitations** via 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.**
- **Magic-byte PDF validation** on every upload path (in-server and presigned-PUT).
- **Timing-safe webhook verification** for document-signing callbacks.
- **Defense-in-depth port scoping** on every aggregated query — joins double-check `port_id`.
- **30-second timeouts on object-storage calls** so a slow host can't stall the application.
- **Per-port encryption-at-rest** for SMTP/IMAP credentials.
- **Pre-commit hooks block accidental secret commits** (`.env` files including `.env.example`).

---

## 16. Multi-tenancy at port level

- **Per-port URL slug** — 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 overridable per port from admin.
- **Per-port signing configuration** — provider API version, API key, signing order, redirect URL.
- **Per-port storage backend** — S3-compatible or filesystem, switchable via migration script.
- **Per-port currency and timezone** flowing through the scheduler, dashboard timezone-drift banner, recommender deposit defaults, and every report.
- **Per-port sales settings** — qualification criteria, pipeline rules, recommender weights, send-from accounts, and AI budgets, all scoped to the port.
- **Cross-port super-admin search** — super-admins see other-port matches in a clearly-labelled secondary section; otherwise queries scope to the current port.