Skip to content

PROGRESS.md

Latest commit

 

History

History
108 lines (86 loc) · 6.66 KB

PROGRESS.md

File metadata and controls

108 lines (86 loc) · 6.66 KB
Raw

Map Studio Modernization Roadmap

Snapshot

Area Status Notes
Foundation guardrails ✅ Complete ESLint/TypeScript enforced, CI lint+type-check running
Routing & shell ✅ Complete Marketing pages SSR-ready with SEO metadata; studio remains client-heavy
Architecture refactor ✅ Complete Monolith broken into composable modules; map-preview reduced 83%
Data & caching ✅ Complete Geocode proxy, topology streaming, Vercel KV caching
Accessibility ✅ Complete WCAG AA, keyboard access, contrast validation, Axe CI checks
Testing ⏳ Planned Unit, integration, e2e, visual regression
Performance ✅ Complete Bundle budgets, lazy hydration, Web Worker infrastructure, Lighthouse CI
Ops & observability ⏳ Planned Monitoring, feature flags, deployment safeguards

Phase Checklist

  1. Foundation Guardrails (Done)

    • Remove lint/type ignores from build
    • Add pnpm type-check script and GitHub Actions workflow for lint + type check

  2. Routing & Shell Restructure (Complete)

    • Split app/ into (marketing) and (studio) route groups with proper layouts
    • Convert landing/marketing pages to server components and ensure SSR for critical paths
      • Landing page (/landing) is fully server-rendered with proper metadata for SEO
      • Added comprehensive metadata (title, description, OpenGraph, Twitter cards) for optimal SEO
      • Marketing layout is server component ensuring SSR for all marketing routes
      • Studio editor remains client-heavy as intended for interactive functionality
    • Move theme/toast providers into minimal client subtrees; introduce app/(studio)/layout.tsx shell

  3. State & Data Modules Extraction (Complete)

    • Introduce typed store (Zustand) for data ingest, styling, geocoding slices
    • Move CSV parsing & custom SVG helpers into modules/data-ingest
    • Extract map-type inference and dimension resets into modules/data-ingest
    • Finish moving schema validation and advanced dimension logic into modules/
      • Extract legend formatting and label preview helpers into shared modules
      • Centralize palette presets via modules/data-ingest/color-schemes and rewire dimension mapping UI
      • Move TopoJSON fetching into useGeoAtlasData hook for map preview renderer
    • Break map-preview into composable layers (renderer, legends, controls) — Reduced from 2,579 to 436 lines (83% reduction), fully type-safe, uses extracted modules

  4. Data Fetching & Caching Strategy (Complete)

    • Create app/api/geocode proxy with rate limiting and Vercel KV caching (graceful fallback to in-memory)
    • Create app/api/topojson route with server-side caching and CDN fallbacks
    • Adopt TanStack Query for client revalidation and cache hydration
    • Upgrade to Vercel KV/Redis for production caching (with in-memory fallback)
    • Add request deduplication for concurrent API calls
    • Implement Suspense boundaries for TopoJSON loading
    • Add monitoring/metrics API endpoint (/api/metrics)

  5. Accessibility Hardening (Complete)

    • Enable eslint-plugin-jsx-a11y and configure accessibility linting rules
    • Add accessible map summaries and descriptions for screen readers
    • Fix form label associations (htmlFor attributes)
    • Add keyboard navigation support for collapsible panels (Enter/Space keys)
    • Add ARIA attributes (aria-label, aria-expanded, aria-controls, aria-describedby)
    • Create color contrast validation utilities (lib/accessibility/color-contrast.ts)
    • Add accessible descriptions to map preview SVG
    • Add Axe runtime checks in development (@axe-core/react in providers.tsx)
    • Set up Playwright E2E tests with Axe (@axe-core/playwright)
    • Add accessibility test job to CI workflow (.github/workflows/ci.yml)
    • Integrate color contrast validation into UI components (optional enhancement)

  6. Testing & Quality Gates

    • Stand up Vitest for units with coverage on stores/utilities
    • Add Playwright/Cypress flows for ingest → map render workflows
    • Integrate visual regression/Storybook snapshots for key components

  7. Performance Optimization Pass (Complete)

    • Introduce bundle size budgets and Next.js analyzer reports in CI
      • Added @next/bundle-analyzer with build:analyze script
      • Configured webpack code splitting for D3, React Query, Radix UI chunks
      • Created scripts/check-bundle-size.js for bundle size budget enforcement
      • Added bundle size check job to CI workflow
    • Implement island architecture / lazy hydration for heavy panels
      • Lazy loaded DataPreview, DimensionMapping, MapStyling, MapPreview components
      • Added Suspense boundaries with fallback components
      • Reduced initial bundle size by deferring heavy component loading
    • Offload expensive D3 calculations to Web Workers; measure Lighthouse >=95
      • Created Web Worker infrastructure (lib/workers/map-calculations-worker.ts) with main thread fallback
      • Structured code to support worker-based projection and scale calculations
      • Set up Lighthouse CI workflow (.github/workflows/lighthouse.yml)
      • Configured Lighthouse assertions for performance >=95 (lighthouserc.json)
      • Added @lhci/cli and scripts for local/CI Lighthouse runs
      • Note: Web Workers use main thread fallback for now (can be migrated to true workers for further optimization)

  8. Ops & Observability Enhancements

    • Add environment schema validation and secrets management docs
    • Integrate Sentry or Vercel monitoring with error boundaries
    • Document deployment process and add performance regression alerts

Supporting Artifacts

  • PRD.md — product requirements and user journeys
  • TECH_STACK.md — technology constraints and chosen libraries
  • PROGRESS.md — authoritative roadmap (update statuses here and in shared tooling)

Update Process

  1. When a task begins, mark the appropriate checkbox and add sub-bullets if the scope grows.
  2. Cross-link PRs or tickets using inline notes (e.g., [#123]).
  3. On completion, mark tasks done and capture outcomes/metrics to inform later phases.