Skip to content
Reef

Architecture

Reef is split by job, not by ceremony. One runtime handles the public API and workflow coordination, a Go engine handles matching, the simulator creates repeatable activity, and Postgres keeps the facts needed for audit and replay.

Services

Section titled “Services”
Service Language Responsibility
services/platform-runtime Kotlin External API boundary (/api/v1), command handling, workflow orchestration, persistence, read models, admin surface
services/matching-engine Go Hidden order book, matching rules, execution/order events
services/simulator Go Deterministic scenario execution, seeded participant/bot traffic, replay checks, stress/load tooling
services/stock-data Kotlin Seed-time-only external stock reference snapshots for game/simulation creation
apps/docs-site Astro This site
contracts/proto Protobuf Versioned cross-language contracts (order execution today)
packages/bot-sdk TypeScript Public Bot SDK authoring surface — see Bot Arena
packages/scenario-definitions — Reusable scenario/simulation input definitions

Deployment Shape (Current)

Section titled “Deployment Shape (Current)”

Current local development can still run in a deliberately simple shape:

Kotlin platform runtime  (one process)
  -> Postgres            (one instance)
  -> Go matching engine  (one process)

The promoted high-throughput venue-core path moves the hot lane away from synchronous database writes:

API durable publish ack
  -> matching-engine direct partition consume
  -> durable VenueEventBatch
  -> command offset commit
  -> canonical Postgres materialization
  -> asynchronous projection/replay verification

Redpanda/Kafka-compatible direct-stream ingestion plus venue-event materialization is the current 10k accepted/direct-acked/materialized baseline. Projection and read-model freshness are measured separately so UI/control-room lag does not redefine venue-core acceptance.

Bounded Contexts

Section titled “Bounded Contexts”

Reef uses explicit business contexts so the code keeps its shape as features grow. Most contexts start as modules inside the Kotlin runtime instead of separate deployed services:

  • reference-data
  • account-and-bot-ledger
  • orders-and-execution
  • market-data
  • trade-processing
  • post-trade-workflow
  • clearing-and-netting
  • settlement
  • exceptions-and-operations
  • simulation-control
  • audit-and-analytics

Orders-and-execution, command status, market-data/own-order reads, durable venue event materialization, Bot SDK live-read wiring, and the first settlement evidence/finality slice have meaningful implementation today. The broader post-trade and operator UI surfaces remain architecture targets. See Current Status for the built/planned split.

Core Rules

Section titled “Core Rules”
  • Simulation and bot-arena actors submit through the same /api/v1 command paths as manual users. No direct table writes.
  • Domain/workflow logic stays framework-light, outside HTTP adapters.
  • Every meaningful state transition is evented for audit, replay, and timeline reconstruction.
  • Canonical venue facts (durable event batches, command outcomes) stay separate from rebuildable operational projections.
  • Matching-sensitive submit/cancel/modify commands for the same venue session + instrument stay on one deterministic processing lane.
  • Settlement consumes canonical trade facts downstream and writes append-only post-trade evidence; it must not mutate matching history.

Learn More

Section titled “Learn More”
  • docs/steering/architecture.md — full architecture steering
  • docs/steering/external-api-boundary.md — API boundary steering
  • docs/DATA_DOMAIN_SCHEMA_BLUEPRINT.md — schema blueprint (see Schema on this site)
  • docs/ARCHITECTURE_INFRASTRUCTURE_DIAGRAMS.md — infrastructure diagrams