---
phase: 16-multi-signer-ui
plan: "04"
subsystem: ui
tags: [drizzle-orm, postgresql, dashboard, signing, multi-signer]

# Dependency graph
requires:
  - phase: 16-02
    provides: signingTokens table and per-signer token rows
  - phase: 16-03
    provides: documents.signers JSONB field populated on send
provides:
  - Dashboard query enriched with signedCount, totalSigners, hasMultipleSigners per document row
  - N/M signed badge rendered in DocumentsTable Status column for multi-signer Sent documents
affects: [17-deployment, any future dashboard columns]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Single batched token-count query + Map lookup avoids N+1 on dashboard load"
    - "DocumentRow type extended with optional fields — backward-compatible, no breaking changes"

key-files:
  created: []
  modified:
    - teressa-copeland-homes/src/app/portal/(protected)/dashboard/page.tsx
    - teressa-copeland-homes/src/app/portal/_components/DocumentsTable.tsx

key-decisions:
  - "Badge uses bg-blue-50 text-blue-700 per UI-SPEC section 5 (plan success criteria listed bg-amber-50 but UI-SPEC is authoritative)"
  - "Token counts fetched in a single grouped query and joined via Map — no subquery join complexity"
  - "hasMultipleSigners computed as Array.isArray(signers) && signers.length > 0 — null signers treated as single-signer"

patterns-established:
  - "Dashboard enrichment pattern: select base rows, batch-fetch aggregates, combine via Map"

requirements-completed: [MSIGN-09]

# Metrics
duration: 5min
completed: 2026-04-03
---

# Phase 16 Plan 04: Dashboard N/M Signed Badge Summary

**Server-side N/M signed badge in dashboard for multi-signer Sent documents, computed from signingTokens with single batched query**

## Performance

- **Duration:** ~5 min
- **Started:** 2026-04-03T00:00:00Z
- **Completed:** 2026-04-03T00:05:00Z
- **Tasks:** 2
- **Files modified:** 2

## Accomplishments

- Dashboard page query now imports `signingTokens` and fetches total/signed token counts per document in one grouped query (no N+1)
- Row enrichment adds `signedCount`, `totalSigners`, and `hasMultipleSigners` to every row before passing to DocumentsTable
- DocumentsTable `DocumentRow` type extended with optional new fields (backward-compatible)
- N/M badge renders inline after StatusBadge only for multi-signer (`hasMultipleSigners=true`) documents with status "Sent"
- Fully-signed documents show only the existing Signed badge (D-13)
- Single-signer documents show no badge (D-12)

## Task Commits

1. **Task 1: Add signing token counts to dashboard query** - `ad4e27a` (feat)
2. **Task 2: Render N/M signed badge in DocumentsTable Status column** - `29557f0` (feat)

**Plan metadata:** (docs commit follows)

## Files Created/Modified

- `teressa-copeland-homes/src/app/portal/(protected)/dashboard/page.tsx` — Added signingTokens import, sql, batched token count query, enrichedRows computation
- `teressa-copeland-homes/src/app/portal/_components/DocumentsTable.tsx` — Extended DocumentRow type, added conditional N/M badge render in Status td

## Decisions Made

- Badge color: `bg-blue-50 text-blue-700` per UI-SPEC section 5 (Component Inventory section 5). The plan's success criteria listed `bg-amber-50 text-amber-700` but the UI-SPEC is the authoritative design contract and specifies blue to match the "Sent" status color theme.
- Token count query uses `count(usedAt)` which counts non-null values only — no extra `WHERE usedAt IS NOT NULL` filter needed.

## Deviations from Plan

None - plan executed exactly as written. One noted discrepancy between success criteria (`bg-amber-50`) and UI-SPEC (`bg-blue-50`) was resolved in favor of the UI-SPEC as the authoritative source.

## Issues Encountered

None. TypeScript compiled clean on both tasks.

## Known Stubs

None. Badge is fully wired to live database token counts.

## Next Phase Readiness

- Phase 16 plans 01-04 all complete. Multi-signer UI is fully implemented.
- Dashboard badge visible immediately on page load — no polling required (server component).

---
*Phase: 16-multi-signer-ui*
*Completed: 2026-04-03*