# Port Nimara CRM — UI Page Map & Navigation Structure

**Compiled:** 2026-03-11
**Framework:** Next.js 15 App Router
**Component Library:** shadcn/ui + Tailwind CSS
**Routing:** File-based via `src/app/` directory

---

## Navigation Architecture

### Global Shell (persistent on all authenticated pages)

```
┌─────────────────────────────────────────────────────────────┐
│ [Logo/Port Name]  [Port Switcher ▾]     [⌘K Search] [🔔 3] [👤 Matt ▾] │
├──────────┬──────────────────────────────────────────────────┤
│ Sidebar  │                                                  │
│          │              Page Content                        │
│ Dashboard│                                                  │
│ Clients  │                                                  │
│ Interests│                                                  │
│ Berths   │                                                  │
│ Expenses │                                                  │
│ Invoices │                                                  │
│ Files    │                                                  │
│ Email    │                                                  │
│ Reminders│                                                  │
│ ──────── │                                                  │
│ Admin ▾  │                                                  │
│          │                                                  │
│ [Collapse│                                                  │
│  Toggle] │                                                  │
└──────────┴──────────────────────────────────────────────────┘
```

**Top bar components:**

- Port name + logo (from port settings branding)
- Port switcher dropdown (hidden entirely in single-port mode; visible only when 2+ active ports exist and user has access to multiple ports)
- Global search trigger (Cmd+K / Ctrl+K → modal)
- Notification bell with unread count badge → dropdown panel
- User avatar + name → dropdown: Profile, Dark Mode toggle, Scratchpad, Logout

**Sidebar:**

- Collapsible (persisted in user prefs via Zustand)
- Collapsed state shows icons only with tooltips
- Active page highlighted
- Admin section expandable submenu (only visible to users with any admin permission)
- Mobile: hamburger icon → slide-out drawer

---

## Route Map

### Auth Pages (unauthenticated — no shell)

| Route                  | Page           | Description                                                                                          |
| ---------------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
| `/login`               | Login          | Email + password form, "Forgot password?" link, CRM-styled (maritime branding, port logo)            |
| `/auth/set-password`   | Set Password   | Token-validated form: new password + confirm. Used for first-time login after admin creates account. |
| `/auth/reset-password` | Reset Password | Token-validated form: new password + confirm. Used from "forgot password" email link.                |

**Layout:** Centered card on full-screen branded background. No sidebar, no top bar.

---

### User Settings (accessible from user avatar menu)

| Route                     | Page                     | Description                                         |
| ------------------------- | ------------------------ | --------------------------------------------------- |
| `/settings/profile`       | My Profile               | Edit own name, avatar, timezone, preferred language |
| `/settings/notifications` | Notification Preferences | Per-notification-type delivery channel toggles      |

#### `/settings/notifications` — Notification Preferences

- **Table:** Notification type (rows) × delivery channel (columns: In-App, Email)
- **Notification types:** Reminder due, reminder overdue, new website registration, EOI signature event, new email received, duplicate client alert, invoice overdue, waiting list notification, system alert, follow-up auto-created, tenure expiring
- **Per-type toggles:** In-app (always on, read-only), Email (toggle on/off)
- **Save button** applies changes

---

### Dashboard

| Route | Page      | Description                        |
| ----- | --------- | ---------------------------------- |
| `/`   | Dashboard | Home screen — port-scoped overview |

**Page contents:**

- **Pipeline funnel widget** — interest count and weighted value per pipeline stage (bar or funnel chart). Click a stage → navigates to `/interests?stage={stage}`
- **Berth occupancy widget** — available / under offer / sold breakdown (donut chart). Click a status → navigates to `/berths?status={status}`
- **Revenue forecast widget** — weighted pipeline value with best/likely/worst scenarios, trend line over time
- **Expense summary widget** — month-over-month spend by category (bar chart)
- **Recent activity feed** — last 10 actions across all entities (from audit log). Each entry links to the relevant record.
- **Upcoming reminders & events** — unified list of next 5 CRM reminders + upcoming Google Calendar events (next 7 days). CRM reminders show linked entity; Calendar events show a Google Calendar badge. Link to `/reminders` for full view.
- **Overdue items panel** — unsigned EOIs, overdue invoices, overdue reminders, expiring tenures. Each item links to its record.
- **Timeline strip** — upcoming key dates: reminder due dates, tenure expirations, invoice due dates, Google Calendar events (horizontal scrollable timeline at top or bottom)

**Permission:** `reports.view_dashboard` (all roles by default)

---

### Client Management

| Route                | Page          | Description                                         |
| -------------------- | ------------- | --------------------------------------------------- |
| `/clients`           | Client List   | Paginated table of all clients                      |
| `/clients/new`       | Create Client | New client form                                     |
| `/clients/[id]`      | Client Detail | Full client record with tabbed sections             |
| `/clients/[id]/edit` | Edit Client   | Edit client fields (could also be inline on detail) |

#### `/clients` — Client List

- **Table columns:** Name, company, nationality, source, tags, # interests, last activity, created date
- **Filters:** Search (name/email/phone), nationality, source, tags, archived (toggle), date range
- **Sort:** Name, created date, last activity
- **Saved views:** Dropdown of saved filter configurations, "Save current view" button, "Manage Views" link → modal: rename, delete, share/unshare saved views
- **Bulk actions toolbar** (appears when rows selected): Bulk tag, bulk export (CSV/PDF), bulk archive
- **Actions per row:** View, Edit, Archive
- **"+ New Client" button** → `/clients/new`

