No description
  • Java 89.1%
  • Svelte 8.2%
  • TypeScript 1.3%
  • JavaScript 0.8%
  • Shell 0.4%
  • Other 0.2%
Find a file
2026-11-05 22:24:55 +01:00
backend generator for manifest 2026-11-05 22:24:55 +01:00
benchmarks initial commit 2026-11-05 20:11:07 +01:00
contracts/sample-providers generator for manifest 2026-11-05 22:24:55 +01:00
deploy open acocount at first order 2026-11-05 21:08:15 +01:00
docs generator for manifest 2026-11-05 22:24:55 +01:00
fixtures/runs initial commit 2026-11-05 20:11:07 +01:00
frontend generator for manifest 2026-11-05 22:24:55 +01:00
scenarios initial commit 2026-11-05 20:11:07 +01:00
scripts open acocount at first order 2026-11-05 21:08:15 +01:00
.gitignore open acocount at first order 2026-11-05 21:08:15 +01:00
compose.yaml open acocount at first order 2026-11-05 21:08:15 +01:00
README.md open acocount at first order 2026-11-05 21:08:15 +01:00

SimTrader — trading platform emulator

A stateful, provider-adaptable trading API emulator for repeatable integration tests. Upload a local OpenAPI contract, map its operations to a shared financial model, configure accounts and market conditions in a run fixture, and point your integration client at the emulated provider API. Orders are processed asynchronously with partial fills, reservations, T+N settlement, cross-currency settlement with booked FX conversions, exact decimal accounting and a controllable business clock. Every financial effect is traceable, and recorded runs can be replayed with identical outcomes.

Everything runs locally: the application, PostgreSQL and the tests never contact external services. The two bundled provider contracts (contracts/sample-providers/alpha, .../beta) are synthetic, authored for this project; passing them demonstrates conformance to those contracts, not compatibility with any live provider.

Quick start (from source)

Prerequisites: Git, Docker with Compose v2, JDK 21, Maven 3.9, Node 22+. The Docker build and Compose use only local images, so pull the two base images once:

docker pull postgres:17-alpine && docker pull eclipse-temurin:21-jre-alpine
git clone https://scm.hanodrim.com/dusan.bratusa/SimTrader.git && cd SimTrader
scripts/build.sh
SIMTRADER_ADMIN_PASSWORD=change-me docker compose up -d

scripts/build.sh builds the admin UI, the backend and the image simtrader:dev. The first build on a new computer downloads the Maven and npm dependencies (roughly 100–250 MB and 100 MB) and the base images (about 700 MB unpacked). Set SIMTRADER_BIND=0.0.0.0 to reach the app from other machines (plain HTTP: trusted networks only, or put a TLS proxy in front).

Open http://localhost:8080/admin/ (user admin). To populate a demo instance with both synthetic providers:

SIMTRADER_ADMIN_PASSWORD=change-me node scripts/demo.mjs

Install package (no build tools on the target)

scripts/package.sh

writes dist/simtrader-<version>-<os>-<arch>.tar.gz (about 240 MB) with the app and PostgreSQL images, a runtime compose.yaml (database not published, restart policies), INSTALL.md and the samples. Copy it to the other computer, unpack it and follow its INSTALL.md (docker load, then docker compose up -d). The target needs only Docker, and the same CPU architecture as the build machine (an arm64 Mac builds arm64 images); for another architecture build from source there.

Without Docker for the app: SIMTRADER_ADMIN_PASSWORD=change-me java -jar backend/target/quarkus-app/quarkus-run.jar (PostgreSQL defaults to localhost:5442, see backend/src/main/resources/application.properties).

How it fits together

Path What
/admin/ Static SvelteKit administration UI (served by Quarkus)
/api/admin/v1/... Setup, clock control, inspection, replay, provider registry
/api/canonical/v1/runs/{runId}/... Provider-neutral trading API
/mock/{instanceId}/{providerKey}/... Emulated provider API of the instance's active run
/mock-run/{runId}/{providerKey}/... Emulated provider API of one specific run (concurrent tests)
/api/admin/v1/runs/{runId}/webhooks Outbound webhook deliveries (status, attempts, redeliver)
/q/health/live, /q/health/ready Health

Typical CI flow: create an instance → create a run from a fixture (fixtures/runs/*.json) → call the provider API → POST /api/admin/v1/runs/{id}/clock/advance → assert on /orders, /obligations, /reconciliation → GET /api/admin/v1/runs/{id}/export to keep a replayable package. Waits are explicit (/runs/{id}/quiesce, /runs/{id}/wait?applied=N, advance completion) — no sleeps needed.

Tests

cd backend && mvn test

Unit tests (calculation vectors, calendars, state machines, OpenAPI 3.0/3.1 conformance fixtures, routing, mapping DSL, architecture rules) plus integration tests against a local PostgreSQL (simtrader_test database created by deploy/postgres/init). Browser smoke tests:

cd frontend && SIMTRADER_ADMIN_PASSWORD=change-me npx playwright test

They use a locally installed Chromium (PLAYWRIGHT_CHROMIUM, default /Applications/Chromium.app/...) and fail on any request to a non-local host.

Documentation

  • Architecture — modules, request lifecycle, durable work, clock, accounting
  • Capability matrix — what is supported, partial, unsupported or not built yet
  • Mapping DSL — provider bundle manifests, the mapping language and spec-driven webhooks
  • Operations — configuration, deployment, recovery
  • Decisions — architecture decision records