Prayog

A simulated stock exchange and bot arena. Simulated traders create the market; people trade on it by hand in the browser or with their own bots, against a real matching engine with a journal and deterministic replay.

• Visit the market

  Watch the live order book and trades, sign in, place and cancel orders.

  Using the market

• Build a bot

  Get a token, read the feeds, send orders with the Python SDK.

  Bot builder guide · API

• Run & debug

  Start the stack, check its health, break it on purpose, find out why.

  Runbook

• Learn how it works

  Session notes, decisions and 15 interactive explainers with simulators.

  Learnings · Interactive pages

How it fits together

Click any box to read the page that explains it.

Learning path

The project in the order it was built. Each step has session notes (concepts to tick off, explain-back answers) and, where one exists, an interactive page with a simulator.

• 1 · S1 Repo skeleton

  Maven modules, wrappers, lock files, CI.

  Notes · ADR 0001

• 2 · S3–S4 Contracts and order book

  Integer money, price-time priority, property tests.

  Notes · Modern Java

• 3 · S5 Market, cancel, modify

  Commands, event sourcing, queue priority.

  Notes · ADR 0004

• 4 · S6 Bands, sessions, STP

  Price bands, halts, self-trade prevention, kill switch.

  Notes · Functional overview

• 5 · S7 Sequencer pipeline

  Single writer, back-pressure, simulated clock.

  Notes · Ring buffer · Memory model · GC and JIT

• 6 · S8 Journal and replay

  fsync, group commit, torn writes, SBE, checksums.

  Notes · Journaling · SBE · Off-heap · FIX

• 7 · S2 Local infrastructure

  Compose, Kafka KRaft, Keycloak, Traefik, secrets.

  Notes · Compose and Traefik · Kafka · OAuth2 and OIDC

• 8 · S10–S13 The live market

  Gateway, feeds and gaps, SDK, market making, end-to-end checks.

  Notes · Market data feeds · Market making · Technical overview

• 9 · Step 1.5 Admin, workspace, strategies

  Admin console, draggable workspace, six browser strategies with risk limits.

  Notes · ADR 0012

• 10 · S15 Kafka publisher

  Outbox pattern: tail the durable log, checkpoint, at-least-once.

  Notes · Kafka · ADR 0013

• 11 · S16–S17 Post-trade and leaderboard

  Idempotent consumer, average-cost P&L, zero-sum checks, Redis sorted sets.

  Notes · ADR 0015

• 12 · S18–S19 Terminal, blotter, ops page

  Server-backed panels, official P&L, a whole simulated day from the browser.

  Notes · ADR 0017

• 13 · Step 2 Recovery hardening

  Duplicate client order IDs, rule versions, snapshots, journal archiving.

  IDs · Snapshots · Archiving

• 14 · S9 Benchmarks, allocation and GC

  JMH, HdrHistogram, coordinated omission, JFR, GC settings, a boxing-free index.

  S9 · Allocation · Numbers

• 15 · S14 Realism checks

  Do simulated prices look like a real market? Spreads, tails, clustering.

  Notes · Report

• 16 · S20–S22 Rules, observability, docs

  Cucumber scenarios, Prometheus and Grafana, failure modes, the demo.

  S20 · S21 · S22 · Failure modes

Background: industry context (exchange vs trading firm, what production engines do differently). Every decision: Decisions. What's done and next: Progress.

Run it locally

You need Java 21, Docker (Desktop with at least 4 GB of memory), uv, and Node 22 with pnpm 10 (corepack).

make env    # once: creates .env with random local secrets (git-ignored)
make up     # builds and starts everything; add PROFILES="infra app obs" for Prometheus and Grafana
make smoke  # quick checks
make e2e    # the live market is correct: feeds, liquidity, bots, Kafka outage, post-trade, journal replay
make down   # stops it (data is kept); `make reset` also deletes the data volumes
make test   # build and test everything

Address	What
http://app.prayog.localhost	The live market: watch without signing in; sign in as trader1 to trade, ops1 for the ops page
http://api.prayog.localhost	The exchange and post-trade API for bots (reference)
http://grafana.prayog.localhost	Dashboards (profile obs)
http://auth.prayog.localhost	Keycloak; admin console at /admin (credentials in .env)
http://traefik.prayog.localhost/dashboard/	Traefik routes

Step-by-step checks, failure drills and debugging help are in the runbook; start with Start and stop.