#### `/clients/new` — Create Client

- **Sections:**
  - Basic info: Full name, company/entity (optional), nationality
  - Contact info: Add multiple contacts (channel + value + label), at least one required
  - Vessel details: Yacht name, length, width, draft (dual unit input), berth size desired
  - Proxy/representative: Toggle, proxy type, actual owner name, relationship notes
  - Communication preferences: Preferred method, language, timezone
  - Source: Website / manual / referral / broker (+ referrer link)
  - Tags: Tag selector (multi-select from existing tags or create new)
- **On submit:** Duplicate detection runs (same email → auto-merge, fuzzy match → alert modal)
- **Cancel** → back to `/clients`

#### `/clients/[id]` — Client Detail

- **Header area:** Client name, company, tags, status badges, quick actions (Edit, Archive, Export PDF, Merge)
- **Tabs:**

| Tab               | Contents                                                                                                                                                                                       |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Overview**      | Core fields (name, company, nationality, vessel, proxy info, communication prefs, source), contact cards                                                                                       |
| **Relationships** | Visual/list view of related clients. Relationship types: referred by, broker for, family member, same vessel, custom. Add/remove relationships. Shows referral networks and broker portfolios. |
| **Interests**     | List of all interests for this client. Single interest → inline expanded. Multiple → accordion or sub-table. Each links to `/interests/[id]`. "+ New Interest" button.                         |
| **Activity**      | Chronological timeline feed (from audit log). Filterable by event type.                                                                                                                        |
| **Notes**         | Timestamped notes thread. New note input with @mention support. Edit (within 15 min) / locked indicator.                                                                                       |
| **Files**         | Client-scoped file browser (MinIO). Upload button, folder tree, file cards with preview/download.                                                                                              |
| **Emails**        | Email threads linked to this client (from IMAP sync). Compose new button.                                                                                                                      |
| **Documents**     | EOIs, contracts, NDAs linked through interests. Status indicators (pending, signed, completed).                                                                                                |
| **Invoices**      | Invoices billed to this client. Status badges. Link to invoice detail.                                                                                                                         |
| **Audit Trail**   | Raw audit log entries for this client and all related entities. Filterable by action type, date range.                                                                                         |

---

### Interest Management

| Route             | Page            | Description                                       |
| ----------------- | --------------- | ------------------------------------------------- |
| `/interests`      | Interest List   | Table + pipeline (Kanban) views                   |
| `/interests/new`  | Create Interest | New interest form (often initiated from a client) |
| `/interests/[id]` | Interest Detail | Full interest record                              |

#### `/interests` — Interest List

- **View toggle:** Table view ↔ Pipeline (Kanban) view
- **Table view:**
  - Columns: Client name, berth (if linked), pipeline stage, lead category, EOI status, last activity, date created
  - Filters: Stage, berth, client, lead category, source, tags, date range, assigned salesperson
  - Sort: Date created, last activity, stage, client name
- **Pipeline (Kanban) view:**
  - 8 columns (one per pipeline stage): Open → Details Sent → In Communication → Visited → Signed EOI and NDA → 10% Deposit → Contract → Completed
  - Cards show: client name, berth, days in stage, next action indicator
  - Drag-and-drop between stages (confirmation dialog for significant changes)
  - Filters same as table view (applied to both views)
- **Saved views, bulk actions** same pattern as clients

#### `/interests/new` — Create Interest

- **Fields:**
  - Client selector (search/select existing or "+ New Client" inline)
  - Berth link (optional — search/select berth)
  - Initial pipeline stage (default: Open)
  - Lead category
  - Source
  - Notes (initial note)
  - Tags

#### `/interests/[id]` — Interest Detail

- **Header:** Client name → link to client, berth → link to berth (if linked), pipeline stage badge (with manual override dropdown), lead category, EOI status badge
- **Quick actions:** Generate EOI, Link Berth, Change Stage, Export PDF, Archive
- **Sections / Tabs:**

| Tab                 | Contents                                                                                                                                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Overview**        | Pipeline stage (with stage history), berth details (inline if linked), vessel info (from client), milestone dates (first contact, EOI sent, signed, deposit, contract, completed), lead category, source                 |
| **EOI & Documents** | EOI section: generate button (if prerequisites met), signing status per signer, signing URLs, reminder controls. Documents list: all docs on this interest (EOI, contracts, NDAs) with status. Upload manual doc button. |
| **Recommendations** | Berth recommendation panel: vessel dimensions summary, "Run Recommendation" button → ranked berth list with match scores. Assign berth from recommendation.                                                              |
| **Waiting List**    | If berth is linked and client is on waiting list: position, priority, notification pref. If berth has a waiting list: show queue.                                                                                        |
| **Notes**           | Interest-specific notes thread (separate from client notes). Same @mention / edit window behavior.                                                                                                                       |
| **Activity**        | Interest-specific timeline (subset of client timeline filtered to this interest).                                                                                                                                        |
| **Audit Trail**     | Audit log for this interest record.                                                                                                                                                                                      |

---

### Berth Management

