PSA/ee/docs/plans/2026-06-15-tickets-list-bundle-reduction/PRD.md

PRD — Tickets List Load-Time Reduction (bundle/hydration)

Status: Draft for review Owner: TBD Created: 2026-06-15 Plan slug: 2026-06-15-tickets-list-bundle-reduction

---

1. Problem statement & user value

The MSP ticketing dashboard (/msp/tickets) is slow to become usable. A production performance trace (algapsa.com, warm cache) shows:

• LCP 3,048 ms, of which 2,774 ms (91%) is render delay — the browser receives HTML quickly (TTFB 274 ms) but can't paint until it finishes executing the route's JS.
• ~9.3 MB of decoded JavaScript across 103 chunks hydrating on the list route.
• Backend is not the bottleneck: server actions return in ~24–27 ms.
• The list route eagerly bundles heavy client code that is not on screen at first paint:
  • 7 dialogs imported only by the list (BulkAssign/Tags/DueDate/Status/Priority, TicketImportDialog, TicketExportDialog).
  • The full ClientDetails component (2,215 lines + all client tabs) for the side-drawer quick view, even though the drawer only ever shows the first ("details") tab.
• Each list view also fires 48 redundant RSC prefetch requests (two <Link>s per row × ~24 rows) that force the server to render ticket detail pages nobody asked for.

User value: the tickets list paints and becomes interactive noticeably faster, and the server stops doing wasted detail-page renders on every list view.

2. Goals

• G1 (primary): Reduce tickets-list initial JavaScript / hydration cost and improve LCP / render delay, measured by build output (list route first-load JS) and a repeat production-style performance trace.
• G2: Remove the redundant per-row RSC prefetch traffic from the list.
• G3: Replace the full-weight client drawer with a genuinely lightweight ClientQuickView, and reuse it at every client quick-view call site.
• G4: Move the 7 list-only dialogs out of the list route bundle via route-level code splitting (static imports only).

3. Non-goals

• No next/dynamic / React.lazy / import() code-splitting. Architectural decision: the team avoids dynamic imports to keep module boundaries clean.
• No changes to QuickAddTicket or its rich-text editor. It is shared across 9 surfaces (including the global header quick-create), so list-only extraction yields little app-wide benefit. Tracked as a possible separate future plan.
• No change to QuickAddCategory — shared by 4 components, not cleanly list-only.
• App-shell server-action burst (~20 POSTs during hydration) and the 15 s job-metrics poll (Header.tsx) — real but shell-level; out of scope here.
• Deep-linkable / refresh-safe dialog URLs are not a goal (acceptable side effect of intercepting routes, but we will not invest extra to guarantee it).

4. Hard constraints

• C1 — No visual change for end users. Dialogs must still appear as modal overlays on top of the list (not full-page navigations). The client drawer must look identical.
• C2 — Dialogs must respect all current list filters (and, for bulk actions, the current row selection), exactly as today.
• C3 — No dynamic imports (see non-goals).
• C4 — Multi-tenant safety unchanged. This is primarily a UI/bundling refactor; any server actions reused by new routes keep their existing tenant scoping.

