- Java 89.1%
- Svelte 8.2%
- TypeScript 1.3%
- JavaScript 0.8%
- Shell 0.4%
- Other 0.2%
| backend | ||
| benchmarks | ||
| contracts/sample-providers | ||
| deploy | ||
| docs | ||
| fixtures/runs | ||
| frontend | ||
| scenarios | ||
| scripts | ||
| .gitignore | ||
| compose.yaml | ||
| README.md | ||
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