Case study 01 / Network systems

HOPSCOTCH
Network systems

An interactive laboratory and causal debugger that keeps routing, protocol state, packet bytes, failures, and imported evidence tied to one explicit source of truth.

Launch HOPSCOTCH View source

Role: Architecture and implementation
Core model: Deterministic canonical state
Stack: React · TypeScript · Vite
Status: Active · Public source

The problem

Networks are easiest to misunderstand when the picture looks cleaner than the underlying state.

Packet bytes, routing decisions, protocol convergence, policy, transport behavior, and application failures are usually inspected in separate tools. That makes it easy for a visualization to tell a story that no longer matches the state that produced it.

HOPSCOTCH treats animation and explanation as views over canonical state rather than as sources of truth. The same model drives the Builder, packet inspection, troubleshooting, CLI operations, time travel, and causal explanations.

One model, several views

InputConfiguration or evidence
Scenarios, packet captures, measured reports, parsed configuration, and bounded public evidence enter through explicit provenance boundaries.
TruthCanonical state
Routing, forwarding, protocols, policy, packet outcomes, queues, and application dependencies are derived by deterministic engines.
TimeCausal event model
Recorded events preserve what changed, when it changed, and which earlier state or event caused the transition.
ViewPresentation only
SVG, Canvas, WebGL, Motion, and Anime.js explain state without manufacturing new network truth.

Flagship workflows

Builder

Configure and break networks

IPv4/IPv6, routing, switching, OSPF, BGP, policy, NAT, DHCP, overlays, queues, transport behavior, and deterministic application transactions share the same scenario state.

Microscope

Trace fields back to bytes

Constructed packets and captured frames expose Ethernet/IP/transport fields, checksums, lengths, and exact byte lineage rather than a detached packet summary.

Theater

Watch protocols evolve

TCP, recursive DNS, TLS 1.3, and HTTP/2 versus HTTP/3 are projected from deterministic or captured evidence while missing evidence stays visibly missing.

Journey

Follow one application request

A canonical URL request can be replayed through DNS, routing, transport, TLS, packets, policy, congestion, and injected failures without switching to a second simulator.

Evidence boundaries

A captured packet is not simulated state, and public context is not proof that traffic traversed a facility.

HOPSCOTCH labels simulated, captured, inferred, parsed-config, locally measured, edge-observed, and public-data sources separately. Imported PCAP/PCAPNG bytes remain immutable; missing stream bytes are not invented; traceroute hops do not inherit unrelated ASN, facility, or geography claims.

This provenance boundary is deliberately visible in the product because a technically polished explanation is still wrong if it quietly upgrades an inference into an observation.

Causal troubleshooting

The useful question is not only what failed? but where did truth first diverge?

Troubleshooting challenges, WHY? diagnosis, the Builder CLI, and EXPLAIN all consume the same canonical state. Repairs mutate ordinary configuration paths and verification re-runs the actual network objective.

application request
  ↓
DNS resolution        PASS
  ↓
route selection       PASS
  ↓
ACL policy            DENY
  └─ rule 30 matched source / destination
       ↓
transport start       NOT REACHED
       ↓
TLS / HTTP            NOT REACHED

Engineering evidence

v9canonical scenario schema

A–Limplemented product tracks

4browser and render paths

0invented missing capture bytes

npm run check exercises Builder, Journey, capture, measurement, navigation, native-companion, CLI, troubleshooting, and explanation contracts before the production build. Production profiling then checks versioned bundle, DOM, heap, and semantic budgets alongside real PCAP/PCAPNG replay across Chrome default, disabled-WebGL, SwiftShader, and Firefox semantic paths.

Scope without pretending

Broad coverage only helps if the limits remain explicit.

The Builder models substantial routing, switching, transport, policy, queueing, and overlay behavior, but it is not a vendor-image emulator. Its CLI is intentionally vendor-neutral, public Internet context stays provenance-bounded, and unsupported behavior is treated as unsupported rather than approximated invisibly.

That constraint is what makes the breadth defensible: each additional workspace has to consume existing canonical truth instead of creating a second, easier-to-demo version of the network.

What this project demonstrates

The project is less about drawing packets than about preserving causality across abstraction levels.

HOPSCOTCH combines network-domain modeling with frontend systems work, deterministic state architecture, evidence handling, testing, performance budgets, accessibility, and production deployment.

The strongest result is not the number of supported protocols; it is that simulation, captured evidence, measurement, troubleshooting, CLI operations, and explanation remain separate where they should be separate and share state where they should not drift.

Next project

Measure the path,
not just the peak.

Read Network Diagnostics case study

HOPSCOTCHNetwork systems