| Route                  | Page                      | Description                                                       |
| ---------------------- | ------------------------- | ----------------------------------------------------------------- |
| `/berths`              | Berth Explorer            | Three-panel layout: map + list + detail                           |
| `/berths/new`          | Create Berth              | New berth form (admin/super admin)                                |
| `/berths/[id]`         | Berth Detail              | Full berth specs (also shown in right panel of explorer)          |
| `/berths/compare`      | Berth Comparison          | Side-by-side comparison of 2-3 berths                             |
| ~~`/berths/calendar`~~ | ~~Availability Calendar~~ | **CUT FROM V1** — Gantt-style tenure timeline deferred to post-V1 |

#### `/berths` — Berth Explorer (Three-Panel Layout)

```
┌──────────────────────────────────────────────────────┐
│  [Interactive Berth Map]              [Collapse Map ▲]│
│  SVG map color-coded: green=available, orange=under  │
│  offer, red=sold. Click berth → selects in list.     │
├─────────────────┬────────────────────────────────────┤
│  Smart List     │  Detail Panel                      │
│  ─────────────  │  ───────────────                   │
│  Grouped by     │  Full berth specs                  │
│  status:        │  (collapsible sections):           │
│  Under Offer    │  - Dimensions                      │
│  Available      │  - Infrastructure                  │
│  Sold           │  - Commercial                      │
│                 │  - Linked interests                │
│  Filter: area,  │  - Waiting list                    │
│  size, price    │  - Maintenance log                 │
│                 │  - Files / Gallery                 │
│  [+ New Berth]  │  - Tenure info                     │
│                 │  [Edit] [Compare] [Export PDF]      │
└─────────────────┴────────────────────────────────────┘
```

