Architecture Overview

Every service, library, storage system, and frontend in the Position Keeping System (PKS), with data-flow bindings. Hot path (< 1 ms), warm path (< 100 ms), and async/cold paths are labeled in the diagram and latency table below.

1. Full System Data-Flow Diagram

---

2. Data-Flow Latency Tiers

Path	Transport	Typical latency	Description
Fill → SHM position slot	In-process + SHM seqlock	< 1 ms	Fill lands in position-accumulator, lot-matched, written to /pks-positions-v1
SHM → Atlas Qt / algo strategy	SHM seqlock read	< 1 µs	Direct shared-memory read; no network hop
Fill → WebSocket (atlas-web)	NATS + BFF + WS	5–15 ms	PositionUpdated via NATS → broadcaster → WebSocket push
Mark → valuation result	NATS + gRPC + NATS	50–200 ms	Mark event → valuation-hub → pricing-engine gRPC → PositionValuated → BFF
Trade → Postgres checkpoint	Async write	< 500 ms	position-snapshot-writer async flush; not on the hot path
Fill → QuestDB time-series	Async write	< 1 s	questdb-trade-writer async INSERT
EOD snapshot	Batch job	~2–5 min	bo-eod-aggregate triggered by report-scheduler

---

3. Component Reference Table

3.1 Services

