---
title: "How the simulator works"
description: "The Kafka Simulator runs a deterministic, seeded engine in your browser. What a frame is, what the golden traces lock in, and what replayable means."
url: https://monedula.dev/flock/docs/kafka-simulator/concepts/how-the-simulator-works/
---
The simulator is an engine, written in TypeScript, that holds a Kafka cluster's state and applies Kafka's rules to it. It runs in the page; no server runs your cluster.

## State, actions and events

The engine keeps the whole cluster as one state: brokers, topics and partitions with their leaders, replicas, in-sync replicas, high watermarks and log end offsets, producers, consumer groups and their offsets, and the controllers. You change it with actions: produce a record, kill a broker, change a config. An action updates the state and schedules events, such as a replica fetch, a leader election or a consumer poll, at a point in simulated time. Moving the clock forward runs the events that are due, and each one may schedule more.

Time in the simulator is simulated time. The timeline, the timing settings and the times in the Inspector all count it, and it advances only when the playground steps the engine.

Each event records what caused it. That chain is what the Inspector's **caused by** list walks, and what the **Why** tab uses to explain an error.

## Deterministic and seeded

The only randomness in the engine comes from a pseudo-random generator seeded with a text seed. The same seed and the same actions always produce the same events, in the same order, in every browser. Each scripted scenario has its own seed, and in free play the seed is one of the settings in the **timing & seed · free play** section, on the **Engine** tab of the cluster's Inspector view.

## Frames

A frame is the state at one moment. A scripted scenario is a starting cluster, a script of timed actions and the moments to capture; each captured frame carries a time, a label and usually a teaching note, which the **Steps** tab shows. In a sandbox, each action you take and each step of the clock adds a frame.

Moving the playhead shows a recorded frame. It never runs the engine backwards: stepping back in a sandbox restores the frame that was recorded, and acting from there replaces what came after it.

## Golden traces

We store the frames of every scripted scenario with the site, one file per scenario: its golden trace. A test reruns each scenario through the engine and requires the result to match its file byte for byte. A change to the engine that would alter what any scenario shows fails that test, so a scenario only changes when we record its new trace on purpose. That is how the notes in the **Steps** tab stay true to the cluster drawn next to them.

## What replayable means

A sandbox is its starting cluster plus the actions you took, each with the time you took it. The playground does not save the state itself: to rebuild any point of a session, it replays those actions through the engine from the start.

That is what makes a [shared link](/flock/docs/kafka-simulator/how-to/share-by-url/) work: it carries the cluster shape and the action log, and the playground that opens it replays them. What it cannot carry is a frame that was only a step of the clock between two actions; a reloaded session has one frame per action.


The format of the action log in the link is public: the [playground URL format](/flock/docs/kafka-simulator/reference/url-format/) specifies it for tools that generate links.


## Related

- [Fidelity](/flock/docs/kafka-simulator/concepts/fidelity/) says what the model covers and what it leaves out.
- [Run your first scenario](/flock/docs/kafka-simulator/tutorials/run-your-first-scenario/) shows frames, causes and the **Why** tab at work.