gtat-tech-career-kickstarter-main/proto/README.md

Proto Definitions

This directory contains the Protobuf definitions that describe the entire messaging contract of the exchange system. Every message your components must accept, respond to, or emit is defined here.

These files are the contract your implementation must satisfy — system tests will connect to your components over TCP and exchange exactly these messages.

Where to start

Begin with common.proto. It contains the MessageType enum, which is the single authoritative index of every message in the system. The enum is grouped by module (Auth, Admin, Info, Order Book, Execution, Risk), giving you a map of the whole system before you dive into any individual file. It also defines the shared types that appear everywhere else: Instrument, Side, and the auth LoginRequest/LoginResponse pair.

File-by-file overview

common.proto

The foundation. Defines:

• MessageType — a numbered enum of every request/response/notification in the system, grouped by subsystem.
• Instrument — the data model for a tradeable instrument (symbol, description, currency, multiplier).
• Side — the BUY/SELL enum used across order-related messages.
• LoginRequest / LoginResponse — the authentication handshake your components must perform with every connecting client before serving any other message.

Read this first to orient yourself. Every other file imports it.

admin.proto

The administration interface your exchange must expose to let the system be bootstrapped before trading begins.

• CreateInstrumentRequest/Response — your exchange must accept requests to list a new tradeable instrument, create an order book for it, and return the assigned order_book_id.

User information is provided via a static JSON data file (see users_data_schema.json in the project root) whose path is supplied in each component's config as dataFilePath. Components that require authentication must read this file at startup to validate login credentials.

info.proto

The market data feed your exchange must maintain and push to subscribed clients.

• OnInstrument — your exchange must push this to every client on connection (for all existing instruments) and again whenever a new instrument is created.
• OrderBookSubscribeRequest/Response — clients may subscribe to a specific instrument's order book in one of two modes. Your exchange must honour the chosen type and push updates accordingly:
  • TOP_OF_BOOK — push OnTopOfBook whenever the best bid or ask changes.
  • PRICE_DEPTH_BOOK — push OnPriceDepthBook with the full visible depth on every change.
• OnTrade — your exchange must broadcast this to all subscribed clients whenever a trade occurs, showing price, quantity, and which side was the aggressor.

order_book.proto

The core of the exchange: the matching engine. This component stores resting orders, matches them when prices cross, and is the authoritative source of order book state.

It has two responsibilities:

State broadcast — pushed to all connected clients upon login (current state) and on every subsequent change:

• OnOrderInserted — broadcast when a new order enters the book, including any trades it immediately triggered.
• OnOrderCancelled — broadcast when an order is removed from the book.
• OnTrade — broadcast when a match occurs, carrying both the buy and sell order_ids and full trade details.

Request/response — your order book component must accept these from other internal services:

• InsertOrderRequest/Response — place a limit order identified by order_book_id. Your component must assign an order_id, record the timestamp, attempt to match, and return the result.
• CancelOrderRequest/Response — cancel a resting order by order_book_id and order_id. Your component must confirm the cancellation timestamp and remaining quantity at the time of removal.

execution.proto

The client-facing execution interface your exchange must expose to trading clients. It is a higher-level entry point into the order book: clients address orders by instrument_symbol (human-readable) rather than order_book_id (internal numeric ID), so this component is responsible for the translation.

• InsertOrderRequest/Response — accept a limit order from a client, resolve the instrument to its order book, forward it, and return the result (order ID, timestamp, fills).
• CancelOrderRequest/Response — accept a cancellation request from a client and forward it to the appropriate order book.
• OnTrade — your exchange must send this privately to the specific client whose order was involved in a trade, reporting their order_id, side, and whether they were the aggressor.

risk_limits.proto

The risk management component your exchange must implement to enforce guardrails on all trading activity. Before an order reaches the order book, risk limits must be checked.

Limits operate at two scopes:

User-level (UserRiskLimits):

• max_outstanding_quantity — caps the total quantity a user may have resting across all instruments simultaneously.
• message_rate_rolling_limit — caps the number of order/cancellation messages a user may send within a rolling time window.

Instrument-level (InstrumentRiskLimits):

• max_outstanding_quantity / max_outstanding_amount — caps how much of a single instrument a user may have resting at one time.
• order_quantity_rolling_limit / order_amount_rolling_limit — rolling-window caps on order flow per instrument.

Each scope has a symmetric Get.../Set... request/response pair. Your component must persist these limits and enforce them on every incoming order.