Component	Crate	Description	Consumes	Publishes	Storage R/W
execution-platform	execution-platform (execution repo)	OMS: ClOrdId minting, round-robin load-balanced connection manager, 18 venue gateways (MOEX FIX/TWIME/ASTS, crypto CLOBs, IBKR, Exante, CQG, Polymarket)	Venue fills (FIX/TWIME/REST)	FillEvent → pd.canonical	Postgres (execution schema)
trade-capture-lifecycle	trade-capture-lifecycle	Trade validation state machine; regime routing; lifecycle event processor (amend, cancel, novation, give-up, interbook)	FillEvent (pd.canonical)	TradeBooked · bo.booking.v1 · LifecycleEventApplied · bo.booking.v1	Postgres (trade schema)
trade-booker	trade-booker	Manual booking REST API; idempotency guard (24 h deduplication by idempotency_hash); OTC instrument registration	REST POST /trades/book	TradeBooked · bo.booking.v1	Postgres (back_office)
bo-book-router	bo-book-router	Venue fill decoder; routes decoded fills to the correct book based on routing rules; venue decoders: MOEX FIX, MOEX TWIME, Coinbase, Hyperliquid, Alpha4, Polymarket	NATS TradeBooked	Decoded fill → position-accumulator (direct call)	—
bo-allocation	bo-allocation	Splits a block trade into child allocations across books per allocation instructions	NATS TradeBooked (block)	TradeBooked · bo.booking.v1 (child legs)	Postgres (back_office.allocation)
bo-batch-api	bo-batch-api	Bulk trade import: accepts CSV or JSON batch; validates; publishes individual TradeBooked events	REST POST /batch/trades	TradeBooked · bo.booking.v1 (per row)	Postgres (batch audit)
position-accumulator	position-accumulator	Sole writer of position state. Per-book single-writer; in-memory position map; FIFO/LIFO/WA lot matching via bo-lotmatch; seqlock SHM write; NATS publisher; crash-idempotent (dedup by trade_id)	NATS TradeBooked · LifecycleEventApplied (via bo-book-router)	PositionUpdated · bo.position.updated.v1 → NATS; PositionSlot → SHM /pks-positions-v1; checkpoint trigger → position-snapshot-writer	SHM write; Postgres (via PSW)
bo-lotmatch	bo-lotmatch	Lot matching algorithm library: FIFO (default), LIFO, weighted-average; configurable per book and per instrument class; computes realised P&L at close	Called by position-accumulator	Returns matched lots + realised P&L to caller	— (stateless library)
position-snapshot-writer	position-snapshot-writer	Async Postgres checkpoint writer; receives checkpoint triggers from position-accumulator; writes back_office.position_snapshot (crash-recovery WAL)	Checkpoint trigger from PA	position_snapshot rows → Postgres	Postgres W
questdb-trade-writer	questdb-trade-writer	Consumes TradeBooked events; writes time-series rows to QuestDB bo_positions table for historical position queries	NATS TradeBooked	QuestDB bo_positions ILP rows	QuestDB W
pnl-engine	pnl-engine	P&L attribution by Greek bucket: Δ P&L, Γ P&L, ν P&L, θ P&L, carry P&L, FX P&L, funding P&L; writes §11 attribution columns to position_record	NATS PositionUpdated · PositionValuated	PnLAttributed · bo.pnl.attributed.v1 → NATS; attribution rows → Postgres	Postgres W
ledger-service	ledger-service	Double-entry cash ledger; GL posting on every trade; generates cash entries for settlement, fees, accruals	NATS TradeBooked · LifecycleEventApplied	CashLedgerEntry · bo.cash.ledger.v1 → NATS; ledger rows → Postgres	Postgres R/W
cash-position-service-v2	cash-position-service-v2	Aggregates cash balances per (entity, account, currency) from ledger events; publishes real-time balance updates	NATS CashLedgerEntry	CashBalance · bo.cash.balance.v1 → NATS	Postgres R/W
open-currency-position-service	ocp-service	Aggregates net FX exposure per entity from cash balances; identifies open currency risk	NATS CashBalance	OcpPosition · bo.cash.ocp.v1 → NATS	Postgres R/W
cashflow-accrual-engine	cashflow-accrual-engine	Coupon accrual booking for fixed income; perpetual funding accrual booking at funding intervals; posts paired FUNDING / COUPON trades	NATS bo.mark.v1.* (funding rate marks) · schedule	TradeBooked (accrual) · bo.booking.v1 → NATS	Postgres R/W
otc-lifecycle-service	otc-lifecycle-service	OTC trade lifecycle: trade confirmation, novation, termination, give-up; generates LifecycleEventApplied events	REST (from back-office UI) · NATS TradeBooked	LifecycleEventApplied · bo.booking.v1 → NATS	Postgres R/W
inter-entity-xfer-engine	xfer-engine	Inter-entity position and cash transfer workflows; generates paired give-up / receive trades across legal entities	REST · internal trigger	TradeBooked (transfer) · bo.booking.v1 → NATS	Postgres R/W
md-mark-loader	md-mark-loader	Loads end-of-day marks from ISS (batch by board) and intraday marks from ALOR (REST polling); writes to Redis and publishes NATS mark events	ISS REST · ALOR REST	md:mark:v1:{instrument_id} Hash → Redis; md.mark.v1.{instrument_id} → NATS	Redis W
valuation-hub	valuation-hub	Consumes mark events; identifies positions needing revaluation; dispatches PriceRequest to pricing-engine via gRPC; receives PriceResponse; publishes PositionValuated; triggers Greeks aggregator	NATS md.mark.v1.* · bo.position.updated.v1	PositionValuated · bo.position.valuated.v1 → NATS; valuation rows → Postgres	Postgres W; Redis R
pricing-engine	pricing-engine (pricing repo)	QuantLib C++ FFI; full instrument × model matrix: BSM, Black-76, futures fair value, bond curve, swap NPV, XVA; full Greeks suite; SIMD BSM optimisation	gRPC PriceRequest from valuation-hub / pks-bff	gRPC PriceResponse (PV · Greeks · analytics)	Redis R (curves)
position-reconciler	position-reconciler	Cross-source position reconciliation: compares position-accumulator state against pd_positions (exchange-authoritative) from QuestDB; identifies breaks	NATS PositionUpdated · QuestDB pd_positions	Recon result rows → Postgres	Postgres W; QuestDB R
settlement-service	settlement-service	Settlement instruction lifecycle; tracks pending, confirmed, settled, failed status; manages custodian references	NATS TradeBooked	SettlementStatusChanged · bo.settlement.v1 → NATS; instruction rows → Postgres	Postgres R/W
confirmations-service	confirmations-service	Trade confirmation workflow; matches internal trade against counterparty confirm; tracks AFFIRMED / DISPUTED status	NATS TradeBooked	Confirmation state rows → Postgres	Postgres R/W
corp-actions-service	corp-actions-service	Corporate actions processing: dividends, stock splits, mergers, rights issues; adjusts positions via synthetic trades	NATS TradeBooked · external CA feed	CorporateActionBooked · bo.ca.v1 → NATS; CA rows → Postgres	Postgres R/W
dispute-service	dispute-service	Reconciliation break dispute workflow; manages dispute lifecycle, evidence, resolution	NATS bo.recon.v1	Dispute rows → Postgres	Postgres R/W
collateral-service	collateral-service	Initial and variation margin tracking; collateral valuation; haircut computation; margin call generation	NATS PositionUpdated · PositionValuated	MarginCall · bo.collateral.v1 → NATS; margin rows → Postgres	Postgres R/W
regulatory-reporter	regulatory-reporter	Generates regulatory reports (SIMM, Basel trading book metrics, exposure calculations); writes to Postgres regulatory tables	NATS PositionValuated	Regulatory rows → Postgres	Postgres R/W
reconciliation-service	reconciliation-service	External statement ingestion and matching; accepts custodian / broker / exchange position statements; produces match / break results	External statements (CSV, FIX, SWIFT)	Match results → bo-recon; break rows → Postgres; ReconciliationResult · bo.recon.v1 → NATS	Postgres R/W
bo-recon	bo-recon	Internal reconciliation engine; receives break data from reconciliation-service; runs matching algorithms; drives dispute workflow	NATS bo.recon.v1 · reconciliation-service	Break rows → Postgres; bo.recon.v1	Postgres R/W
bo-eod-aggregate	bo-eod-aggregate	EOD position snapshot aggregation; reads intraday position state; writes full position_record v3 rows for the business date	Postgres (intraday state) · QuestDB	position_record EOD rows → Postgres	Postgres R/W; QuestDB R
report-scheduler	report-scheduler	Cron-based report trigger; fires EOD report generation at configured time per desk/entity; supports manual trigger	System clock · REST (manual trigger)	Trigger → report-engine	Postgres R
report-engine	report-engine (worker)	Executes 16-section EOD report templates; distributes work to report-worker pool; assembles results; publishes completion event	report-scheduler trigger · Postgres position_record · NATS events	Work tasks → report-worker; section data → report-renderer; bo.report.generated.v1 → NATS; report rows → Postgres	Postgres R/W
report-worker	report-worker	Distributed report computation worker; processes individual report sections (P&L, Greeks, settlement, regulatory); scales horizontally	Task queue from report-engine	Section results → report-engine	Postgres R; QuestDB R
report-renderer	report-renderer (lib)	Renders report sections to HTML, XLSX (multi-tab), and PDF (one-pager); applies formatting templates and audit trail	Section data from report-engine	XLSX · PDF · HTML artifacts → report-distributor	— (stateless)
report-distributor	report-distributor	Email and Telegram delivery of generated reports; manages distribution lists; tracks delivery receipts	Report artifacts from report-renderer · NATS bo.report.generated.v1	Email · Telegram delivery; delivery rows → Postgres	Postgres R/W
mavr-dlq-reaper	mavr-dlq-reaper	Dead-letter queue consumer; monitors all NATS DLQ subjects for undeliverable messages; alerts on failure; writes dead-letter rows for audit	NATS *.dlq.* (all dead-letter subjects)	Alert (Telegram / PagerDuty); dead-letter rows → Postgres	Postgres W
pks-bff	pks-bff	Primary API gateway. Axum REST (:8080) + gRPC TLS (:8443); JWT auth with RS256; per-user RBAC book filtering; in-memory position merge cache (SimulatorService); serves REST snapshot from merge cache or Postgres; proxies pricing requests to pricing-engine; drives broadcaster	NATS (all position, trade, cash, report subjects) · SHM /pks-positions-v1 · Redis (marks) · Postgres (all schemas) · QuestDB (OHLC, pd_positions)	REST responses → atlas-web; gRPC PositionViewPatch stream → Atlas Qt; events → broadcaster	Postgres R; Redis R; QuestDB R; SHM R
broadcaster	(module inside pks-bff)	tokio::sync::broadcast channel; batches NATS events in ~10 ms windows; fan-out JSON BroadcastMessage to all WebSocket clients; sends heartbeats every 10 s; drops slow consumers	Events from BFF NATS consumer	WebSocket JSON → atlas-web (positions · trades · blotter · cash · reports · orders · curves · ocp · payment_orders)	—
md-query-api	md-query-api	Market data REST query proxy for BFF; exposes OHLC and mark endpoints; queries QuestDB and Redis on behalf of BFF	REST from pks-bff	OHLC bars · mark prices → pks-bff	QuestDB R; Redis R

