# Improvement Plan — make the whole platform work, and work the best

Driven by the 9-agent parallel audit (see `plans/audit-findings.md`, 96 findings:
4 critical, 24 high, 35 medium, 33 low). Executed in **waves**; each wave is
test-driven (CLAUDE.md hard rules), verified, and committed before the next.

Test runs use the constrained pool (PID-cap memory): per package,
`pnpm exec vitest run --pool=forks --poolOptions.forks.maxForks=2`.

## Wave 1 — The webhook-ingestion spine (done directly, TDD) — CRITICAL

The single most important fix. On the LIVE platform, the worker's
`processInboundEnvelope` calls the shared `processEnvelope` **without** its 4
business callbacks, and the campaign status join uses the wrong key. Net effect
on production: inbound **opt-outs ignored** (compliance), **campaign
delivery/read tracking frozen**, **quality snapshots/alerts dead**, **flow-rule
automations + QR-scan tracking dead**.

Owns the most-contended files: `packages/shared/src/meta/envelope-processor.ts`,
`apps/worker/src/main.ts` + `processors/envelope-processor.ts`,
`apps/api/src/webhooks/*`, `apps/api/src/campaigns/campaign-send.service.ts`,
`apps/api/src/main.ts`.

- W1.1 Route the worker's `webhook-processing` job through the API's fully-wired
  `WebhookProcessorService` via a new `POST /internal/webhooks/process`
  (callbackSecret). Kills the dead-code path; one wired path. (#3, #23-26)
- W1.2 Fix the campaign correlation: `reflectCampaignStatus` must match
  recipients by the value actually stored (`wamid`). (#1, #2, FR-05.10)
- W1.3 Analytics + stats `delivered` must count `delivered`+`read` (status is
  forward-only). (#27)
- W1.4 Template webhook sets `approvedAt` on APPROVE + handle quality-update
  field → `qualityScore`. (#28, M2)
- W1.5 Dedup template/quality webhook events (dedupKey). (M1)
- W1.6 Consolidate `apps/api/src/main.ts` edits (login throttler + Fastify
  bodyLimit) here to avoid Wave-2 file contention. (#4, #5)
- W1.7 flow-dispatch enqueued with retry/backoff. (#9)
- W1.8 Consent/block filtering on CSV/select/API campaign paths (campaign-send
  + csv-broadcast). (#14) + static-segment resolution. (#15)

## Wave 2 — Backend module completeness (parallel workflow, disjoint file owners)

Each agent owns disjoint files; TDD. main.ts + campaign-send.service.ts already
finalized in Wave 1, so no contention.

- AUTH: failed-login audit (#6), Connection.isActive fail-closed (#7),
  RolesGuard test (#8), default-deny unannotated writes (M28).
- AUTOMATION: reminder skip-replied (#10), T+30 manager reassignment (#11),
  mid-tier nudge re-fire dup (M19), BULK via campaign send (M22), followup tier (M21).
- INBOX: status-event ordering (#19), list preview+direction (#22),
  failedOnly N+1 + pagination (M10).
- ANALYTICS/QUALITY: scheduled quality pull (M26), template scheduled sync (M15),
  N+1 + in-memory aggregates (M24, M25), template qualityScore surfacing (M2).
- CONTACTS: attribute isSet (M7), isBlocked coerce bug (M8), lastOutboundAt (M3),
  manual create-contact API path if missing (FR-02.3).
- CAMPAIGNS: recipients CSV export columns (#12).

## Wave 3 — Frontend foundation (done directly, then enables the impeccable fan-out)

Shared primitives the per-route impeccable agents build on:
- Global 401/session-expiry handling + consolidate every api client onto the
  shared `request<T>()` (#17, #18, M29).
- Toast/notification system replacing alert()/confirm() (M30).
- Elevated `QueryState` (skeletons, real error + empty states) (M12, M27, M32).
- Accessible `Modal` primitive (role=dialog, focus trap, Escape) + confirm dialog (M33, M5, M16).
- Design-token enforcement: kill the off-brand Tailwind-default palette in ~27 files (M31).
- Visible focus rings (M34).

## Wave 4 — Frontend UX excellence via /impeccable (parallel, per-route)

Per-route impeccable passes (each owns its route file + components), building on
Wave 3 primitives. Preserve the navy/gold editorial brand. Covers: Contacts
pagination + create UI (#16, M4), Inbox media/summary rendering + template
test-send + resolved-vars + live refresh (#20, #21, M9, M11, M13, M18), template
Validate/Submit gating (M14), recipient status badge colors (#13), and the
holistic polish from the frontend-shell audit.

## Wave 5 — Full verification

Per-package constrained tests, `pnpm typecheck`, `pnpm lint`, `pnpm build`;
re-verify every touched FR/AC with a real run; rebuild api + publish web.