> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myfundingmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phase 2 processor redesign plan

# Phase 2 – Processor Pages Redesign Plan

**Branch:** `feat/processor-redesign-phase-2`
**Scope:** `app/admin/internal/processing/page.tsx` (1,734 lines, 8 tabs) and `app/admin/internal/funding-queue/page.tsx` (417 lines)
**Goal:** Bring both processor-facing pages into visual alignment with the Phase 1 Contact Page redesign (PR #463) — summary bar + consolidated tabs + shared primitives — **without touching data flow, hooks, or controllers**.

This document is the planning artifact. It must be reviewed and approved before any component code is written (per the task brief's Planning Phase requirement).

***

## 1. Context recap — what Phase 1 established

PR #463 set the design language we're now extending. The relevant contracts:

* **Summary bar** replaces the dashboard-style gradient header: compact horizontal row with avatar, name, meta, inline stage controls, and an action toolbar (`components/contact/ContactSummaryBar.tsx`).
* **Tab reduction**: 8 tabs → 5 tabs on the contact page (`Overview / Funding / Credit File / Docs & Notes / Client Info`).
* **Overview-first**: the Overview tab carries a `NextActionCard`, the hero credit/funding summary, a compact metrics row, and push-down decision controls.
* **Shared primitives** live under `components/shared/`:
  * `SectionLabel` — small-caps section header with a gradient hairline.
  * `AnimatedSection` — fade-in-up wrapper with a `delay` prop for staggered reveals.
  * `MetricCard` — 4-corner metric tile with a 2px top-gradient accent and optional subtitle/trend.
  * `StatusBadge` — variant-driven pill (`submitted`, `docs-needed`, `under-review`, `approved`, `funded`, `stale`, `prime`, `declined`).
* **Data layer untouched** — `useContactPageController` was not modified; only presentation was refactored.

Phase 2 inherits all of those rules.

## 2. Current state — processing page (`app/admin/internal/processing/page.tsx`)

### 2.1 Current structure

| Region                                         | What it is                                                                                                                                                                                                                                                | Lines       |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| Dark gradient header (`dashboard-header-bg`)   | Back button, avatar, name, email, phone, View As, Refresh, Agreement, Spotlight                                                                                                                                                                           | \~750–836   |
| Credit & Underwriting Hero card                | Credit score bucket, underwriting decision, estimated range, overall-status `<Select>`, Complete (Cards)/(TL) buttons, processing meta grid (Processing Type, Funding Category, Submitted By, Assigned To), funding-agreement link, processing notes body | \~854–1033  |
| Credit Details Grid (5 mini-cards)             | DTI, Late, Inquiries, Derogatory, Monthly Debt                                                                                                                                                                                                            | \~1035–1120 |
| Derogatory warning banner                      | Red strip if any derogatory item > 0                                                                                                                                                                                                                      | \~1122–1139 |
| Quick Stats Strip (4 divided cells)            | Late, Inquiries, Business, Address                                                                                                                                                                                                                        | \~1141–1226 |
| Processing Notes card (history of submissions) | Table-like list of all submissions' notes                                                                                                                                                                                                                 | \~1228–1277 |
| **8 tabs**                                     | Funding Plans, Communication, Credit Report, Agreements, Documents, Invoices, Details, Activity                                                                                                                                                           | \~1279–1663 |
| Modals                                         | `NewCreditRequestModal`, `SubmitTermLoanDialog`                                                                                                                                                                                                           | \~1666–1687 |

### 2.2 Current 8 tabs → proposed 5 tabs

| # | Current tab   | Content                                                                            | New home                                                                          |
| - | ------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| 1 | Funding Plans | `FundingPlanTable`                                                                 | **Overview** (primary working surface — funding plans is THE processor workhorse) |
| 2 | Communication | `TeamCommunicationPanel` (notes + internal chat)                                   | **Communication** (kept; processors spend significant time here)                  |
| 3 | Credit Report | `StitchCreditReport` + report picker + Pull Credit CTA + `CreditReportPDF` wrapper | **Credit File** (same name as Phase 1)                                            |
| 4 | Agreements    | Funding agreement link button                                                      | **Funding** (merged)                                                              |
| 5 | Documents     | `DocumentList`                                                                     | **Docs & Notes** (merged with sub-chips)                                          |
| 6 | Invoices      | `OperatorInvoiceHistory`                                                           | **Funding** (merged)                                                              |
| 7 | Details       | Personal + Address + Business + Tags + Metadata                                    | **Docs & Notes → Details** sub-chip (rarely opened; hide behind sub-filter)       |
| 8 | Activity      | `ProcessingActivityTimeline`                                                       | **Docs & Notes** sub-chip                                                         |

**Proposed tab set (5):**

1. **Overview** — summary bar context, next-action prompt, processing submission meta, funding plans table, processing notes.
2. **Funding** — Funding agreement + operator invoice history (the "money" tab).
3. **Credit File** — dossier-style credit report with history picker + Pull Credit.
4. **Docs & Notes** — documents / activity / details sub-chips (mirrors Phase 1's "Docs & Notes" sub-chip pattern).
5. **Communication** — internal team chat + notes.

### 2.3 What becomes the summary bar vs. what stays in tabs

**Moves to `ProcessingSummaryBar` (new, processor-specific header):**

* Back button → queue.
* Avatar (initials from contact name).
* Contact name (+ demo spotlight toggle).
* Pipeline-type badge (Card Processing / Term Loan / Both) derived from `submissionData.processingType`.
* Email / phone / city on second line (muted).
* **Overall Status** `<Select>` + `Complete (Cards)` / `Complete (TL)` buttons (high-value processor control — lifts them above the fold).
* Action toolbar (right): View As, Refresh, Agreement link, Spotlight (demo).

**Stays in the Overview tab body:**

* Credit score + underwriting decision hero (refactored to use Phase 1's `CreditScoreRing`-style summary but adapted to the processor's lower information needs — see §2.4).
* Processing submission meta grid (Processing Type, Funding Category, Submitted By, Assigned To, Submitted At, Completed At) — this is high-value processor context and stays inline.
* Credit metrics row (DTI / Late / Inquiries / Derogatory / Monthly Debt) — refactored from ad-hoc `Card` nodes into `MetricCard` components.
* `NextActionCard` (processor-variant) — "What should I do next?" contextual nudge (e.g., "Status is 'Funding Plan Needed' — assemble plans and submit" / "Processing Complete — mark status and invoice operator").
* Processing notes card (history list) — stays in Overview but collapsed by default behind a toggle (mirrors Phase 1's "Show full credit report" toggle pattern).
* Funding plans table (`FundingPlanTable`) — the primary working surface.

### 2.4 Hero summary vs. Phase 1 CreditScoreRing

The contact page uses a 3-bureau SVG ring (`CreditScoreRing`). The processing page only has a single aggregate score from the stored `creditReport` and no separate bureau breakdown readily available — so building a 3-bureau ring would be misleading.

**Decision:** reuse Phase 1's `CreditScoreRing` in **single-score mode** (passing `creditScore` and leaving the TU/EQ/EX props undefined) rather than forking a new ring. If `CreditScoreRing` doesn't already support "single score only" cleanly, we extend it with a `compact` prop — that's a shared-component extension, not a new primitive, and is the only acceptable primitive-level change. **We will inspect `CreditScoreRing.tsx` before deciding; if it already no-ops bureau ring rendering when the props are absent, no change is needed.**

## 3. Current state — funding-queue page (`app/admin/internal/funding-queue/page.tsx`)

### 3.1 Current structure

| Region                                       | Content                                                                                                                                                       |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Dark gradient header (`dashboard-header-bg`) | `ClipboardList` logo, "Funding Queue (All Accounts)" title, subtitle, `uniqueLocations` counter, Invoices link, `ProcessorTeamManager`, `ProcessorHelpDialog` |
| Tab row + Pull Next                          | `FundingQueueTabs` (All / My Queue), `Pull Next` button                                                                                                       |
| Stats cards                                  | `FundingQueueStatsCards` or `MyQueueStatsCards`                                                                                                               |
| Filters                                      | `FundingQueueFilters`                                                                                                                                         |
| Table                                        | `FundingQueueTable` (or `MyQueueEmptyState`)                                                                                                                  |
| Pagination                                   | Prev / Next + counts                                                                                                                                          |

### 3.2 Proposed funding-queue structure (no tab concept on this page)

Per the task brief: *"simpler, likely summary bar + single table + filters"*. The existing tabs (All / My Queue) are a filter, not a navigation tab, so we keep them. The page becomes:

1. **Summary bar** (light-surface) — `ProcessorQueueSummaryBar`:
   * Icon + "Funding Queue" title with Phase 1 typography.
   * `uniqueLocations` chip (badge).
   * Right side: Invoices link, `ProcessorTeamManager`, `ProcessorHelpDialog`, Pull Next (when in My Queue).
   * Eliminates the dark gradient banner in favour of the Phase 1 hairline + generous negative space.
2. **Tab row** (All / My Queue) + filters in a single row (condensed).
3. **Stats strip** using `MetricCard`s (re-skin of `FundingQueueStatsCards` and `MyQueueStatsCards`).
4. **Filters bar** (`FundingQueueFilters` — unchanged component, just loses its dashboard-section wrapper).
5. **Table** (`FundingQueueTable` — unchanged; out of scope per brief).
6. **Pagination** — re-skinned with Phase 1 tight spacing.

### 3.3 What doesn't change

* `useAdminFundingQueue` hook — untouched.
* `FundingQueueTable` internals — untouched (presentation wrapper only).
* `FundingQueueFilters` internals — untouched.
* `ProcessorTeamManager`, `ProcessorHelpDialog` — untouched (rendered by summary bar).
* Pull-Next / claim flow — untouched.

## 4. Shared vs. new components

### 4.1 Reused from `components/shared/` (zero new primitives unless justified)

* `MetricCard` — processing credit metrics grid + funding-queue stats strip.
* `StatusBadge` — processing submission status pill (variants: `submitted`, `docs-needed`, `under-review`, `approved`, `funded`, `stale`). **The existing `variantStyles` in `StatusBadge.tsx` already covers the processing-queue statuses** (`submitted` → `funding_plan_needed`, `under-review` → `processing_in_progress`, `docs-needed` → `additional_info_required`, `funded` → `card_processing_complete` / `tl_processing_complete`, `stale` → `closed_no_longer_processing`). We'll write a `mapProcessingStatusToBadgeVariant(status)` helper rather than add new variants.
* `SectionLabel` — section headers on both pages.
* `AnimatedSection` — staggered fade-in on Overview sections.

### 4.2 Reused from Phase 1's contact components (verified safe to reuse)

* `CreditScoreRing` — processing Overview hero.
* `NextActionCard` — we'll **thin-wrap** it in a new `ProcessorNextActionCard` that maps processing-submission status → next-action payload, reusing the same presentational shell. If `NextActionCard` is tightly coupled to approved/declined underwriting states (likely), we'll author a purpose-built `ProcessorNextActionCard` and **not** modify the contact version.

### 4.3 New page-specific components (under `components/processing/` and `components/funding-queue/`)

**`components/processing/`** (new folder):

* `ProcessingSummaryBar.tsx` — processor-specific horizontal bar (summary bar analog). Not a generic component — processor-specific controls (overall status select, Complete-Cards/TL buttons, Pipeline-type badge) make a shared bar undesirable.
* `ProcessingOverviewTab.tsx` — composes the Overview tab body (next action, credit/underwriting summary, meta grid, metrics, funding plans, processing notes).
* `ProcessingStatusControls.tsx` — extracted overall-status `<Select>` + Complete-Cards/TL button group (kept in the summary bar, but extracted for readability and reuse-within-page).
* `ProcessingSubmissionMetaGrid.tsx` — 4-cell grid (Processing Type / Funding Category / Submitted By / Assigned To) styled with `SectionLabel`.
* `ProcessingCreditMetricsRow.tsx` — `MetricCard`-based DTI / Late / Inquiries / Derogatory / Monthly Debt strip (processing flavour of `CreditMetricsRow`; processor metrics are different enough that reusing the contact version would require prop coupling).
* `ProcessorNextActionCard.tsx` — processor-workflow next-action nudge (Phase 1 `NextActionCard` is underwriting-flow-specific; we author the processor analog here).
* `ProcessingNotesCard.tsx` — processing notes list card.
* `DocsNotesTabShell.tsx` — Phase 1-style sub-chip shell wrapping documents / activity / details.

**`components/funding-queue/`** (existing folder, additions):

* `ProcessorQueueSummaryBar.tsx` — light-surface queue header (replaces the dark gradient banner).
* `FundingQueueMetricsStrip.tsx` — `MetricCard`-based stats strip. Internally delegates to the existing `FundingQueueStatsCards` / `MyQueueStatsCards` data, but renders through `MetricCard` for visual parity with the contact page.

**Justification for the new components (required by brief):**

* None of them duplicate a shared primitive — they are page-specific compositions of the shared primitives.
* `ProcessingSummaryBar` is processor-specific; extending `ContactSummaryBar` to handle processor controls would bloat its prop surface and couple two unrelated pages.
* `ProcessorNextActionCard` is workflow-specific; reusing `NextActionCard` would require overloading its state machine.

## 5. Data-layer / hook implications

Reviewed the data flow on both pages. **No data-layer changes are required.** The processing page's hooks (`useContactData`, `useQuery` for `submissionData` / `planSnapshotData` / `creditReport` / `allCreditReports` / `agreementDocuments` / `processingNotes` / `termLoanSubmission`, the `useMutation`s, the term-loan action, the two `useCallback` note/comment helpers) are all consumed by presentation-only. The funding-queue page delegates entirely to `useAdminFundingQueue`. Modals (`NewCreditRequestModal`, `SubmitTermLoanDialog`) keep their existing wire-up.

**No data-layer blockers — proceeding to execution after plan approval.**

## 6. `frontend-design` skill — sections applied

Per the brief, we cite specific skill sections we're applying:

* **Design Thinking → Tone:** *refined / editorial*. The processor pages are tools for a back-office audience — we commit to restrained, information-dense elegance (not maximalist chaos). Phase 1 already set this tone; Phase 2 matches it.
* **Typography:** we inherit Phase 1's type system (heading + body + small-caps `SectionLabel`) rather than introducing a third face on a secondary surface. Consistent kerning (`tracking-wider` uppercase labels) across surfaces reinforces the editorial tone.
* **Color & Theme:** drop the dark-gradient `dashboard-header-bg` on the processing + funding-queue pages in favor of the light/soft-card surface + gradient hairline divider Phase 1 uses. Status colours continue to flow through `StatusBadge`'s variant map — dominant neutrals with targeted accent pops rather than a full rainbow.
* **Motion:** staggered `AnimatedSection` reveals on page load (delay: 0ms, 80ms, 160ms, 240ms). One high-impact moment, not scattered micro-interactions, matches the skill's guidance.
* **Spatial Composition:** tight compact spacing (`py-3.5`, `gap-4`, `px-5` as used in `ContactSummaryBar`); controlled density rather than generous whitespace (processors want information density). Unchanged grid underneath Funding-Queue table.
* **Backgrounds & Visual Details:** retain the `bg-gradient-to-r from-transparent via-gold-400/30 to-transparent` hairline divider as the atmospheric detail that ties pages together (same gold accent Phase 1 uses on dashboards).
* **Avoid AI slop:** no purple-gradient-on-white, no generic Inter/system-font switch (inherits project's existing `font-heading` + body pairing), no cookie-cutter KPI tile. `MetricCard`'s 2-pixel gradient top-bar accent is the distinguishing detail.

## 7. Acceptance criteria

* [ ] Processing page tab count drops from 8 → 5 (Overview, Funding, Credit File, Docs & Notes, Communication).
* [ ] Funding-queue page dark gradient banner replaced with a Phase 1-style summary bar + hairline.
* [ ] All Phase 1 shared primitives (`MetricCard`, `StatusBadge`, `SectionLabel`, `AnimatedSection`) reused.
* [ ] No new shared primitives added (only page-specific compositions under `components/processing/` and `components/funding-queue/`).
* [ ] `npx tsc --noEmit` clean.
* [ ] Relevant tests under `tests/` (processing / funding-queue) still pass.
* [ ] All modals, overlays, data hooks preserved byte-for-byte.
* [ ] PR split into three reviewable commits: (1) processor components, (2) funding-queue components, (3) page refactors.

## 8. Commit strategy

Per the brief's 3-commit split:

1. **`feat(processing): add processor-specific components built on Phase 1 primitives`** — adds `components/processing/*` (summary bar, overview tab, meta grid, metrics row, next-action, notes card, docs-notes shell). Zero page-level changes. Compiles but isn't yet rendered anywhere.
2. **`feat(funding-queue): add summary bar + metrics strip using Phase 1 primitives`** — adds `components/funding-queue/ProcessorQueueSummaryBar.tsx` + `FundingQueueMetricsStrip.tsx`. Zero page-level changes.
3. **`feat(processing, funding-queue): refactor pages to Phase 1 layout`** — edits `app/admin/internal/processing/page.tsx` (8 tabs → 5, new summary bar) and `app/admin/internal/funding-queue/page.tsx` (new summary bar, new metrics strip). This is the visible cut-over commit.

Each commit runs `npx tsc --noEmit` clean independently.

## 9. Open questions (none blocking, but worth flagging)

1. **Processing page's "Processing Notes" card** — currently shows *all* prior submissions' notes (useful history). We're collapsing it by default behind an expand toggle to keep the Overview above-the-fold tight. Flag: this changes scan-ability. If processors rely on always-visible notes, we'll flip the default back to expanded. **Default: collapsed, remember expansion in local state.**
2. **Communication tab placement** — Phase 1 folded activity+notes into "Docs & Notes" sub-chips. On the processing page, team-communication is a *heavier* surface (internal operator-to-processor chat) — we keep it as a top-level tab. Alternative: fold it into "Docs & Notes" sub-chip to hit 4 tabs. **Default: keep as its own 5th tab.**
3. **Funding-queue "All Accounts" subtitle** — the dark header currently reads "Funding Queue (All Accounts)" in a refined display type. We preserve the subtitle copy but move it into the new summary bar's secondary line.

## 10. Out of scope (per brief)

* Convex queries / data-layer changes.
* Auth / permissions logic.
* Modal/dialog component internals.
* `FundingQueueTable` table logic (presentation-only wrapper allowed).
* Any other admin/internal pages.

***

**Reviewers:** please sign off on §2.2 (tab consolidation), §3.2 (funding-queue structure), and §4 (new component surface). Once approved, execution proceeds per §8.