---

3.2 Storage Systems

Component	Type	Description	Writers	Readers	Key namespaces / tables
NATS JetStream	Message bus	Durable pub/sub with replay; JetStream streams per subject group; 24 h retention for trade events; 7 d for position snapshots; DLQ subjects for each stream	All service publishers	All service consumers; pks-bff broadcaster	See §4 NATS subject taxonomy
Postgres	RDBMS	Primary persistent store; five logical schemas on one cluster	position-snapshot-writer, ledger-service, valuation-hub, pnl-engine, settlement-service, report-engine, trade-booker, all ops services	pks-bff, report-engine, bo-eod-aggregate, all ops services	back_office.* · trade.* · position.* · auth.* · report.*
QuestDB	Time-series DB	High-throughput time-series store for position and OHLC data; ILP ingestion; SQL query interface	questdb-trade-writer, market-data-processor	pks-bff (OHLC), position-reconciler (pd_positions overlay), bo-eod-aggregate, md-query-api	bo_positions · pd_positions · bo_ohlc
Redis	Cache / KV store	Mark cache, curve store, JWT blocklist, session cache; key-TTL eviction	md-mark-loader (marks), pks-bff (JWT blocklist writes)	pks-bff, valuation-hub, pricing-engine, md-query-api	md:mark:v1:{id} · curve:{id} · jwt:blocklist:{jti}
Shared Memory (SHM)	IPC	POSIX shared memory segments; seqlock protocol (lock-free reads, single-writer); sub-microsecond read latency; same-host only	position-accumulator (/pks-positions-v1); valuation-hub greeks-aggregator (/pks-greeks-v1); md-mark-loader (/md-marks-v1)	pks-bff, Atlas Qt, algo strategies	/pks-positions-v1 · /pks-greeks-v1 · /md-marks-v1