Routing decision (derived from C1 + C2 + C3): Plain separate full pages are ruled out (they change the UX from modal → full navigation, violating C1). Keeping the dialogs inside the list component keeps them in the list bundle (fails G1/G4). With dynamic imports off the table (C3), the only approach that satisfies all three is Next.js intercepting routes + a parallel @modal slot: each dialog lives in its own route segment (so it's a separate, statically-imported route bundle) but renders as a modal overlay over the still-mounted list. This pattern does not exist in the codebase yet.

5. Affected users / flows

• MSP internal users on the tickets list: open Quick View on a client, run bulk actions on selected tickets, import/export tickets. All flows must look and behave the same.
• Any user hitting the other client quick-view surfaces (clients list, billing dashboard, ticket detail drawer, projects, interactions, user list) — they get the new lighter component with identical appearance.

6. Approach (workstreams)

A. Row-link prefetch fix (smallest, immediate)

• Add prefetch={false} to the two <Link>s in packages/tickets/src/lib/ticket-columns.tsx (ticket-number col ~line 219, title col ~line 273). Clicks are already intercepted (e.preventDefault() → onTicketClick), and middle-click / open-in-new-tab keep working via the retained href.

B. Lightweight ClientQuickView + reuse everywhere

• Rebuild packages/clients/src/components/clients/ClientQuickView.tsx so it imports only the "details" tab content (what ClientDetails renders when quickView → tabContent[0]), not the full ClientDetails module (which statically imports contacts list, billing config, interactions feed, notes panel, and 3 Hudu tabs).
• Extract the shared details-tab content into a small component so both ClientDetails (full page) and ClientQuickView can use it without ClientQuickView dragging in the other tabs.
• Wire all client quick-view call sites to ClientQuickView:
  • packages/msp-composition/src/tickets/MspTicketsPageClient.tsx:18
  • packages/msp-composition/src/tickets/MspTicketDetailsContainerClient.tsx:71
  • packages/msp-composition/src/clients/MspClientDrawerProvider.tsx:36
  • packages/msp-composition/src/billing/MspBillingDashboardClient.tsx:18
  • packages/msp-composition/src/projects/MspClientIntegrationProvider.tsx:44
  • packages/clients/src/components/clients/Clients.tsx:1779
  • packages/clients/src/components/interactions/InteractionDetails.tsx:209
  • packages/projects/src/components/Projects.tsx (renderClientDetails, ~1024)
  • server/src/components/settings/general/UserList.tsx:206
  • (verify contact-context <ClientDetails> usages: Contacts.tsx:697, MspContactTickets.tsx:230 — classify as client quick view or leave)

C. Route-extract the 7 list-only dialogs (intercepting + parallel routes)

• Add server/src/app/msp/tickets/layout.tsx hosting {children} + a @modal parallel slot, and server/src/app/msp/tickets/@modal/default.tsx returning null.
• Create route segments for each dialog under msp/tickets/... with an intercepting (.) variant in @modal that renders the dialog as an overlay, plus a plain segment for the hard-load fallback.
• Triggers on the list become navigations (router.push / <Link>) to those routes instead of toggling local isOpen state; the dialog components move into the route segments so they leave the list route's module graph.
• Shared state: introduce a tickets-segment client context provider (in tickets/layout.tsx) holding the current filters and selected ticket ids, so the intercepting modal routes (sibling subtrees that cannot read the list page's local state) can honor C2. The list writes to it; dialog routes read from it. Filters are already partly URL-synced (TicketingDashboard.tsx:510,625) and can be read from searchParams as a backstop.
• Dialog order by effort/benefit: Import → Export (no selection dependency, easiest, likely heaviest) first; then the 5 bulk dialogs (require the selection context).

7. Data model / API notes

No schema changes. Existing server actions (bulk assign/tags/due-date/status/priority, import, export, client fetch) are reused unchanged and keep their tenant scoping. Export/bulk-select-all must continue to pass the current ITicketListFilters to the server action so results respect filters (C2).

8. Risks & mitigations

• R1 — Intercepting/parallel routes are a new pattern here. Risk of focus/scroll/ back-button regressions and SSR quirks. Mitigation: prototype one dialog (Import) end-to-end first; add a default.tsx; manual + e2e checks for open/close/refresh/back.
• R2 — Selection-state lifting is the highest-effort item. Selection lives deep in TicketingDashboard (selectedTicketIds, line 252). Mitigation: lift to a small tickets-scoped context; if a bulk dialog's effort:benefit is poor, it may stay in-list (re-evaluate during A/B; user scoped "all" but ROI matters).
• R3 — Filter fidelity (C2). Modal routes must see the exact active filters. Mitigation: shared context is source of truth; e2e assert each dialog acts on filtered set.
• R4 — ClientQuickView is reused at ~10 sites. Rebuilding it risks regressions across clients/billing/projects/tickets. Mitigation: keep visual output identical to current quickView details tab; verify each call site.
• R5 — "No visual change" (C1). Modal-from-route must match current modal styling/ behavior. Mitigation: reuse the existing Dialog components inside the route segments.

9. Success metrics / Definition of Done

• DoD-1: Production-style repeat trace of /msp/tickets shows reduced render delay and LCP vs. the 2,774 ms / 3,048 ms baseline (record exact numbers in SCRATCHPAD).
• DoD-2: next build shows the tickets-list route first-load JS reduced; the 7 dialogs and full ClientDetails no longer appear in the list route chunk graph.
• DoD-3: Loading the list fires 0 per-row RSC prefetch requests; clicking a ticket still opens it; middle-click/open-in-new-tab still work.
• DoD-4: Every client quick-view surface renders the lightweight ClientQuickView and looks identical to today.
• DoD-5: Each dialog opens as a modal overlay (no full-page nav), respects current filters/selection, and performs its action correctly. No visual change reported.
• DoD-6: No next/dynamic / React.lazy introduced.

10. Open questions

• OQ1: Confirm the intercepting-routes approach is acceptable as a new pattern (it's the only option satisfying C1+C2+C3). If not, we must relax C1 (allow full pages) or C3.
• OQ2: Is there an existing client-side store pattern (zustand/jotai/context) preferred for the tickets selection/filter context, or should we add a plain React context?
• OQ3: For bulk dialogs with poor effort:benefit, is leaving them in-list acceptable, or is full extraction of all 7 required?
• OQ4: Should Contacts.tsx:697 / MspContactTickets.tsx:230 <ClientDetails> usages be migrated to ClientQuickView too, or are they intentionally full?