Visual Operations OS

Live demo: https://visual-ops-os.fly.dev

Most operations software works backwards. A manager wants to change how the company handles a late shipment, so they file a ticket, an engineer gets to it weeks later, and the manager finds out whether it worked only after it's already running in production. The thing they actually wanted to change — the behavior — was never an object they could point at. It was scattered across code, spreadsheets, and habit.

I wanted to see what happens if you flip that: make the behavior itself the thing you edit, and generate the software from it afterward.

So I built a small operations tool for a fictional freight forwarding company. A shipment from Turkey to the US runs late, some paperwork goes missing, and the team has to decide when to check for it, when to chase the shipper, and when to escalate to a person. That decision process lives on a canvas as a graph of events, decisions, and outcomes — you can open it, see exactly why a given shipment turned out the way it did, change a rule, and immediately replay that change against two years of shipment history to see what would have happened.

Only after you save the change do you see the part most tools show you first: the code underneath. A compiled execution plan, a service scaffold, a query layer. It was always just the output.

How it works

The graph is the only thing you ever write. The simulation, the diff, and the code are all generated from it, and none of it can be edited back in — patch the generated code directly and it drifts from the graph until neither one is trustworthy, which is basically how these systems always rot. So the code stays read-only, and changing behavior means going back to the graph.

Edits are kept small on purpose — move a threshold, reschedule a check, tighten a rule — and each one gets replayed against the full shipment history before you're allowed to keep it. You see the consequence before you commit to it, which most process-change tools skip entirely.

You can also just describe what you want in plain English. It's translated into the same kind of edit you'd make by hand, reaching the same small set of levers — a request phrased in words can't do anything a slider couldn't.

And the tool learns from how people actually use it. If operators keep overriding a threshold by hand, that pattern turns into a proposed graph change, tested against history before anyone's asked to accept it. If someone rejects a proposal because of a real constraint the graph didn't know about, that reason gets written back in as a rule, so the "no" isn't wasted.

What it found

Moving the documentation check from when the vessel arrives to three days earlier, and tightening the escalation threshold, cuts document holds by 44% — 305 down to 170 out of 2,000 shipments. Forecast on a year of history and graded against two months it never saw, that prediction lands within 6% of what actually happened.

It's not free. Outreach to shippers goes up by half, some of it before the shipper could possibly have the document yet, and filing the customs entry earlier means it occasionally goes out before an import filing is confirmed — a compliance rule gets breached more often too. Both costs sit on the same screen as the win.

The more interesting result is that demurrage — the fee side of a late shipment — barely moves. A few free days at the port absorb almost all of a late document's effect, and most of the actual demurrage here comes from customs exams and equipment shortages that a documentation fix can't touch. A flashier demo would have quoted a big dollar saving; the honest number is closer to a rounding error.

Try it

The live demo runs against 2,000 synthetic shipments (invented carrier names, a fictional lane) — see LIMITATIONS.md for what the numbers can and can't be taken to mean. To run it yourself:

make install    # uv venv (py3.11) + npm install
make dev        # API on :8000, Vite on :5173

or as the single container the live demo actually runs:

make image && make image-run

Deploying your own copy needs a Fly.io account (fly launch --no-deploy --copy-config once, then fly deploy --ha=false) — the config ships with no API key, no outbound calls, and one machine by design, so it costs close to nothing to host.

Reading further

docs/LEARN.md walks through the whole idea in plain language, no prior knowledge assumed, about twenty minutes. LIMITATIONS.md is the honest accounting: what's synthetic, what's mocked, what's genuinely untested, and what a result here does and doesn't prove. DATA_MODEL.md documents the data the simulation runs against. DATA_HANDLING.md covers what it would take to point this at a real company's data.

Every number in this document is generated by make verify from the committed dataset, not typed by hand, and the build fails if any of them drift from what's actually running.

License

MIT. The code is free to reuse — the numbers are specific to a synthetic dataset and aren't evidence about real freight operations, so read LIMITATIONS.md before quoting any of them.