Skip to content

New Architecture — Rename Refactoring Plan

Three renames combined into one cohesive refactor that corrects the terminology across the entire prototype.


Motivation

The original naming was misleading:

Problem Example
"Block" is too generic BlockRegistry, BlockCanvas — these define pipeline configuration layers, not generic blocks
"Block Runtime" is confusing Sounds like an ML runtime, but it's the configuration pipeline
"Dataset" implies a collection It's a single input for inference, not a dataset
"Shell" is vague It's a router with role/theme management
Everything called "layer" Services (Router, Tutorial, Benchmarking) and configuration steps were both called "layers" in the layer bar

Corrected mental model

Services (infrastructure)

These provide functionality — they are NOT configuration layers:

Service Responsibility Files
Router SPA routing, role/theme management shell.js, router.js, app.js
Tutorial 7-step guided walkthrough tutorial.js
Playground Free-form config + benchmarking UI playground.js
Pipeline Configuration layers (what the user configures) pipeline.js (renamed from block-runtime.js)
Execution Adapters that run inference ml-adapter.js
Benchmarking Metrics collection, result storage bench.js

Pipeline layers (what the user configures)

These are the configuration layers in the pipeline, ordered by dependency:

Task → Model → Runtime → Framework → Backend → Input Data → Run

Layer What the user picks Constrains
Task Image Classification (only enabled) Available models
Model MobileNet v2, SqueezeNet 1.0, EfficientNet-Lite0 Available runtimes
Runtime ORT Web, TF.js, LiteRT.js Available frameworks + backends
Framework "Direct" or wrapper (Transformers.js, MediaPipe Tasks, ml5.js) Backend options
Backend WASM, WebGPU, WebGL, CPU Execution hardware
Input Data Sample image or upload Nothing — independent

Rename table

Code renames

Current New Scope
block-runtime.js pipeline.js File rename
BlockRegistry LayerRegistry Exported const
BlockCanvas PipelineCanvas Exported class
_activeBlock _activeLayer Instance property
block-change event layer-change CustomEvent name
block-ready event layer-ready CustomEvent name
dataset (config field) inputData DataFlowGraph field
_renderDatasetConfig() _renderInputDataConfig() Method name

CSS renames

Current New
.block-card .layer-card
.block-icon .layer-icon
.block-label .layer-label
.block-value .layer-value
.block-config-panel .layer-config-panel
.block-panel .layer-panel
.active-block .active-layer
#block-val-${type} #layer-val-${type}
#block-config-panel #layer-config-panel
--color-block-task --color-layer-task
--color-block-dataset --color-layer-inputdata
--color-block-model --color-layer-model
--color-block-runtime --color-layer-runtime
--color-block-backend --color-layer-backend
--color-block-framework --color-layer-framework
--layer-blockruntime --layer-pipeline
.layer-blockruntime .layer-pipeline

UI text renames

Current New
"Shell / Router" (layer bar) "Router"
"Block Runtime" (layer bar) "Pipeline"
"Block Runtime Layer" (architecture) "Pipeline Layer"
"Dataset" (layer label) "Input Data"
"Click a block" (playground) "Click a layer"

What NOT to rename

Item Why keep it
--layer-shell CSS variable Internal CSS, not user-facing. Touching 15+ lines across 4 files for no visible benefit
shell.js, router.js, app.js Separate service files, not part of the pipeline system
DataFlowGraph Good name — represents the state graph between layers
MODEL_REGISTRY, FRAMEWORK_REGISTRY, COMPAT Data structures, not part of the block/layer naming

Files affected (14 files)

Prototype code (5 files)

File Changes Lines
js/block-runtime.jsjs/pipeline.js File rename + ~40 internal renames ~85
js/playground.js Import path + event names + config field ~8
js/tutorial.js Import paths + config field ~8
js/ml-adapter.js Config field in JSDoc + runtime ~4
css/playground.css CSS class renames ~15
css/main.css CSS variable + class renames ~12

HTML (3 files)

File Changes
index.html Layer bar text + CSS classes
pages/playground.html CSS classes + user strings
pages/home.html CSS classes + user strings

Documentation (5 files)

File Changes
docs/prototype/index.md Layer name + file references
docs/prototype/architecture.md Full rewrite of layer diagram + table
docs/prototype/implementation-plan.md BlockRegistry → LayerRegistry references
docs/zensical.toml Add new-architecture.md to sidebar

