rivaanranawat/stock_exchange

Purpose and Entry Points

This is a C++ stock-exchange prototype centered on an in-process limit-order matching engine. The main exchange executable starts at src/exchange_main.cpp; interactive or automated clients are represented by tools/trader_terminal.cpp and tools/liquidity_bot.cpp. Build composition is defined in CMakeLists.txt.

Exchange Runtime Boundary

src/exchange_main.cpp is the application orchestration point: it should own process startup, instantiate the matching subsystem, and connect producer/consumer paths. There is no evidence of a web service, database, network protocol layer, or external exchange integration in the repository tree; the system is intended to run locally in native C++.

Order Domain Model

The matching domain is defined under src/matching/:

• src/matching/order.h represents submitted orders and their matching-relevant fields.

• src/matching/events.h defines exchange/matching outputs such as fills or order-state events.

• src/matching/level.h represents a price level, the unit used to organize resting liquidity.

These types form the boundary between order ingress, book state, and emitted execution events.

Order Book and Matching Stage

src/matching/order_book.h maintains book-side state and price-level organization. src/matching/matching_engine.h coordinates matching: accepted orders are compared against opposing resting liquidity, executable quantities generate events, and unfilled remainder can be retained in the book. This is the core stateful transaction boundary: order-book mutation and event production must remain ordered and consistent.

Event and Concurrency Flow

The likely primary flow is:

1. A terminal or liquidity bot creates orders.

2. Orders enter the exchange/matching-engine path.

3. src/matching/matching_engine.h updates src/matching/order_book.h.

4. Resulting events from src/matching/events.h are delivered to downstream consumers.

src/core/spsc_queue.h provides a single-producer/single-consumer queue, indicating a low-latency handoff boundary between one order-producing thread and one matching or event-consuming thread. Its use should preserve single-writer ownership of matching/book state rather than allowing concurrent book mutation.

Performance-Oriented Core Infrastructure

The core layer supports deterministic, low-allocation exchange operation:

• src/core/memory_pool.h supplies pooled allocation for high-churn objects such as orders or levels.

• src/core/clock.h supplies timing/timestamp support for exchange events or latency measurement.

• src/core/types.h centralizes shared primitive/domain types.

These facilities should be treated as infrastructure dependencies of the matching path, not as business logic.

Client/Simulation Tools

tools/trader_terminal.cpp is the human-facing order-entry/observation client. tools/liquidity_bot.cpp is an automated liquidity source, likely exercising both sides of the book and generating resting orders. They are separate from the exchange core and should communicate through the exchange’s intended ingress/event interface rather than directly owning order-book internals.