traffic-sim
A Go traffic simulation engine for the question every city argues about: which upgrade actually fixes this intersection? Simulation, not vibes.
Why this exists
Traffic debates run on intuition: somebody wants a new lane, somebody wants a roundabout, everybody has a commute that proves their point. The repo's stated position is that questions like "which upgrade actually fixes this intersection?" deserve simulation, not vibes. So traffic-sim models real road networks — imported from OpenStreetMap, down to the stop signs — and lets AI driving policies and live human drivers share the same simulated roads, producing congestion metrics concrete enough to rank infrastructure alternatives against each other. It powers a MATH vs. VIBES episode, but it's built standalone, with a roadmap that runs to replaying days of real traffic to evaluate signal-timing changes.
How it works
An authoritative engine, written in Go, owns the world state over a lane-level road graph and publishes it over NATS. Controllers — AI policies or human drivers, in any language — subscribe to that state and emit driving intents back as events. A TypeScript + MapLibre client (no framework) renders live vehicles and congestion heatmaps off the same streams. JetStream provides durable event logs, which is what makes deterministic replay possible: rerun a scenario with a fixed seed and you get the same world. Scenarios — network plus demand plus control config — are first-class, versioned directories, so two proposed upgrades can be diffed like code and ranked on metrics instead of argued about.
What's real today
The README pins status at M11 — scenario directories. Built and
tested so far: the Go simulation kernel, the NATS message contract, an external
default driver, OSM/netconvert network import, junction right-of-way, fixed-time
signals, a runtime demand director, live MapLibre visualization, and scenario
loading per ADR-0012. Each piece implements one of the twelve architecture decision
records kept in docs/kb/decisions/ — the design is on paper before it's
in code. The public face is phantomjam.com, an
atlas of the imported city networks (LA, SF, Miami, Atlanta, Houston, Dallas,
Chicago), with in-browser replays of simulation experiments landing as they're
baked. A live shared sim is staged in deploy/, gated on two explicit
go-live preconditions in ADR-0020 — broker auth and an engine health endpoint —
rather than on someone feeling good about it.
Run it yourself
Two test suites, one for the engine and one for the viz:
cd engine && go test ./... cd viz && pnpm install && pnpm test
The live demo runs a real I-280 network with the external default driver and
browser viz, and scenario directories can be validated, hashed, and swept with
explicit seeds. The network data itself isn't checked in — per ADR-0009 the repo
stores the recipe, not the file, and the bootstrap recipe lives in
contracts/network-format-v1.md. Start with
docs/VISION.md, the founding document, then the ADRs.
The full README, verbatim
traffic-sim
An open-source traffic simulation engine built on NATS. Models real road networks (including OpenStreetMap imports), hosts heterogeneous vehicle controllers — AI policies and live human drivers alike — and produces decision-grade congestion metrics for comparing infrastructure alternatives.
Status: M11 — scenario directories. Simulation kernel (Go), NATS message
contract, external default driver, OSM/netconvert network import, junction
right-of-way, fixed-time signals, runtime demand director, live MapLibre viz,
and ADR-0012 scenario loading are built and tested — see
docs/kb/decisions/ for the 12 ADRs they implement.
Why
Traffic questions like "which upgrade actually fixes this intersection?" deserve simulation, not vibes. This project powers a math-vs-vibes episode, but is built standalone to scale well beyond it — up to replaying days of real traffic to evaluate signal-timing changes.
Design in One Paragraph
An authoritative engine (Go) owns world state over a lane-level road graph and publishes it via NATS; controllers (AI or human, any language) subscribe to state and emit driving intents as events; visualization (TypeScript + MapLibre) renders live vehicles and congestion heatmaps from the same streams. JetStream gives durable event logs for deterministic replay; scenarios (network + demand + control config) are first-class and diffable so alternatives can be ranked on metrics.
See It
phantomjam.com is the public face of this engine:
an atlas of the imported city networks (LA, SF, Miami, Atlanta, Houston,
Dallas, Chicago — down to the stop signs) and, as they land, in-browser
replays of the simulation experiments, baked to static data and served from
the edge. A live shared sim (app.phantomjam.com, deployment in deploy/)
follows once ADR-0020's two go-live preconditions (ws-plane broker auth AND
engine /healthz) land.
Repo Map
| Path | What |
|---|---|
docs/VISION.md |
Founding document — read this first |
docs/kb/ |
Knowledge base: research, articles, decision records |
AGENTS.md |
Rules for humans and agents working here |
engine/ |
Go simulation kernel + NATS contract + tools (simrun, serve, netimport, scenario, default-driver, demand-director) |
contracts/ |
AsyncAPI message contract + network file format v1 |
viz/ |
MapLibre realtime client (TypeScript, pnpm, no framework) |
analysis/ngsim/ |
NGSIM x-t field tooling + I-80 wave validation |
deploy/ |
Public-deployment artifacts: Dockerfile, demos registry, GKE manifests (see deploy/README.md — gated on ADR-0020 preconditions) |
prototypes/ |
Throwaway engine-fork demos (pre-implementation) |
Getting Started
Run the test suites:
cd engine && go test ./...
cd viz && pnpm install && pnpm test
Run the live demo (real I-280 network, external default driver, browser viz):
cd engine && go run ./cmd/serve -netfile ../data/networks/i280-woodside/i280.json \
-run demo -ws 127.0.0.1:8443 -geojson ../viz/public/network.geojson
cd viz && pnpm dev # open http://localhost:5173/?run=demo&ws=ws://127.0.0.1:8443
Or run from an ADR-0012 scenario directory (manifest + demand parts; explicit
-seed/-ticks override the manifest for sweeps):
cd engine && go run ./cmd/scenario validate path/to/scenario && go run ./cmd/scenario hash path/to/scenario
go run ./cmd/simrun -scenario path/to/scenario -seed 2
data/networks/ is git-ignored per ADR-0009's recipe-not-file posture; the
bootstrap recipe to regenerate it is in contracts/network-format-v1.md.
Repo post · repo created 2026-07-27, posted 2026-08-06. Twelve ADRs in, the loudest commute opinion on the internet remains unfalsifiable. We're working on it.