Architecture¶

The prototype implements a clean separation of concerns across six services, with the Pipeline containing the user-configurable layers. Visually represented in the UI via a color-coded layer bar.

graph TD
    A[🧠 ML Browser Benchmark] --> B[Router]
    B --> C[Tutorial]
    B --> D[Playground]
    C --> E[Pipeline]
    D --> E
    E --> F[Execution]
    F --> G[Benchmarking]
    G --> H[📊 Results Dashboard]

    style A fill:#6366f1,color:#fff
    style B fill:#3b82f6,color:#fff
    style C fill:#22c55e,color:#fff
    style D fill:#eab308,color:#000
    style E fill:#8b5cf6,color:#fff
    style F fill:#ef4444,color:#fff
    style G fill:#ec4899,color:#fff
    style H fill:#6366f1,color:#fff

Services¶

Pipeline layers¶

The Pipeline is the only service that contains user-configurable steps. Users build up a configuration pipeline layer by layer, ordered by dependency:

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

Cascade rules¶

When a user changes a layer, downstream layers are cleared:

Model × Runtime availability¶

Framework overhead measurement¶

Layer bar (UI)¶

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

Services are infrastructure. "Pipeline" is the only one that contains user-configurable layers.

Data flow¶

sequenceDiagram
    participant U as User
    participant R as Router
    participant P as Page Fragment
    participant E as Engine
    participant Pl as Pipeline
    participant M as ML Adapter
    participant C as Benchmarking

    U->>R: Click nav link (#playground)
    R->>P: fetch(pages/playground.html)
    P-->>R: HTML fragment
    R->>E: dynamic import(playground.js)
    E->>Pl: new PipelineState() + PipelineCanvas()
    U->>Pl: Click layers (task → model → runtime → framework → backend → inputData)
    Pl->>E: layer-ready event
    U->>E: Click "Run"
    E->>M: runBenchmark(config, nRuns)
    M->>M: adapter.load() → download model
    M->>M: adapter.infer() → cold + warm runs
    M->>C: MetricsCollector + RunRecorder.save()
    C-->>U: Result card with prediction + metrics

Module dependency graph¶

app.js
├── shell.js → utils.js
└── router.js → utils.js, shell.js

Lazy imports:
  tutorial.js   → utils.js, pipeline.js, ml-adapter.js → bench.js
  playground.js → utils.js, pipeline.js, ml-adapter.js, shell.js
  bench.js      → utils.js

Key design decisions¶

• Zero build step — all ES modules loaded natively by the browser; no bundler, no TypeScript, no framework
• Lazy loading — pages AND CDN libraries (TF.js, ONNX, etc.) loaded on-demand via dynamic import() / script injection
• Event-driven — layer-change, layer-ready, role-change CustomEvents decouple UI from state
• Advanced mode — N-runs slider, raw logs
• localStorage as DB — run records persisted as JSON array with UUIDs, CSV export available
• CSS custom properties — design system with per-layer colors, light/dark theme via data-theme attribute

Terminology guide¶

Previous architecture (first iteration)¶

What changed¶

What was also corrected¶

• Services vs Pipeline: Shell, Tutorial, Benchmarking are infrastructure services. Only the Pipeline contains user-configurable layers. The layer bar now reflects this distinction.
• ONNX re-enabled: Originally disabled due to GitHub LFS CDN issues. Now uses HuggingFace /resolve/main/ CDN URLs directly.
• Model selection restored: Originally hardcoded per runtime. Now user-interactive via MODEL_REGISTRY with runtime filtering.
• LiteRT.js added: New Google runtime (released July 2026) as a 3^rd runtime option alongside TF.js and ORT Web.
• ml5.js added: TF.js wrapper for symmetric overhead measurement across all 3 runtimes.
• Framework block added: Optional layer for measuring wrapper overhead (Direct vs Transformers.js vs MediaPipe Tasks vs ml5.js).