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 |
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.js → js/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.