- **Map panel:** Toggleable (collapse to maximize list/detail). SVG with berth outlines colored by status. Hover shows tooltip (mooring #, area, status, size). Click selects berth.
- **List panel:** Grouped by status (Under Offer first, then Available, then Sold). Each item: mooring number, area, nominal size, price. Search/filter by area, size range, price range, status.
- **Detail panel:** Full spec sheet. Collapsible sections for each data group. Action buttons: Edit, Compare (adds to comparison), Export PDF, View on map.
  - **Waiting List section:** Ordered queue of clients with position, priority (normal/high), date added, notification preference. Actions: reorder, change priority, update notification pref, remove entry. "Add to waiting list" button (client selector).
  - **Maintenance Log section:** Chronological log of maintenance/repair/inspection entries. Each entry: date, description, cost, category (routine/repair/inspection/upgrade), photos (thumbnail gallery), responsible party. "+ Add Entry" form with photo upload. Edit/delete existing entries.

#### `/berths/compare` — Berth Comparison

- Select 2-3 berths (from berth list or via URL params)
- Side-by-side table: rows are spec fields, columns are berths
- Highlights differences
- Export as PDF button (branded with port logo/colors)

#### `/berths/calendar` — Availability Calendar — **CUT FROM V1**

> **Deferred to post-V1.** Tenure data and expiry checks remain active (see BR-003 tenure expiry, `tenure-expiry-check` background job). Only the Gantt-style visualization UI is deferred.

~~- Gantt-style horizontal timeline~~
~~- Rows = berths, bars = tenure periods~~
~~- Color: active tenure (blue), expiring soon (amber), expired (red), available (green)~~
~~- Configurable time range (3 months, 6 months, 1 year, 5 years)~~
~~- Click a tenure bar → links to interest or client detail~~
~~- Flags upcoming expirations (configurable warning threshold, set in port settings)~~
~~- Legend: color key for tenure status types~~
~~- Warning threshold control: dropdown to set how far in advance expirations are flagged (1/3/6/12 months)~~

---

### Expenses

| Route            | Page                  | Description                                                                                            |
| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------ |
| `/expenses`      | Expense List          | Paginated table of all expenses                                                                        |
| `/expenses/new`  | Create Expense        | New expense form with receipt upload                                                                   |
| `/expenses/[id]` | Expense Detail        | Full expense record with receipt images                                                                |
| `/scan`          | Receipt Scanner (PWA) | Standalone PWA — camera → AI extraction → save expense. Also accessible via `/expenses/scan` redirect. |

#### `/expenses` — Expense List

- **Table columns:** Date, establishment, amount (original currency + USD), category, payer, payment status, receipt indicator
- **Filters:** Date range, payer, category, payment status, currency, amount range
- **Sort:** Date, amount, establishment
- **Export controls:** CSV export, PDF export (with receipts), parent company export (EUR + 5% fee)
- **Bulk actions:** Bulk export, bulk payment status update, create invoice from selected

#### `/expenses/new` — Create Expense

- **Fields:** Establishment name, amount, currency (dropdown), date/time, category, payer, description, payment method, payment status
- **Receipt upload:** Drag-and-drop or camera capture, multiple images allowed
- **"Scan Receipt" button** → redirects to `/scan` (standalone PWA receipt scanner)

#### `/scan` — Receipt Scanner (Standalone PWA)

- **Standalone PWA:** `manifest.json` with `display: "standalone"`, custom icon ("Port Nimara Scanner"). Addable to Apple home screen / Android — opens without browser chrome.
- **Service worker:** Caches UI shell for instant load. Offline: photos queued in IndexedDB, uploaded on reconnect.
- **Easy URL:** `crm.portnimara.dev/scan` — short and bookmarkable. `/expenses/scan` redirects here.
- **Minimal UI:** No sidebar or navigation chrome. Camera viewfinder (or file upload for desktop) → Capture → AI processing spinner → Review extracted data (establishment, amount, currency, date, items) → Edit/correct → Save as expense → "Scan Another" or "Back to CRM"
- **Multi-currency indicator:** Shows detected currency + USD conversion at current rate
- **Auth:** Session-based. If not logged in, shows minimal login form then returns to scanner.

---

### Invoices

| Route            | Page           | Description                                          |
| ---------------- | -------------- | ---------------------------------------------------- |
| `/invoices`      | Invoice List   | Paginated table of all invoices                      |
| `/invoices/new`  | Create Invoice | Invoice builder (select expenses, configure billing) |
| `/invoices/[id]` | Invoice Detail | Full invoice with line items, payment tracking       |

#### `/invoices` — Invoice List

- **Table columns:** Invoice # (INV-YYYYMM-###), client/company, total, currency, status (draft/sent/paid/overdue/cancelled), due date, created date
- **Filters:** Status, client, date range, amount range, currency
- **Status badges color-coded:** Draft (gray), Sent (blue), Paid (green), Overdue (red), Cancelled (strikethrough)

#### `/invoices/new` — Create Invoice

- **Step 1:** Select billing target (client or company, billing email, billing address)
- **Step 2:** Add line items — inline editable table: description, quantity, unit price, amount (auto-calculated). "Add Row" button for manual items. "Import from Expenses" button → modal showing un-invoiced expenses with checkboxes, select → auto-creates line items.
- **Step 3:** Configure: payment terms (Immediate/Net 10/15/30/45/60), currency, discount (% or fixed), additional fees, notes
- **Preview:** Live invoice preview as you configure
- **Save as draft** or **Save & Send**

#### `/invoices/[id]` — Invoice Detail

- **Header:** Invoice #, status badge, client/company, total, due date
- **Line items table:** Description, quantity, unit price, amount
- **Totals section:** Subtotal, discount, fees, total
- **Payment tracking:** Status, payment date, method, reference, notes. "Record Payment" button.
- **Actions:** Send (email PDF), Download PDF, Edit (if draft), Mark as Paid, Cancel
- **Linked expenses:** List of expenses included in this invoice

---

### File Management

| Route    | Page         | Description                                    |
| -------- | ------------ | ---------------------------------------------- |
| `/files` | File Browser | MinIO-backed file explorer organized by client |

#### `/files` — File Browser

- **Left panel:** Folder tree (clients as top-level folders, sub-folders: eoi, contracts, images, receipts, correspondence, misc)
- **Right panel:** File grid/list for selected folder
- **File cards:** Thumbnail (images/PDFs), filename, size, uploaded date, uploaded by
- **Actions per file:** Preview (inline modal for images/PDFs), Download, Rename, Delete (confirmation), Move
- **Upload:** Drag-and-drop zone + click upload. Context-aware (if in a client's eoi folder, auto-categorizes)
- **Folder management:** Create folder, rename folder, delete folder (with contents warning)
- **Search:** Search files by name within current context

---

### Email System

| Route             | Page           | Description                                     |
| ----------------- | -------------- | ----------------------------------------------- |
| `/email`          | Email Inbox    | Connected email threads (if mailbox configured) |
| `/email/settings` | Email Settings | IMAP/SMTP configuration                         |

#### `/email` — Email Inbox

- **If no mailbox configured:** Prompt to set up in `/email/settings`. Show system-sent emails log instead.
- **If configured:**
  - Left panel: Thread list (newest first), search, filter by linked client
  - Right panel: Thread detail (conversation view, newest at bottom)
  - Compose button → TipTap rich text editor modal (recipients, subject, body, merge fields, attachments from MinIO)
  - Threads auto-linked to clients by email address matching
  - Unlinked threads shown in a separate "Unlinked" section

#### `/email/settings` — Email Settings

- Provider presets: Google Workspace, Outlook, Custom
- SMTP configuration: host, port, username, password (encrypted), TLS toggle
- IMAP configuration: host, port, username, password (encrypted), TLS toggle
- Test connection button
- Sync frequency setting

---

### Reminders

| Route        | Page                 | Description                                            |
| ------------ | -------------------- | ------------------------------------------------------ |
| `/reminders` | Reminders & Upcoming | Unified list of CRM reminders + Google Calendar events |

#### `/reminders` — Reminders & Upcoming

- **Unified list view:** CRM reminders and Google Calendar events interleaved chronologically
  - Toggle: My Reminders ↔ All Reminders (requires `reminders.view_all`)
  - CRM reminders: Title, linked entity (client/interest/berth), priority (color-coded), due date, assigned to, status badge
  - Google Calendar events: Title, time, location (if any), calendar badge icon to distinguish from CRM reminders
  - Filters: Source (CRM only / Calendar only / Both), status (pending/snoozed/completed/dismissed), priority, assignee, entity type, due date range, overdue toggle
  - Sort: Due date (default), priority, created date
- **Quick create:** "+ New Reminder" → inline form or modal (title, note, due date/time, priority, assignee, linked entity, "Add to Google Calendar" toggle)
- **Reminder detail:** Click reminder → slide-out panel with full fields, edit capability, snooze/complete/dismiss buttons
- **Snooze options:** 1 hour, 4 hours, tomorrow morning, next week, custom date/time
- **Calendar connection banner:** If Google Calendar not connected, show a subtle banner: "Connect Google Calendar to see your events alongside reminders" → link to `/settings/calendar`
- **Google Calendar event detail:** Click calendar event → read-only panel showing event details, link to open in Google Calendar

### User Settings — Calendar

| Route                | Page              | Description                                  |
| -------------------- | ----------------- | -------------------------------------------- |
| `/settings/calendar` | Calendar Settings | Google Calendar connection and configuration |

#### `/settings/calendar` — Calendar Settings

- **Connection status:** Connected / Not connected, with Google account email displayed
- **Connect button:** Initiates Google OAuth flow → redirects to Google consent screen → returns with token
- **Calendar selector:** Dropdown listing all user's Google Calendars (fetched via `calendarList.list`). User picks which calendar to sync with (e.g., "Business", "CRM", "Primary").
- **Sync toggle:** Enable/disable background sync
- **Last synced:** Timestamp of most recent sync
- **Manual sync:** "Sync now" button to trigger immediate pull
- **Disconnect:** Button to revoke connection and clear cached events

---

### Admin Panel

| Route                   | Page                   | Description                                   |
| ----------------------- | ---------------------- | --------------------------------------------- |
| `/admin`                | Admin Overview         | Admin landing with section links              |
| `/admin/users`          | User Management        | User list + create/edit                       |
| `/admin/users/new`      | Create User            | New user form                                 |
| `/admin/users/[id]`     | User Detail            | User profile, assigned ports/roles, activity  |
| `/admin/roles`          | Role Management        | Role list + builder                           |
| `/admin/roles/new`      | Create Role            | Role builder with permission toggles          |
| `/admin/roles/[id]`     | Edit Role              | Edit existing role permissions                |
| `/admin/ports`          | Port Management        | Port list + settings                          |
| `/admin/ports/new`      | Create Port            | New port setup (or onboarding wizard)         |
| `/admin/ports/[id]`     | Port Settings          | Per-port configuration                        |
| `/admin/audit`          | Audit Log              | System-wide audit log viewer                  |
| `/admin/settings`       | System Settings        | Global system configuration                   |
| `/admin/webhooks`       | Webhook Management     | Webhook CRUD + delivery logs                  |
| `/admin/webhooks/new`   | Create Webhook         | New webhook configuration                     |
| `/admin/webhooks/[id]`  | Webhook Detail         | Edit webhook + view delivery history          |
| `/admin/reports`        | Scheduled Reports      | Report schedule management                    |
| `/admin/reports/new`    | Create Report Schedule | Configure new scheduled report                |
| `/admin/custom-fields`  | Custom Fields          | Custom field definitions per entity type      |
| `/admin/templates`      | Document Templates     | Template CRUD with TipTap rich text editor    |
| `/admin/templates/new`  | Create Template        | New template with merge field insertion       |
| `/admin/templates/[id]` | Edit Template          | Edit existing template                        |
| `/admin/forms`          | Form Management        | Data collection form builder + submissions    |
| `/admin/forms/new`      | Create Form            | Build a pre-filled data collection form       |
| `/admin/forms/[id]`     | Form Detail            | Edit form + view submissions                  |
| `/admin/import`         | Data Import            | CSV/Excel import center + import history      |
| `/admin/monitoring`     | System Health          | Service health dashboard + BullMQ job monitor |
| `/admin/backup`         | Backup & Restore       | Database backup management                    |
| `/admin/tags`           | Tag Management         | Manage tags across entity types               |
| `/admin/onboarding`     | Port Onboarding Wizard | Step-by-step new port setup                   |

#### `/admin/users` — User Management

- **Table:** Name, email, status (active/inactive), last login, ports assigned, roles
- **Actions:** Create, edit, deactivate/reactivate, reset password
- **User detail page (`/admin/users/[id]`):**
  - Full profile: name, email, status, created date, last login
  - Port assignments: table of assigned ports with role per port, add/remove assignments
  - Active sessions: list of current sessions (device/browser, IP, last active). "Revoke" button per session, "Revoke All Sessions" button.
  - Activity history: last N actions from audit log filterable by date range

#### `/admin/roles` — Role Management

- **Role list:** Name, description, system role flag, # users assigned
- **Role builder:**
  - Permission grid: categories on the left (clients, interests, berths, etc.), permission flags as toggles
  - Visual grouping by domain
  - "Clone from" dropdown to start from an existing role
  - Preview: "What can this role do?" summary

#### `/admin/ports` — Port Management

- **Port list:** Name, slug, status (active/inactive), # users, # berths
- **Port settings:**
  - Basic: Name, slug, timezone, default currency
  - Branding: Logo upload, primary/secondary color pickers → stored in port settings
  - Operational: Follow-up reminder schedules, alert thresholds, EOI reminder settings
  - Role overrides: Per-port permission tweaks for global roles

#### `/admin/audit` — Audit Log

- **Filterable table:** Timestamp, user, action (create/update/delete/archive/restore/merge), entity type, entity ID, field changed, old value → new value
- **Filters:** User, entity type, action type, date range, entity ID
- **Export:** CSV
- **Revert button** (super admin only) on individual entries

#### `/admin/settings` — System Settings

- **Sections:**
  - **Berth Status Rules:** Table of trigger→mode→target status rules. Each row: Trigger description (read-only), Mode dropdown (auto/suggest/off), Target Status dropdown (available/under_offer/sold). "Reset to Defaults" button. Per-port if multi-port.
  - Email: Poste.io SMTP config, test send
  - Documenso: API URL, API key, test connection
  - MinIO: Endpoint, access key, secret key, bucket, test connection
  - Currency: Primary currency, exchange rate refresh interval, Frankfurter API status, current rates table (auto-updated + manual override per pair), "Refresh Now" button
  - Backup: Schedule (cron), retention days, last backup status
  - Security: Session timeout, login rate limits, password requirements
  - Expiration alerts: Default warning threshold for tenure expirations (months before)

#### `/admin/webhooks` — Webhook Management

- **Webhook list:** Name, target URL, events subscribed, enabled/disabled toggle, last delivery status
- **Create/edit:** Target URL, secret key (for HMAC signing), event selector (checkboxes), enable/disable
- **"Test Webhook" button:** Sends a test payload to the target URL, shows response status/body inline
- **Delivery log per webhook:** Timestamp, event type, response status, response time, payload preview, retry count

#### `/admin/reports` — Scheduled Reports

- **Report list:** Name, type, frequency, recipients, last sent, next send, enabled toggle
- **Create/edit:** Report type (dropdown), frequency (daily/weekly/monthly/cron), enable/disable
- **Recipient selector:** Multi-select from CRM users + free-text entry for external email addresses. Shows recipient list with remove buttons.

#### `/admin/custom-fields` — Custom Fields

- **Per entity type tabs:** Clients, Interests, Berths, Expenses
- **Field list:** Name, type (text/number/date/boolean/select), required flag, sort order
- **Create field:** Name, type, options (for select type), required, default value

#### `/admin/templates` — Document Templates

- **Template list:** Name, type (welcome letter, handover checklist, etc.), last modified, active toggle
- **Template editor:**
  - Rich text editor (**TipTap** — confirmed, with table + merge field extensions)
  - Merge field insertion toolbar: dropdown showing available fields organized by entity (client.full_name, berth.mooring_number, etc.), click to insert `{{token}}`
  - Preview with sample data
  - Save / activate / deactivate

#### `/admin/forms` — Form Management

- **Form list:** Name, linked entity type, status (active/inactive), submissions count, last submitted, created date
- **Create/edit form:**
  - Form name, description
  - Entity type: client data collection, interest data collection, general intake
  - Field selector: choose which CRM fields appear on the form, set which are pre-filled vs. editable
  - Branding preview: shows form as client will see it (port logo/colors)
  - Generate link: creates per-client secure token URL
- **Submissions view per form:** Table of submissions with date, client, status (pending review / applied / rejected). Click submission → diff view showing what data the client provided vs. current CRM data. "Apply" button to merge submitted data into CRM records.

#### `/admin/tags` — Tag Management

- **Entity type tabs:** Clients, Interests, Berths (each port has its own tag set)
- **Tag list per type:** Tag name, color swatch, usage count (how many records tagged)
- **Create tag:** Name input + color picker
- **Edit tag:** Rename, change color
- **Delete tag:** Confirmation with cascade warning ("This tag is used on X records. Removing it will untag all of them.")
- **Drag to reorder** (sort order for display in tag selectors)

#### `/admin/import` — Data Import

- **Import wizard:**
  - Step 1: Select entity type (clients, interests, berths, expenses)
  - Step 2: Upload CSV/Excel file
  - Step 3: Column mapping (source columns → CRM fields, auto-mapped where names match)
  - Step 4: Validation preview (valid rows, error rows, duplicate alerts)
  - Step 5: Import + progress bar
- **Import history:** Past imports with record counts, errors, date, user

#### `/admin/monitoring` — System Health

- **Service health cards:** PostgreSQL, Redis, MinIO, Documenso, Poste.io, Socket.io — each with green/yellow/red indicator, last check time, response time
- **BullMQ dashboard:** Queue cards (one per queue: email, documents, reminders, calendar-sync, backups, etc.) showing pending/active/completed/failed counts. Click queue → drill-down job list with: job ID, status, data preview, created/processed timestamps. Actions per job: retry, remove. Dead letter queue section with bulk retry/clear.
- **Alert configuration:** Per-category alert rules (service down, job failure, backup failure, disk space, unusual activity). Each rule: threshold (e.g., >5 failures), time window (e.g., in 10 minutes), notification targets (super admin email + in-app). Enable/disable per rule.
- **System info:** Disk usage, memory, uptime (non-sensitive info only)

#### `/admin/backup` — Backup & Restore

- **Backup list:** Date, size, type (scheduled/manual), status
- **Manual backup trigger button**
- **Download backup** button per entry
- **Restore:** Upload backup → preview (record counts) → confirm → restore (super admin only)
- **Retention settings:** Keep last N days

---

### Global Overlays & Modals

These UI elements appear on top of any page:

| Component                      | Trigger                                   | Description                                                                                                                                                                                  |
| ------------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Global Search Modal**        | Cmd+K / Ctrl+K or search icon             | Full-screen modal: search input, results grouped by entity type (clients, berths, interests, invoices, expenses, documents), recent searches. Enter or click → navigates to record.          |
| **Notification Panel**         | Bell icon click                           | Slide-out right panel or dropdown: notification list ordered by recency. Each: icon, title, description, timestamp, read/unread dot, click → navigates to record. "Mark all as read" button. |
| **Scratchpad**                 | User menu → Scratchpad                    | Slide-out panel: personal notes area. Persisted per user. Notes can be dragged to a client record (opens a "move to client" modal).                                                          |
| **Confirmation Dialog**        | Any destructive action                    | Modal: "Are you sure?" with context (what's being deleted/archived). Confirm / Cancel.                                                                                                       |
| **Quick Note Modal**           | "Add Note" button on any entity           | Modal: text area with @mention support, entity context pre-filled. Save → adds to entity's notes.                                                                                            |
| **Duplicate Alert Modal**      | On client creation (fuzzy match detected) | Modal: shows potential duplicate(s) side-by-side. Options: "Merge with existing", "Create anyway", "Cancel".                                                                                 |
| **Merge Preview Modal**        | From client detail → Merge action         | Modal: two records side-by-side, field-by-field selection of which values to keep, preview of merged result. Confirm → merge.                                                                |
| **EOI Generation Wizard**      | "Generate EOI" button on interest         | Multi-step modal: Step 1 verify client data → Step 2 verify berth data → Step 3 select signers → Step 4 confirm → generate.                                                                  |
| **Berth Recommendation Panel** | "Run Recommendation" on interest          | Panel/modal: shows vessel dimensions, ranked berth results with match scores and reasons. "Assign" button per result.                                                                        |
| **Bulk Operation Progress**    | After triggering bulk action              | Toast/modal: progress bar, record count, success/error count. Stays until dismissed or auto-closes on completion.                                                                            |

---

### Client Portal (Separate Auth Context)

| Route                         | Page                 | Description                                    |
| ----------------------------- | -------------------- | ---------------------------------------------- |
| `/portal/login`               | Portal Login         | Client authentication (separate from CRM auth) |
| `/portal`                     | Portal Dashboard     | Client's berths, pending documents, invoices   |
| `/portal/documents`           | My Documents         | Documents awaiting signature, signed documents |
| `/portal/documents/[id]/sign` | Sign Document        | Embedded Documenso signing view                |
| `/portal/invoices`            | My Invoices          | Invoice history with status                    |
| `/portal/files`               | My Files             | Files shared by salesperson, upload area       |
| `/portal/forms/[token]`       | Data Collection Form | Pre-filled form for client to complete         |

**Layout:** Simplified layout — no sidebar, just a top bar with portal logo and client name. Clean, focused UI for non-CRM users.

---

### Public Pages (No Authentication)

| Route                      | Page              | Description                                               |
| -------------------------- | ----------------- | --------------------------------------------------------- |
| `/api/public/berths`       | —                 | JSON API endpoint (no UI)                                 |
| `/api/public/berths/:id`   | —                 | JSON API endpoint (no UI)                                 |
| `/api/public/interests`    | —                 | JSON API endpoint (POST, no UI)                           |
| `/api/public/forms/:token` | Public Form       | Pre-filled data collection form (branded, minimal layout) |
| `/api-docs`                | API Documentation | OpenAPI/Swagger UI for the public API                     |

---

## Page Count Summary

| Section                | Page Count                            |
| ---------------------- | ------------------------------------- |
| Auth pages             | 3                                     |
| User settings          | 2                                     |
| Dashboard              | 1                                     |
| Client management      | 4                                     |
| Interest management    | 3                                     |
| Berth management       | 5                                     |
| Expenses               | 4                                     |
| Invoices               | 3                                     |
| File management        | 1                                     |
| Email                  | 2                                     |
| Reminders              | 1                                     |
| Calendar Settings      | 1                                     |
| Admin panel            | 27 (includes forms, tags detail)      |
| Global overlays/modals | 10 components                         |
| Client portal          | 7                                     |
| Public pages           | 2 (with UI)                           |
| **TOTAL**              | **~66 pages + 10 overlay components** |

---

## Responsive Breakpoints

| Breakpoint              | Layout Adaptation                                                                                                                                                             |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Desktop (≥1280px)**   | Full three-panel layouts (berths), sidebar expanded, all columns visible                                                                                                      |
| **Tablet (768–1279px)** | Sidebar collapsed to icons, detail panels become full-page navigation, berth map toggles to separate tab, table columns reduced                                               |
| **Mobile (< 768px)**    | Sidebar → hamburger slide-out drawer, all views single-column, receipt scanner optimized for camera, touch-friendly tap targets (min 44px), swipe gestures for pipeline cards |

---

## Navigation Flow Diagram

```
Login ──→ Dashboard
               │
     ┌─────────┼──────────┬──────────┬──────────┬──────────┐
     ▼         ▼          ▼          ▼          ▼          ▼
  Clients   Interests   Berths   Expenses   Invoices    Reminders
     │         │          │          │          │          │
     ▼         ▼          ▼          ▼          ▼          ▼
  Detail    Detail     Explorer   Detail    Detail    Upcoming List
     │         │          │          │
     │     ┌───┘          │          │
     │     ▼              │          │
     │  EOI/Signing       │          │
     │  Recommendations   │          │
     │                    ▼          │
     │              Compare/Calendar │
     │                               │
     └──── Files ◄─── linked ───────┘
              │
              ▼
           Email
              │
     ┌────────┘
     ▼
  Admin Panel ──→ Users / Roles / Ports / Audit / Settings
                  Webhooks / Reports / Custom Fields / Templates
                  Import / Monitoring / Backup / Tags / Onboarding
```

**Cross-linking patterns:**

- Client detail → links to interests, files, emails, invoices, documents
- Interest detail → links to client, berth, EOI documents, recommendations
- Berth detail → links to interests, waiting list entries (which link to clients)
- Expense detail → links to invoice (if invoiced), receipt files
- Invoice detail → links to client, linked expenses
- Activity timelines → every entry links to the relevant record
- Notification items → each links to the triggering record
- Dashboard widgets → each links to the relevant list/filter view

---

## State Management Summary

| State Type                                     | Technology                                     | Scope                                         |
| ---------------------------------------------- | ---------------------------------------------- | --------------------------------------------- |
| **Server state** (entities, lists)             | TanStack Query                                 | Cache + refetch on focus/stale                |
| **UI state** (sidebar, modals, view prefs)     | Zustand store                                  | Per-session, persisted subset to localStorage |
| **Form state**                                 | React Hook Form + Zod                          | Per-form, validated on submit                 |
| **Real-time updates**                          | Socket.io events → TanStack Query invalidation | Port-scoped rooms                             |
| **URL state** (filters, pagination, view mode) | URL search params (nuqs or manual)             | Shareable/bookmarkable                        |

**Real-time update flow:**

1. User A creates a client → API saves → Socket.io emits `client:created` to port room
2. User B's browser receives event → TanStack Query cache invalidated for client list
3. User B's client list auto-refetches → new client appears without page refresh
4. If User B is on the dashboard → activity feed also refreshes

---

## Appendix: Route-to-Feature Spec Cross-Reference

| Feature Spec Section          | Primary Routes                                                                                 |
| ----------------------------- | ---------------------------------------------------------------------------------------------- |
| 1. Client Management          | `/clients`, `/clients/new`, `/clients/[id]`                                                    |
| 2. Interest Management        | `/interests`, `/interests/new`, `/interests/[id]`                                              |
| 3. Berth Management           | `/berths`, `/berths/compare` (~~`/berths/calendar`~~ cut from V1)                              |
| 4.1–4.5 EOI & Signing         | `/interests/[id]` (EOI tab), EOI Generation modal                                              |
| 4.5 Data Collection Forms     | `/admin/forms`, `/admin/forms/new`, `/admin/forms/[id]`, `/api/public/forms/:token`            |
| 4.6 Document Templates        | `/admin/templates`, `/admin/templates/new`, `/admin/templates/[id]`                            |
| 4.7 Record PDF Export         | Export buttons on `/clients/[id]`, `/berths/[id]`, `/interests/[id]`                           |
| 5. Expenses & Invoicing       | `/expenses`, `/expenses/new`, `/expenses/scan`, `/invoices`, `/invoices/new`, `/invoices/[id]` |
| 6. File Management            | `/files`, file tabs on client detail                                                           |
| 7. Email System               | `/email`, `/email/settings`                                                                    |
| 8. Dashboard & Analytics      | `/`                                                                                            |
| 9. Reminders & Calendar       | `/reminders`, `/settings/calendar`                                                             |
| 10. Notification Center       | Notification bell overlay                                                                      |
| 11.1 Global Search            | Cmd+K overlay                                                                                  |
| 11.2 Saved Filters            | Filter controls on all list pages                                                              |
| 11.3 Bulk Operations          | Bulk action toolbar on all list pages                                                          |
| 12. Admin Panel               | `/admin/*` (all sub-routes)                                                                    |
| 13. Audit System              | `/admin/audit`, audit trail tabs on entity detail pages                                        |
| 14. Multi-Port Tenancy        | Port switcher in top bar                                                                       |
| 15. Auth & Authorization      | `/login`, `/auth/*`, middleware (invisible)                                                    |
| 16. Public API                | `/api/public/*`, `/api-docs`                                                                   |
| 17.1 Berth Spec Import        | `/admin/import` (berth-specific flow)                                                          |
| 17.2 Receipt Scanner (PWA)    | `/scan` (standalone PWA, also `/expenses/scan` redirect)                                       |
| 17.3 Recommendation Engine    | `/interests/[id]` (Recommendations tab)                                                        |
| 17.4 S3 File Migration        | One-time admin script (no permanent UI — progress in `/admin/monitoring`)                      |
| 18. Data Import/Export        | `/admin/import`, export buttons on all list pages                                              |
| 19. Webhooks                  | `/admin/webhooks`, `/admin/webhooks/new`, `/admin/webhooks/[id]`                               |
| 20. Scheduled Reports         | `/admin/reports`, `/admin/reports/new`                                                         |
| 21. System Monitoring         | `/admin/monitoring`, `/admin/backup`                                                           |
| 22. Client Portal             | `/portal/*`                                                                                    |
| 23.1 Mobile Responsive        | Responsive breakpoints (all pages)                                                             |
| 23.2 Dark Mode                | User menu toggle (all pages)                                                                   |
| 23.3 Quick Notes              | Scratchpad overlay                                                                             |
| 10.2 Notification Preferences | `/settings/notifications`                                                                      |
| 23.4 Tags                     | `/admin/tags`, tag components on entity forms/detail                                           |
| 23.5 Archiving                | Archive actions on all entity detail/list pages                                                |
| 23.6 Multi-Currency           | Currency display on berth detail, expense forms                                                |
| 23.7 Audit Export             | Export button in `/admin/audit` or dedicated modal                                             |
