# Website Analytics — flesh-out plan **Goal:** rebuild `/{portSlug}/website-analytics` so it feels like a polished native CRM panel that _mirrors_ Umami's idiom rather than reading as a stripped-down embed. Keep a "View in Umami →" deep-link in the header for power users; render most data in-app via the API. Also extend usage into adjacent CRM surfaces (dashboard tiles, inquiry detail, email open-tracking) so Umami stops being "the analytics page" and becomes a cross-cutting data layer. **Inputs to this plan:** 1. Live API capabilities reference — `docs/umami-api-capabilities.md` (verified empirically against v3.1.0 on analytics.portnimara.com). 2. Live UI tour via Playwright — screenshots `umami-tour-1-overview.png` through `umami-tour-9-compare.png` (10 surfaces captured). 3. Pixel-tracking probe — confirmed the `/p/` and `/q/` endpoints + their UI creation forms. --- ## 1. What Umami's UI actually does — design patterns to mirror Tour findings (from 17 sub-pages + 4 team pages): | Surface | Visual idiom | Adopt for CRM? | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | **Overview** | 5-tile KPI row (Visitors / Visits / Views / Bounce rate / Visit duration) — each tile shows headline number + colored arrow chip (green ↑ 58% / red ↓ 39%) + percentage delta. Single stacked bar chart below for traffic time-series (visitors stacked over visits, dual-shade blue). Filter pill + date-range nav top-right. | **Yes** — already mostly there, missing the bounce-rate + visit-duration tiles. | | **Events** | List of custom event names with per-event count + time-series spark. | **Yes** — needs marketing-site event firing first (Phase 4). | | **Sessions** | Dense table: avatar + per-session row showing Visits / Views / Events / Location (flag + city, country) / Browser icon / OS icon / Device icon / Last seen. Tabs for Activity vs Properties (custom session props). | **Yes** — high-leverage; lets reps see _who_ is browsing right now. | | **Realtime** | 4 stat tiles (Views/Visitors/Events/Countries) + auto-refreshing line chart of last 30 min. | **Yes** — already partial via the glance tile. | | **Performance** | Likely page-speed / Core Web Vitals. | Skip — not relevant to marina sales. | | **Compare** | Pick two date ranges side-by-side. | **Partial** — single `compare=prev` overlay on the existing trend chart suffices. | | **Breakdown** | Pivot table view across dimensions. | Skip in v1; expose via Reports later. | | **Goals** | Define event/page-view goals, see completion rate over time. | **Yes** — defer to Phase 5. | | **Funnels** | Multi-step conversion funnel (e.g. /berths → /berths/A12 → /inquire → submit). | **Yes** — Phase 5; high-value for inquiry conversion. | | **Journeys** | Most common navigation paths (Sankey-like). | **Maybe** — defer; nice-to-have. | | **Retention** | Cohort retention grid. | Skip — wrong fit for one-and-done marina inquiry traffic. | | **Replays** | Session replay (likely paid). | Skip — unavailable on our tier. | | **Segments / Cohorts** | Saved filters / user groups. | Skip in v1. | | **UTM** | Campaign attribution by UTM params. | **Yes** — Phase 5 for paid-campaign tracking. | | **Revenue** | Revenue attribution. | Skip — would require firing `purchase` events from CRM after EOI close (consider Phase 6 if leadership wants funnel→revenue). | | **Attribution** | First/last-click attribution model. | **Maybe** — defer. | | **Team-Boards / Websites / Links / Pixels** | Account admin surfaces. | **Pixels + Links: YES — see Phase 4.** Boards/Websites stay in Umami. | ### Visual specifics worth copying - **KPI tile design**: large bold number, label above in muted-grey, arrow + percentage delta below in a colored chip (green-bg for positive, red-bg for negative, fixed-width for alignment). Our `KPITile` already does the right shape — we just need to add the missing two metrics. - **Stacked bar chart for traffic**: dual-shade single bar (visitors as light-blue base, views stacked dark-blue on top). Reads cleaner than two overlapping lines. - **Location rendering**: flag emoji + "City, Country" inline. Use `getCountryName()` + a flag library (twemoji or unicode regional indicators). - **Browser/OS/Device icons**: small colored brand glyphs inline. Use `simple-icons` or `lucide` equivalents. - **Filter chip + date nav**: `<` `>` arrows step through the date range; dropdown opens to preset list. Adopt the same pattern on our shell — currently we only have presets, no step-arrows. --- ## 2. Phased build plan ### Phase 1 — Fill out the Overview tiles & chart (~3-4h) Quick wins that close visual parity with Umami's Overview: | Task | File | Effort | | -------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | Add **Bounce rate** KPI tile | `website-analytics-shell.tsx` | derive `bounces / visits * 100`; service field already there | | Add **Avg visit duration** KPI tile | `website-analytics-shell.tsx` | derive `totaltime / visits` formatted as `Xm Ys`; service field already there | | Add **`<` `>` date-step arrows** on the date-range chip | `date-range-picker.tsx` | step the current preset by one window (today→yesterday, 7d→prior-7d, etc.) | | Convert pageviews trend to **stacked bar** (visitors vs views) | `pageviews-chart.tsx` | recharts `BarChart` stacked, light/dark blue | | Add **`compare=prev` overlay toggle** on the trend chart | `pageviews-chart.tsx` + service `getPageviewsSeries` | optional "vs prior period" series rendered as dashed line | | Add **Top browsers / OS / devices** ranked-list cards | new `` consumers; service already exposes via `getMetric(type)` | mirror Top Pages/Referrers/Countries layout | | **World choropleth heatmap** card (already queued separately) | new `visitor-world-map.tsx` (Natural Earth topojson + react-simple-maps) | ~4-6h on its own | **Cumulative result:** Overview surface reads at ~80% parity with Umami's Overview. --- ### Phase 2 — Sessions surface (~4-5h) New `/website-analytics/sessions` tab + supporting service wrappers: | Task | File | Effort | | ------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------- | | Service: `getSessions(portId, range, opts)` → `/api/websites/:id/sessions` (paged) | `umami.service.ts` | ~30 min | | Service: `getSession(portId, sessionId)` → single-session detail | `umami.service.ts` | ~15 min | | Service: `getSessionActivity(portId, sessionId, range)` → event timeline | `umami.service.ts` | ~15 min | | Service: `getSessionsWeekly(portId, range)` → hour-of-week heatmap | `umami.service.ts` | ~15 min | | API route: `/api/v1/website-analytics?metric=sessions[&sessionId=...]` | route.ts | ~30 min | | UI: `sessions-table.tsx` — dense rows mirroring Umami (avatar + location flag + browser/OS/device icons + Last seen) | new component | ~2h | | UI: `session-detail-sheet.tsx` — right-side Sheet drawer showing the session's full event timeline when a row is clicked | new component | ~1h | | UI: `weekly-heatmap-card.tsx` — 7×24 grid colour-scaled by session count, hover for tooltip | new component | ~1h | **Unlock:** rep can see "who is currently browsing right now, where from, on what device, what they're looking at" — directly actionable for sales follow-up. --- ### Phase 3 — Events surface (~3-4h, BLOCKED on Phase 4a) | Task | File | Effort | | -------------------------------------------------------------------------------------------- | ------------------ | ------- | | Service: `getEvents(portId, range, opts)` → `/events` paged list | `umami.service.ts` | ~30 min | | Service: `getEventsStats(portId, range)` → totals | `umami.service.ts` | ~15 min | | Service: `getEventsSeries(portId, range, eventName, unit)` → per-event time-series | `umami.service.ts` | ~15 min | | API route addition | route.ts | ~30 min | | UI: `events-tab.tsx` — list of event names with per-event count + spark + drill-in | new component | ~1.5h | | UI: `event-detail-sheet.tsx` — single event's time-series chart + filter by payload property | new component | ~1h | **Dependency:** the marketing site must fire `umami.track(name, payload)` calls (Phase 4a). Without this, Events tab is empty. --- ### Phase 4 — Pixel tracking + link tracking + marketing-site event push **Phase 4a — Marketing-site event tracking (~2-3h on marketing repo)** Add `umami.track()` calls in the marketing site: - `inquiry-submitted` with `{berth, source}` payload — fires on EOI form submit - `brochure-download` with `{brochureId}` — fires on brochure download - `berth-detail-viewed` with `{berthId, mooring}` — fires on `/berths/[mooring]` page view - `phone-revealed` / `email-revealed` — fires when contact details are exposed These light up the Events tab + enable funnel analysis in Phase 5. **Phase 4b — Pixel-based email open tracking (~3-4h CRM-side)** Probe finding: Umami exposes pixel URLs at `https://analytics.portnimara.com/p/` — fetching the URL records an event. Use case: embed in HTML emails as a 1x1 image. **Two architecture options:** **Option A — One Umami pixel per email type** (simple, low fidelity) - Create a pixel manually in Umami for each templated email type (`portal-invite`, `eoi-sent`, `reservation-reminder`, etc.) - Embed the static pixel URL in each template - Pro: zero CRM-side code beyond template HTML. Open rates roll up in Umami by pixel. - Con: can't tell _which recipient_ opened — only aggregate counts per template. **Option B — One Umami pixel + CRM-side per-send tracking endpoint** (richer, recommended) - Build `GET /api/public/email-pixel/:sendId.gif` in our CRM that: 1. Returns a 1×1 transparent GIF 2. Records the open in `document_sends.opened_at` (already a table; per CLAUDE.md "send-from accounts" section) 3. Optionally proxies the hit to Umami via `POST /api/send` with the email type + send id as event properties for cross-correlation - Embed `` in every templated email - Pro: per-recipient open tracking + open-time + CRM-attached. Funnels by email type via Umami too. - Con: needs the public endpoint + a schema column (or reuse `document_sends.opened_at`). **Recommendation: ship Option B.** The CRM-side hook gives us per-deal attribution ("client X opened the EOI reminder twice but hasn't signed"), and Umami still gets the aggregate. | Task | File | Effort | | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------- | | New endpoint `/api/public/email-pixel/[sendId]/route.ts` returning a 1×1 GIF + recording open | new route | ~1h | | Migration: add `opened_at`, `open_count`, `last_opened_user_agent` to `document_sends` if not present | drizzle migration | ~30 min | | Email template helper: inject the pixel HTML into every transactional template | `src/lib/email/render.ts` | ~30 min | | UI surface: on each `document_sends` row in the activity feed, show "Opened N times, last at X" badge | `email-activity-row.tsx` | ~1h | | Cross-post to Umami via `trackEvent('email-opened', {emailType, sendId})` so Umami funnel data includes opens | new `trackEvent` wrapper in `umami.service.ts` | ~30 min | | Privacy: respect `EMAIL_REDIRECT_TO` dev gate; don't fire pixels for redirected dev emails | ditto | ~15 min | **Phase 4c — Tracked redirect links (~1.5h)** Umami's `/q/` endpoint is a tracked redirect — records a click then 302s to the destination URL. Use for outbound CTAs: - "View brochure" links in emails → wrap via Umami link → records click → opens brochure - "Schedule a viewing" buttons → wrap via Umami link → click attribution - Marketing-site CTAs → wrap → measure engagement | Task | File | Effort | | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------- | | Service: `createTrackedLink(name, destinationUrl)` → POST to Umami's links endpoint via authenticated API | `umami.service.ts` | ~45 min | | Email template helper: `` JSX wrapper that auto-creates the Umami link on first render + caches the slug | `src/lib/email/components/` | ~45 min | --- ### Phase 5 — Reports surfaces (Funnels, UTM, Journeys) (~6-8h) | Task | File | Effort | | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------ | | Service: `getReport(reportType, body)` POST wrapper covering `/funnel`, `/journey`, `/utm`, `/goals`, `/retention`, `/revenue`, `/attribution` | `umami.service.ts` | ~1h | | UI: `/website-analytics/funnels` page — admin-configurable funnel definitions (steps as event names or URL paths), per-step drop-off chart | new page | ~3h | | UI: `/website-analytics/utm` page — UTM source/medium/campaign breakdown with click-through to attributed sessions | new page | ~2h | | UI: `/website-analytics/journeys` page — top navigation paths rendered as ranked list (skip Sankey for v1) | new page | ~1.5h | | Defer: Goals / Retention / Revenue / Attribution to v2 (low signal for marina sales) | | | **High-leverage funnels to wire as defaults:** - **Inquiry funnel**: `/` → `/berths` → `/berths/[mooring]` → `inquiry-submitted` event → CRM `eoi-signed` (cross-system!) → CRM `reservation-paid` (cross-system!) - **Email funnel**: `email-sent` → `email-opened` (pixel) → tracked-link click → CRM action The cross-system funnels require Phase 4 to be live first. --- ### Phase 6 — CRM → Umami event push for outcome attribution (~2-3h) Close the funnel from "marketing site click" → "CRM closed deal" by firing CRM-side events back into Umami via `POST /api/send`: | Event | Fired by | Payload | | ---------------------- | -------------------------------------------- | --------------------------------------- | | `crm-inquiry-created` | `createInterest()` in `interests.service.ts` | `{interestId, source, leadCategory}` | | `crm-eoi-sent` | `generateAndSign()` after EOI dispatch | `{interestId, berth, pathway}` | | `crm-eoi-signed` | Documenso `DOCUMENT_COMPLETED` webhook | `{interestId, berth}` | | `crm-reservation-paid` | manual stage advance to `deposit_paid` | `{interestId, berth, amount, currency}` | | `crm-contract-signed` | manual stage advance to `contract` | `{interestId, berth, amount, currency}` | | Task | File | Effort | | ----------------------------------------------------------------------------------------- | ------------------- | -------- | | Service: `trackEvent(name, payload, sessionId?)` → `POST /api/send` on the Umami instance | `umami.service.ts` | ~45 min | | Hook into the 5 service entry points above (one event per outcome milestone) | each service file | ~1.5h | | Audit log entry per event sent so we can verify Umami received it | `audit_logs` insert | included | **Unlock:** Umami's Revenue + Attribution reports start showing CRM outcomes attributed to marketing-site channels — closes the leadership question "which traffic sources actually generate signed deals, not just leads?" --- ### Phase 7 — Cross-cutting CRM placements (~3-4h) Beyond the dedicated `/website-analytics` page, surface Umami data inside CRM context: | Placement | What | Effort | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------ | | **Dashboard rail tile** (already shipped) — Pageviews + active now | already done in this session | — | | **Inquiry detail page** — "Source attribution" card showing the inquiry's UTM params, landing page, time-on-site, pages-viewed-before-submit. Pulls from `getSession(sessionId)` if the inquiry's create payload includes a session ID (requires marketing-site change to pass it). | new `inquiry-attribution-card.tsx` | ~1.5h + marketing-site change | | **Client detail page** — "Website activity" card: total sessions, pageviews, last-seen, top pages visited. Requires `umami.identify({email})` on marketing site to link sessions back to clients. | new `client-web-activity-card.tsx` | ~1.5h + marketing-site identify call | | **Berth detail page** — "Marketing demand" card: pageviews to `/berths/{mooring}` over time + referrer breakdown. Drives "this berth is being viewed but not inquired-about — flag for outreach." | new `berth-demand-card.tsx` | ~1h | | **Document send activity** — pixel opens per recipient (from Phase 4b) | inline on existing `document_sends` rows | included in 4b | --- ## 2b. Library adoptions (changes the plan materially) Context7 lookup surfaced three official libraries that reshape the plan. **Adopt all three.** ### `@umami/api-client` — official read-side client Covers every read endpoint we need including all the report types. Built-in filter support, login/JWT auth handled internally, `{ok, data}` discriminated union for clean error handling. **Replaces:** ~60-70% of our current `umami.service.ts` (drop `umamiFetch`, JWT cache, decrypt boilerplate; keep thin wrappers with existing signatures so consumers don't change). **One-time refactor (~2h):** ```ts const clientByPort = new Map(); async function getClient(portId: string): Promise { if (clientByPort.has(portId)) return clientByPort.get(portId)!; const cfg = await loadUmamiConfig(portId); if (!cfg) return null; const client = new UmamiApiClient({ apiEndpoint: `${cfg.apiUrl}/api`, apiKey: cfg.apiToken ?? undefined, }); if (!cfg.apiToken && cfg.username && cfg.password) await client.login(cfg.username, cfg.password); clientByPort.set(portId, client); return client; } export async function getStats(portId: string, range: DateRange) { const client = await getClient(portId); if (!client) return null; const { from, to } = rangeToBounds(range); const result = await client.getWebsiteStats(WEBSITE_ID, { startAt: from.getTime(), endAt: to.getTime(), }); return result.ok ? result.data : null; } ``` Same pattern for `getPageviewsSeries`, `getMetric`, `getActiveVisitors`, plus new ones from the SDK: `getRealtime`, `getWebsiteSessionStats`, `runFunnelReport`, `runJourneyReport`, etc. ### `@umami/node` — official write-side SDK For Phase 6 (CRM → Umami push) and Phase 4b cross-post: ```ts const umami = new Umami({ websiteId, hostUrl }); await umami.track({ url: '/crm/eoi-signed', name: 'crm-eoi-signed', data: { interestId, berth, dealValue }, }); await umami.identify({ sessionId, email, interestId }); ``` **Replaces:** the planned hand-rolled `trackEvent()` wrapper. Single line per outcome milestone. ### `react-simple-maps` — for the world heatmap (Phase 1b) Declarative SVG choropleth on d3-geo + topojson-client. SSR-safe. Use `topojson/world-atlas` (110m resolution ~30KB) cached in `public/`. Bundle ~30-50KB + topojson 30-100KB. ```jsx {({ geographies }) => geographies.map((geo) => ( onCountryClick(geo.properties.iso_a2)} /> )) } ``` **Chose this over visx/Nivo/Chart.js Geo:** visx is overkill for one map; Nivo + Chart.js force a different charting idiom (we use recharts everywhere); react-simple-maps' compose-primitives shape matches our recharts pattern. ### Net effect on phase efforts | Phase | Original estimate | Revised after library adoption | | ---------------------------------------- | ----------------- | --------------------------------------------------------------- | | Service refactor (one-time) | — | **+2h** (one-time foundation; pays back across all phases) | | Phase 1 — Overview parity | 3-4h | 3-4h (unchanged; api-client makes the filter additions trivial) | | Phase 1b — World heatmap | 4-6h | 3-4h (library choice locked in) | | Phase 2 — Sessions | 4-5h | 3-4h (api-client has session methods built-in) | | Phase 3 — Events | 3-4h | 2-3h (api-client provides) | | Phase 4b — Pixel hybrid | 3-4h | 2.5-3h (cross-post is one line) | | Phase 5 — Reports (funnels/UTM/journeys) | 6-8h | 3-4h (every report method pre-wrapped) | | Phase 6 — CRM → Umami push | 2-3h | 1.5h (`@umami/node` handles transport) | **Total scope drops from ~30-40h to ~22-28h** with these adoptions. --- ## 3. Service-layer additions consolidated Add to `src/lib/services/umami.service.ts` (each is a thin wrapper around existing `umamiFetch` / new `umamiPost`): ```ts // Sessions (Phase 2) getSessions(portId, range, { page?, pageSize?, query? }) → /sessions getSession(portId, sessionId) → /sessions/:id getSessionActivity(portId, sessionId, range) → /sessions/:id/activity getSessionProperties(portId, sessionId) → /sessions/:id/properties getSessionsWeekly(portId, range, timezone) → /sessions/weekly // Events (Phase 3) getEvents(portId, range, opts) → /events getEventsStats(portId, range) → /events/stats getEventsSeries(portId, range, eventName, unit) → /events/series getEventDataProperties(portId, range) → /event-data/properties // Realtime (Phase 1) getRealtime(portId, range) → /api/realtime/:id (richer than /active) // Reports (Phase 5) getReport(portId, reportType, body) → POST /api/reports/:type (funnel/journey/utm/goals/retention/revenue/attribution) // CRM → Umami (Phase 6) trackEvent(portId, name, payload, sessionId?) → POST /api/send // Links + Pixels admin (Phase 4) createTrackedLink(portId, name, destinationUrl) → POST team-level /links createTrackingPixel(portId, name) → POST team-level /pixels ``` Plus a new `umamiPost(config, path, body)` helper alongside the existing `umamiFetch` since GET-only doesn't cover reports + send. --- ## 4. Pixel-tracking answer (the user's specific question) **Q: Can we use Umami's pixel tracking for email opens?** **A: Yes — and recommended in hybrid form.** Direct verification on the live instance: - Pixel UI at `/teams/[teamId]/pixels` lets an admin create named pixels. Each gets an auto-generated slug. - The pixel URL is `https://analytics.portnimara.com/p/` — fetching it records an event (no auth required from the email client side; the slug is the credential). - Embedded as `` in HTML emails, it fires when the email is rendered (Outlook/Apple Mail/etc.). - Standard caveats: Apple Mail privacy protection pre-fetches images server-side → opens may be over-counted for iOS users. Some recipients block images entirely → opens under-counted. Same caveats as every email tracking pixel ever. **Recommended hybrid (Phase 4b above):** build a CRM-side pixel endpoint `/api/public/email-pixel/[sendId].gif` that: - Returns the 1×1 GIF - Records `opened_at` in `document_sends` - Cross-posts the hit to Umami via `POST /api/send` so the Umami Events tab + funnels include opens This way: per-recipient attribution in the CRM, aggregate roll-ups in Umami, single source of truth for both. --- ## 5. Effort summary + prioritization | Phase | Scope | Effort | Priority | | ----- | ------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------ | | 1 | Overview parity (KPI tiles, stacked-bar chart, date arrows, browser/OS/device cards) | ~3-4h | **High** — most visible polish, no dependencies | | 1b | World choropleth heatmap (already queued separately) | ~4-6h | **High** if leadership wants the visual | | 2 | Sessions surface (table + detail sheet + weekly heatmap) | ~4-5h | **High** — biggest "wow" + actionable | | 3 | Events surface | ~3-4h | **Medium** — blocked on 4a | | 4a | Marketing-site event tracking | ~2-3h (marketing repo) | **High** — unblocks 3 + 5 | | 4b | Pixel-based email open tracking (hybrid) | ~3-4h | **High** — direct ask + immediate value | | 4c | Tracked redirect links | ~1.5h | **Medium** | | 5 | Reports (Funnels, UTM, Journeys) | ~6-8h | **Medium** — depends on 4a being live | | 6 | CRM → Umami event push for outcome attribution | ~2-3h | **Medium-high** — needed to close marketing→outcome loop | | 7 | Cross-cutting placements (inquiry / client / berth detail cards) | ~3-4h | **Medium** — depends on `umami.identify()` on marketing site | **Recommended build order (updated 2026-05-19 per user):** 1. ✅ **Service refactor** — Kept hand-rolled `umamiFetch` (the official `@umami/api-client` transitively pulls `next-basics` which requires React at module-import time, breaking SSR + tsx scripts). Adopted `@umami/node` for the write side. 2. ✅ **Phase 1** — Overview parity (KPI tiles + browser/OS/device cards + date arrows + stacked-bar chart + `compare=prev` overlay) 3. ✅ **Phase 1b** — World heatmap. **Switched from `react-simple-maps` to ECharts + `public/world-map/echarts-world.json`** — the `world-atlas/110m` topojson has antimeridian-crossing polygons (Russia/Fiji/Antarctica) that render a horizontal line through the equator regardless of projection. ECharts' world.json is pre-cleaned. 4. ✅ **Phase 4b** — Pixel-based email open tracking. `document_send_opens` table + `/api/public/email-pixel/[sendId]` endpoint + `injectTrackingPixel` helper wired into `performSend`. Per-port kill switch `email_open_tracking_enabled` (admin UI on `/admin/website-analytics`). Cross-posts to Umami as `email-opened`. 5. ✅ **Phase 2** — Sessions surface. `SessionsList` (paginated, click-through to detail), `SessionDetailSheet` (full activity stream), `WeeklyHeatmap` (7×24 grid). API endpoints `sessions`, `session`, `session-activity`, `sessions-weekly`. 6. ✅ **Phase 6** — CRM → Umami event push. `trackEvent` calls wired into `createInterest` (`interest-created`), `updateInterestStage` (`interest-stage-changed`), `setInterestOutcome` (`interest-outcome-set`). 7. ✅ **Phase 7** — Cross-cutting placements. `email-sent` (in `performSend`), `eoi-signed` (in `handleDocumentCompleted`). Remaining placements (inquiry / berth detail attribution cards) defer until UI surfaces them. 8. ✅ **Phase 4c** — Tracked redirect links. `tracked_links` + `tracked_link_clicks` tables + `/q/[slug]` redirect endpoint + `createTrackedLink` / `buildTrackedUrl` service helpers. Email-composer integration deferred to UI follow-up. 9. **Phase 3 + Phase 5 — DEFERRED to the end.** Events tab is empty until marketing-site `umami.track()` calls land (Phase 4a, deferred). Funnels save for the end per user direction — pageview-only marketing funnel is the v1; richer event-based funnels come later. 10. **Phase 4a + cross-system funnels** — when there's appetite for marketing-site repo changes, unlock Events tab + cross-system funnels. **Total scope: ~22-28h** with library adoptions, of which ~13-15h is the high-priority Phases 1 + 1b + 4b + 2 + 6 that ship first. Total scope: ~30-40h end-to-end for the full flesh-out. --- ## 6. What stays in Umami vs. mirrored in CRM | In CRM (mirror) | In Umami only (deep-link) | | ----------------------------------------------------------- | ----------------------------------------------------------------- | | Overview / KPI tiles / trend chart | Replays (paid) | | Sessions list + detail | Retention (low signal) | | Top pages / referrers / countries / browsers / OS / devices | Saved Boards (admin power-user) | | Events + per-event drill | Pixels/Links admin CRUD (use Umami for setup; render data in CRM) | | Funnels + UTM + Journeys | Performance / Web Vitals | | World heatmap | Cohorts / Segments (defer until use case emerges) | | Email open tracking | Multi-website CRUD | Every page header in the CRM analytics surface gets a small "View in Umami →" outbound link in the corner for power users who want the full feature surface. --- ## 7. Open questions for the user before implementation 1. **Marketing site repo access**: Phase 4a (umami.track calls), Phase 4 (umami.identify for client linkage), and Phase 7 (passing sessionId to inquiry intake) all require changes there. Confirm whoever owns the marketing site is in the loop. 2. **Pixel hybrid vs Umami-only**: do you want per-recipient open tracking (hybrid) or just aggregate (Umami-only)? Recommended hybrid above; switch to Umami-only if the engineering cost isn't worth it. 3. **Funnel definitions**: who defines the canonical funnels? Suggest admins set them up via a CRM-side admin page that POSTs to Umami's `/api/reports/funnel`, with the most important funnels (inquiry, email-conversion) seeded as defaults at install time. 4. **Privacy / GDPR**: email pixel tracking + `umami.identify({email})` linkage both touch PII. Confirm consent model — likely already handled by the marketing-site cookie banner, but the email pixel needs explicit opt-out handling (e.g. don't fire pixel if the recipient is in a do-not-track list).