Execution order

Step 1: Create new architecture doc

  • Write docs/prototype/new-architecture.md
  • Add to docs/zensical.toml sidebar

Step 2: Rename file

  • git mv prototype/js/block-runtime.js prototype/js/pipeline.js

Step 3: Internal renames in pipeline.js

  • All BlockRegistry → LayerRegistry
  • All BlockCanvas → PipelineCanvas
  • All _activeBlock → _activeLayer
  • All CSS class strings block-* → layer-*
  • All DOM IDs block-val-* → layer-val-*
  • All events block-change/block-ready → layer-change/layer-ready
  • All CSS variables --color-block-* → --color-layer-*
  • dataset → inputData in DataFlowGraph
  • _renderDatasetConfig → _renderInputDataConfig

Step 4: Update imports

  • playground.js: import path + names + events + config field
  • tutorial.js: import paths + config field
  • ml-adapter.js: config field

Step 5: Update CSS

  • playground.css: block-* → layer-*
  • main.css: --color-block-* → --color-layer-*, --layer-blockruntime → --layer-pipeline

Step 6: Update HTML

  • index.html: layer bar text + CSS classes
  • pages/playground.html: CSS classes + user strings
  • pages/home.html: CSS classes + user strings

Step 7: Update existing docs

  • architecture.md: layer diagram + table
  • index.md: layer references
  • implementation-plan.md: references

Pipeline layer details

LayerRegistry entries

Each layer has: label, icon, color, description, and optional static options.

export const LayerRegistry = new Map([
  ["task", {
    label: "Task",
    icon: "🎯",
    color: "var(--color-layer-task)",
    description: "Select the ML task. Currently only Image Classification is enabled.",
    options: [...]
  }],
  ["model", {
    label: "Model",
    icon: "🧠",
    color: "var(--color-layer-model)",
    description: "Choose a pre-trained model.",
    options: null // dynamic from MODEL_REGISTRY
  }],
  ["runtime", {
    label: "Runtime",
    icon: "⚙️",
    color: "var(--color-layer-runtime)",
    description: "Select the inference engine.",
    options: [tfjs, onnx, litert, transformers, mediapipe]
  }],
  ["framework", {
    label: "Framework",
    icon: "📦",
    color: "var(--color-layer-framework)",
    description: "Optional wrapper around the runtime.",
    options: null // dynamic from FRAMEWORK_REGISTRY
  }],
  ["backend", {
    label: "Backend",
    icon: "🖥️",
    color: "var(--color-layer-backend)",
    description: "Hardware execution backend.",
    options: BACKEND_OPTIONS
  }],
  ["inputData", {
    label: "Input Data",
    icon: "🗃️",
    color: "var(--color-layer-inputdata)",
    description: "Upload an image or choose a sample.",
    options: null // dynamic: upload + sample grid
  }],
]);

PipelineState (renamed DataFlowGraph)

export class PipelineState {
  constructor() {
    this._config = {
      task: null,
      model: null,
      runtime: null,
      framework: null,
      backend: null,
      inputData: null
    };
  }

  set(layerType, value) {
    if (this._config[layerType] === value) return;
    this._config[layerType] = value;

    // Cascade: clear downstream layers
    if (layerType === "task") {
      Object.assign(this._config, {
        model: null, runtime: null, framework: null,
        backend: null, inputData: null
      });
    }
    if (layerType === "model") {
      this._config.runtime = null;
      this._config.framework = null;
      this._config.backend = null;
    }
    if (layerType === "runtime") {
      this._config.framework = null;
      this._config.backend = null;
    }
    if (layerType === "framework") {
      this._config.backend = null;
    }

    document.dispatchEvent(
      new CustomEvent("layer-change", { detail: { ...this._config } })
    );
    if (this.isReady()) {
      document.dispatchEvent(
        new CustomEvent("layer-ready", { detail: { ...this._config } })
      );
    }
  }
}

Layer bar (UI)

┌────────┬────────────┬─────────────┬──────────┬───────────┬──────────────┐
│ Router │ Tutorial   │ Playground  │ Pipeline │ Execution │ Benchmarking │
│ (Blue) │ (Green)    │ (Yellow)    │ (Purple) │ (Red)     │ (Pink)       │
└────────┴────────────┴─────────────┴──────────┴───────────┴──────────────┘

Services above are infrastructure. "Pipeline" is the only layer that contains user-configurable steps.