---

3.3 Frontends and Clients

Component	Stack	Connection to BFF	Data consumed	Auth
atlas-web	React 18 · Vite · TypeScript · AG Grid · Zustand · TanStack Query	REST /api/v1/* (GET/POST/PATCH/DELETE) + WebSocket /ws?token=<jwt>	Positions, trades, blotter, cash balances, OCP, payment orders, curves, reports, settlement, reconciliation, orders, ref data	JWT Bearer (access_token + refresh_token)
Atlas Qt	C++ · Qt 6 · CMake	gRPC TLS :8443 (PositionsSimulatorService) + direct SHM read (same host)	PositionViewPatch stream; instrument static updates; direct SHM PositionSlot for < 1 µs latency	JWT (gRPC metadata Authorization: Bearer)
Algo strategies	Rust / Python	NATS JetStream (via algo-data-bus) + direct SHM read (same host)	PositionUpdated, PositionValuated, direct SHM reads	NATS credentials (NKey)

---

3.4 Library Crates (shared logic, no binary)

Crate	Used by	Purpose
bo-canonical	All services	Canonical proto definitions (pks_service, position, trade, instrument_static); NATS subject constants
backoffice-proto	Ops services	Legacy backoffice proto definitions (collateral, confirmations, dispute, ledger, positions, reconciliation, settlement)
bo-lotmatch	position-accumulator	FIFO / LIFO / WA lot matching; realised P&L computation
bo-instrument-domain	trade-booker, trade-capture-lifecycle	Instrument domain model and classification
bo-instrument-resolve	trade-capture-lifecycle, pks-bff	Instrument ID resolution across ISIN, CUSIP, FIGI, RIC
bo-instrument-statics	pks-bff, valuation-hub	Instrument static data cache and enrichment
bo-validation	trade-capture-lifecycle, trade-booker	Trade and booking validation rules
bo-shm-bridge	position-accumulator, pks-bff, valuation-hub	SHM segment reader/writer; seqlock protocol
bo-ledger	ledger-service	Double-entry ledger domain model
bo-template	report-engine	Report template engine
bo-query-api	pks-bff, bo-batch-api	Shared query parameter types and SQL builders
field-catalog	position-accumulator, valuation-hub, pnl-engine	Tier 0–3 field registry; inventory! macro; versioned field definitions
position-types	position-accumulator, pks-bff, position-snapshot-writer	Shared position data types
pricing-input-map	valuation-hub, pks-bff	Maps position fields to PriceRequest input structs
valuation-core	valuation-hub	Core valuation types and model dispatch
mavr-fx-convert	position-accumulator, pnl-engine, cash-position-service-v2	FX conversion to functional currency
mavr-circuit-breaker	pks-bff, valuation-hub	Circuit breaker for external gRPC calls
mavr-leader-election	bo-eod-aggregate, report-scheduler	Postgres-backed leader election for singleton services
mavr-shutdown	All services	Graceful shutdown coordination (SIGTERM handler)
backoffice-routing-rules	bo-book-router	Book routing rule evaluation

---

4. NATS Subject Taxonomy

All NATS subjects follow <domain>.<entity>.<version>.<qualifier>. All streams use JetStream with durable pull consumers.

4.1 Trade Lifecycle

Subject	Publisher	Consumer(s)	Payload	Notes
backoffice.booking.v1.TradeBooked	trade-capture-lifecycle · trade-booker · bo-allocation · bo-batch-api · cashflow-accrual-engine · xfer-engine · otc-lifecycle-service	position-accumulator · bo-book-router · ledger-service · settlement-service · confirmations-service · corp-actions-service · collateral-service · questdb-trade-writer	TradeBooked proto	Primary trade ingestion subject; all booking sources converge here
backoffice.booking.v1.LifecycleEventApplied	trade-capture-lifecycle · otc-lifecycle-service	position-accumulator · settlement-service	LifecycleEventApplied proto	Amend, cancel, novation, give-up events
backoffice.booking.v1.TradeRejected	trade-capture-lifecycle	mavr-dlq-reaper · ops alerts	Rejection reason	Failed validation; moves to DLQ

4.2 Position Pipeline

Subject	Publisher	Consumer(s)	Payload
bo.position.updated.v1	position-accumulator	pks-bff · valuation-hub · pnl-engine · position-reconciler	PositionUpdated proto
bo.position.valuated.v1	valuation-hub	pks-bff · pnl-engine · collateral-service · regulatory-reporter	PositionValuated proto
bo.pnl.attributed.v1	pnl-engine	pks-bff · report-engine	PnLAttributed proto

4.3 Market Data

Subject	Publisher	Consumer(s)	Payload
md.mark.v1.{instrument_id}	md-mark-loader	valuation-hub	Mark price + timestamp
md.ohlc.v1.{instrument_id}	market-data-processor	questdb-trade-writer	OHLC bar

4.4 Cash

Subject	Publisher	Consumer(s)	Payload
bo.cash.ledger.v1	ledger-service	cash-position-service-v2	CashLedgerEntry
bo.cash.balance.v1	cash-position-service-v2	pks-bff · open-currency-position-service	CashBalance
bo.cash.ocp.v1	open-currency-position-service	pks-bff	OcpPosition
bo.cash.payment_order.v1	ledger-service	pks-bff	PaymentOrder

4.5 Reporting

Subject	Publisher	Consumer(s)	Payload
bo.report.generated.v1	report-engine	pks-bff · report-distributor	Report ID · run ID · desk · date · seal hash
bo.report.edit.v1	report-engine	pks-bff	Edit metadata · section · user
bo.report.locked.v1	report-engine	pks-bff	Desk · date · locked_at

4.6 Operations

Subject	Publisher	Consumer(s)	Payload
bo.settlement.v1	settlement-service	pks-bff · reconciliation-service	Settlement status update
bo.recon.v1	reconciliation-service · bo-recon	dispute-service · pks-bff	Reconciliation result · breaks
bo.ca.v1	corp-actions-service	position-accumulator · pks-bff	Corporate action event
bo.collateral.v1	collateral-service	pks-bff · ops alerts	Margin call
*.dlq.*	NATS server (undeliverable)	mavr-dlq-reaper	Original message + failure reason

---

5. Port and Endpoint Bindings

Service	Protocol	Port	Binding	Notes
pks-bff	HTTP (REST + WS)	8080	0.0.0.0:8080 → nginx proxy	All /api/v1/*, /auth/*, /ws, /health
pks-bff	gRPC TLS	8443	0.0.0.0:8443	PositionsSimulatorService; used by Atlas Qt and algo clients
pricing-engine	gRPC	50051	mavr-backend network	Internal only; called by valuation-hub and pks-bff
atlas-web	HTTP	80	mavr-edge network	nginx-served SPA; proxies /api, /auth, /ws → pks-bff:8080
atlas.mavr.finance	HTTPS	443	Edge nginx	TLS termination → atlas-web:80
NATS	NATS	4222	mavr-backend	JetStream; all services connect here
Postgres	TCP	5432	mavr-backend	All back-office services
Redis	TCP	6379	mavr-backend	Marks, JWT blocklist, sessions
QuestDB	HTTP (ILP)	9000	mavr-backend	ILP ingestion (questdb-trade-writer)
QuestDB	HTTP (query)	9000	mavr-backend	SQL query (pks-bff, md-query-api)

---

6. Crash Recovery and Idempotency

Every component that mutates state is designed for idempotent replay:

Component	Recovery mechanism	Idempotency key
position-accumulator	Load latest position_snapshot checkpoint; replay TradeBooked from NATS JetStream sequence	trade_id (duplicate = no-op)
ledger-service	Postgres transaction with ON CONFLICT DO NOTHING	trade_id + leg
settlement-service	Postgres UPSERT on trade_id	trade_id
trade-booker	24 h idempotency cache keyed by idempotency_hash	idempotency_hash (client-supplied)
questdb-trade-writer	QuestDB dedup on trade_id timestamp column	trade_id + trade_time
pks-bff (SimulatorService)	Full snapshot pushed to each new subscriber; no durable state loss	NATS consumer sequence
report-engine	Report run is idempotent; re-running for same (desk, date) produces same result	(desk_id, business_date, version)