From 85dc9a1ac2e7f10cff0761bc9f1b47fb15379a2d Mon Sep 17 00:00:00 2001 From: Rbanh Date: Thu, 19 Feb 2026 19:06:22 -0500 Subject: [PATCH] Add Phase 8 React+ELK refactor execution plan --- docs/phase8-react-elk-refactor-plan.md | 95 ++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/phase8-react-elk-refactor-plan.md diff --git a/docs/phase8-react-elk-refactor-plan.md b/docs/phase8-react-elk-refactor-plan.md new file mode 100644 index 0000000..d5ee185 --- /dev/null +++ b/docs/phase8-react-elk-refactor-plan.md @@ -0,0 +1,95 @@ +# Phase 8 Execution Plan: React + ELK Core Refactor + +## Objective +Deliver the largest Schemeta refactor to date: migrate the frontend to a robust React architecture, replace fragile placement behavior with ELK-driven layout, harden routing/labeling readability, and establish production-grade quality gates. + +This phase is OSS-only and budget-neutral. + +## Non-Goals +- No paid/proprietary graph SDKs. +- No API contract break for `/compile`, `/analyze`, `/layout/auto`, `/layout/tidy`. +- No regression of current JSON schema compatibility. + +## Architecture Target +- Frontend: React + TypeScript + Vite. +- Interaction layer: React Flow primitives for node/selection/viewport interactions. +- Layout: `elkjs` as primary placement engine. +- Routing: Schemeta incremental router with deterministic tie-net fallback. +- State: deterministic centralized action pipeline (undo/redo transaction model). + +## Work Breakdown (Milestone #7) +- #37 P8-01 Frontend architecture migration to React + TS + Vite +- #38 P8-02 State model refactor with deterministic action pipeline +- #39 P8-03 Canvas subsystem rewrite with React Flow contracts +- #40 P8-04 ELK integration and constraints mapping +- #41 P8-05 Routing engine revamp (incremental reroute) +- #42 P8-06 Deterministic label placement and collision avoidance +- #43 P8-07 Symbol readability and pin-density standards +- #44 P8-08 JSON editor power-tool upgrade (schema-aware + diff apply) +- #45 P8-09 QA hardening (visual/readability gates) +- #46 P8-10 Cutover, migration, rollback + +## Delivery Sequence (Critical Path) +1. Foundation + - Complete #37 (React app shell) and #38 (state architecture). + - Exit criteria: feature-parity shell + deterministic action store. +2. Interaction rewrite + - Complete #39 on top of #37/#38. + - Exit criteria: drag/multi-select/pan/zoom/edit stable and undoable. +3. Layout core + - Complete #40 with adapter boundaries for constraints. + - Exit criteria: ELK-based autolayout deterministic on fixtures. +4. Routing core + - Complete #41 with local reroute and deterministic fallback behavior. + - Exit criteria: moved components reroute only affected nets. +5. Readability system + - Complete #42 + #43 for labels/pin-density constraints. + - Exit criteria: baseline fixtures have no label/pin overlap failures. +6. Power-user JSON workflow + - Complete #44 for schema-aware editing and safe apply previews. +7. Quality gates + ship safety + - Complete #45 + #46; run cutover checklist. + +## Technical Design Rules +- Determinism first: all ordered traversals sort by stable keys. +- Incremental operations default: no full relayout on drag/edit unless explicit. +- Readability constraints are hard constraints, not best-effort hints. +- Feature flags for risky changes during dual-run period. + +## Quality Gates (Phase 8 Additions) +In addition to existing crossings/overlaps/detour metrics: +- Label collisions must be 0 in baseline fixtures. +- Pin text collisions must be 0 in baseline fixtures. +- Component overlap must remain 0. +- Drag action must not move untouched components. +- Snapshot test matrix across viewport sizes and render modes. + +## Risks and Mitigation +- Risk: React migration stalls on parity gaps. + - Mitigation: keep legacy UI in dual-run until parity checklist passes. +- Risk: ELK mapping mismatch with custom constraints. + - Mitigation: fallback mapping with explicit unsupported-constraint diagnostics. +- Risk: routing regressions after layout changes. + - Mitigation: incremental router tests and stress fixtures in CI. +- Risk: test flakiness due to persisted state. + - Mitigation: force deterministic test bootstrapping and storage resets. + +## Performance Budgets +- Compile latency p95 (sample): <= 180ms local. +- Drag-to-reroute p95 (affected nets only): <= 120ms local. +- Auto layout p95 (medium fixture): <= 600ms local. + +## Release Readiness Checklist +- All milestone issues closed. +- CI green for unit + UI + readability metrics. +- Dual-run comparison report attached. +- Rollback validated with documented steps. +- Release notes include migration caveats and known limitations. + +## Definition of Done +Phase 8 is done only when: +- React UI is default and legacy path can be disabled safely. +- ELK placement is primary in production path. +- Readability gates are enforced in CI. +- Drag/edit interactions are deterministic and locally incremental. +- JSON/AI workflows are schema-aware and operator-safe.