Skip to content

v1-stack-decision.md

Latest commit

 

History

History
112 lines (76 loc) · 3.71 KB

v1-stack-decision.md

File metadata and controls

112 lines (76 loc) · 3.71 KB

V1 Stack Decision

Status: accepted for v1.0.0

Date: 2026-06-05

Context

The current visualizer already proves the important product loop:

repository -> graph JSON -> self-contained interactive HTML map

Its largest pre-v1 problems are packaging, installability, safety contracts, testability, and release trust. They are not evidence that the product needs a different application stack.

A full rewrite would recreate already-working scanner, renderer, graph, interaction, responsive-layout, and authority-boundary behavior while enlarging the regression surface.

Decision

V1 will evolve the current implementation rather than rewrite it.

Retain:

  • Node.js and ESM for scanner and renderer execution.
  • Node standard-library-only installed runtime.
  • Graph JSON as the explicit scanner/renderer boundary.
  • Static self-contained HTML as the primary artifact.
  • Inline SVG for deterministic hierarchy and reference visualization.
  • Vanilla browser JavaScript for map interaction.

Change:

  • Extract testable scanner and renderer modules behind the existing artifact contracts.
  • Package one canonical runtime under the installable skill directory.
  • Prefer authored plain CSS and remove the Tailwind build dependency unless implementation evidence shows a material reason to retain it.
  • Manage large graphs with scoped views, budgets, filtering, and graceful limits before evaluating Canvas or WebGL.

Defer:

  • React, Vue, Svelte, or another browser application framework.
  • Canvas or WebGL rendering.
  • A persistent web application or required local server.
  • Artifact-contract changes made only to ease internal refactoring.

Rationale

Node.js

Node is portable across the intended coding-agent environments, naturally fits filesystem and JSON work, and supports a dependency-light installed runtime.

Static self-contained HTML

The single-file map is portable, inspectable, archiveable, and usable without a server or runtime dependency installation. It matches the generated-snapshot authority model.

SVG

SVG provides crisp labels, deterministic layouts, native interaction targets, and inspectable output. Focused and scoped views are a better first response to large-repository pressure than replacing the renderer without measurements.

Vanilla browser JavaScript

The current browser behavior does not yet justify a framework runtime. Internal module boundaries and tests should address maintainability before adding a framework abstraction.

Plain CSS

The renderer has one specialized visual language rather than a broad component system. Plain authored CSS removes a development dependency and generated-asset drift while preserving the self-contained artifact.

Consequences

Positive:

  • V1 work targets the actual release blockers.
  • Existing behavior remains available to validate during refactoring.
  • Installed runtime stays lightweight and inspectable.
  • Artifact compatibility can remain stable while internals improve.

Tradeoffs:

  • Vanilla browser JavaScript still requires disciplined module boundaries.
  • SVG needs explicit graph-size budgets and scoped rendering.
  • Removing Tailwind requires carefully preserving the current visual language.
  • The modularization must avoid creating duplicate canonical runtime copies.

Reconsideration triggers

Revisit this decision only when evidence shows one or more of:

  • Representative scoped SVG views remain too slow or memory-heavy.
  • Browser state complexity repeatedly causes regressions despite modularization and tests.
  • Multiple maintainers cannot safely evolve the renderer without a framework.
  • The product requirements change from a generated static artifact to a persistent application.

Until then, stack replacement is not part of the v1 path.