Rbanh/schemeta
1
0
Fork 0
Code Issues 11 Pull Requests Actions 1 Packages Projects Releases Wiki Activity
d029e480d0
schemeta/docs/phase8-react-elk-refactor-plan.md
Rbanh 85dc9a1ac2
Some checks are pending
CI / test (push) Waiting to run
Details
Add Phase 8 React+ELK refactor execution plan
2026-02-19 19:06:22 -05:00

4.3 KiB
Raw Blame History

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.