Incremental Admin UI Migration

Companion write-up for Admin Web Migration.

Problem

Admin views accumulated three structural issues:

1. Duplicated ingestion plumbing — parse, map, validate, and error UI rewritten per page
2. Silent form loss — complex mappings vanished on accidental modal dismiss
3. Fetch churn — wizards re-queried org metadata on every step

Constraints

• Ops had to keep using the tools during migration
• Large sheets needed fast client-side pre-validation
• Validation contracts had to stay aligned with existing CRM schemas

Approach

flowchart TD
  UploadFile[CSV / XLSX] --> IngestionUI[Upload View]
  IngestionUI --> Validator{SheetValidationUtil}
  Validator -->|Mismatch| DisplayError[Inline Row/Column Errors]
  Validator -->|Valid| Stepper[CustomStepper]
  Stepper --> PreviewGrid[Mapping Preview]
  PreviewGrid --> ModalGuard{wrapDialogWithDirtyCheck}
  ModalGuard -->|Mutated| Warn[Unsaved Work Confirmation]
  ModalGuard -->|Commit| APIPayload[Batched API Request]

Patterns

1. SheetValidationUtil — column presence, types, length bounds in-browser
2. wrapDialogWithDirtyCheck — intercept dismiss/navigation with unsaved edits
3. CustomStepper — one wizard shell for ingestion flows
4. Normalized domain cache — roles/processes loaded once per flow

Outcomes (high confidence)

• Core modules moved without a scheduled admin blackout
• Accidental dismissals stopped wiping multi-field mappings
• Later CRM integration UIs reused the same upload/validation contracts

Velocity claims like “50% faster” are omitted here without a measured baseline. The durable win is shared primitives that new admin flows inherit.