System Design: Stock Broker Trading Application (Zerodha / Growth / Upstox)

Designing a robust stock broker platform (such as Zerodha, Groww, or Upstox) requires handling high-frequency transactions, strict data consistency, and aggressive latency targets. A Stock Broker acts as an intermediary layer between retail users and the Stock Exchange (e.g., NSE, BSE). The exchange functions as a secure black box where actual order matching, allocation, and settlement occur, while the broker manages user onboarding, portfolios, watchlists, order validation, and real-time market data streaming.

1. Why Do We Need This? (Problem Statement & Status Quo)

Retail trading platforms bridge the gap between millions of retail investors and centralized financial exchanges. The status quo requires systems capable of handling:

• Massive Concurrency: Millions of active users placing concurrent buy and sell orders during market hours (typically a 6-hour window).
• Zero-Tolerance Financial Accuracy: Unlike social media applications where eventual consistency is acceptable, financial ledgers and stock allocations demand strict ACID compliance and immediate correctness.
• Regulatory Mandates: Strict adherence to KYC (Know Your Customer) compliance, margin/fund validations, and end-of-day regulatory reporting.

2. Core Mental Model & Real-Life Analogy

Real-Life Analogy: The Restaurant Host and the Kitchen

Think of a stock broker as a high-end restaurant with a front-of-house reception desk and a secure, high-pressure kitchen (The Exchange):

• The Customer (Client App) walks up to the hostess, browses the menu (Market Data), checks their wallet balance, and places an order for a dish.
• The Hostess (Broker Backend) validates whether the customer has enough money, verifies their ID (KYC), and forwards the ticket to the kitchen.
• The Kitchen (Stock Exchange) prepares the food (executes the trade), matches buyers with sellers, allocates the shares, and hands the completed plate back to the hostess, who delivers it to the customer.
• Crucial Rule: The broker never cooks the food; it only takes orders, routes them securely, and tracks the bills.

3. Functional Requirements

• User Onboarding & Authentication: Users must be able to register, log in, and complete mandatory KYC verification.
• Real-Time & Historical Market Data: Users must be able to view live streaming prices (near real-time) and historical charts spanning days, weeks, or years for 8,000–10,000 listed stocks.
• Order Placement: Users must be able to place buy/sell orders, categorized as Market Orders (executed immediately at current market price) or Limit Orders (executed only when the stock hits a specific target price).
• Watchlists: Users can create, update, and manage custom watchlists to monitor groups of favorite stocks.
• Portfolio & Dashboard: Users can track past orders, current holdings, positions, and live Profit & Loss (P&L) metrics.

4. Non-Functional Requirements & Scale Estimation

• Scale:
  • Total Users: Millions of registered users.
  • Concurrent Daily Transactions: Millions of trades per day.
  • Total Listed Stocks: ~8,000 to 10,000 instruments (spanning NSE and BSE in India).
• CAP Theorem Priority: Consistency (C) over Availability (A). If a server goes down briefly, it is acceptable, but having a discrepancy between deducted funds and allocated stock will result in catastrophic financial loss.
• Latency Targets:
  • Order Placement Latency: $< 100\text{ ms}$.
  • Market Data Streaming Latency: $< 50\text{ ms}$ (near real-time).
• Geographical Scoping: Stock brokers are country-specific (e.g., Indian brokers operate entirely within Indian data centers/cloud regions), making low-latency local deployments achievable.

5. Core Entities

1. User: Stores profile metadata, authentication credentials, and KYC status.
2. Stock: Stores exchange symbols, instrument tokens, and descriptive metadata.
3. Order: Represents a user's intent to buy or sell (tracked through lifecycle states: Pending, Verified, Rejected, Successful).
4. Trade: Represents an order that has been successfully executed and allocated by the exchange.
5. Portfolio / Holding: Aggregates a user's current long-term holdings and active intraday positions to calculate P&L.
6. Watchlist: Maps user IDs to custom collections of stock symbols.

6. Comprehensive API Design

Note: Real-time market data endpoints are not traditional HTTP GET requests; instead, they operate over persistent WebSocket connections to stream high-frequency tick data.

7. High-Level System Architecture & Flow

8. Deep-Dive Component Design & Low-Level Flows

A. The Price Tracker Service & Market Data Pipeline

Handling 8,000+ stocks updating multiple times per second requires an asynchronous event-driven streaming pipeline rather than naive polling.

1. Exchange Connectivity: The backend maintains persistent Bidirectional WebSocket connections via an Exchange Gateway. A single WebSocket connection typically handles 300 to 500 stock subscriptions, meaning ~20 persistent WebSocket connections cover all 5,000–10,000 exchange symbols.
2. Buffer Layer (Kafka): Raw tick streams arriving from the exchange are published into a Kafka broker topic (stock-price) to act as a resilient back-pressure buffer.
3. Price Ingestor Service: A consumer service reads from the Kafka topic and writes data concurrently to:
   • InfluxDB (Time-Series DB): Stores second-by-second historical candlestick data so users can view past trends without querying the expensive exchange API.
   • Redis Pub/Sub: Publishes Latest Transaction Prices (LTP) to memory channels.
4. Client Delivery via WebSocket Gateway: Clients establish a persistent WebSocket connection to subscribe to specific symbols. The Price Tracker Service subscribes to Redis channels and pushes real-time updates directly to connected clients.

B. Order Execution & Validation Pipeline

Placing an order under high load requires decoupling synchronous user requests from asynchronous exchange execution using message queues.

1. Order Submission: The client sends a trade request (POST /api/v1/orders) through the API Gateway to the Order Service.
2. Raw Order Queue: The Order Service publishes the raw event to Kafka (raw-order topic).
3. Validator Service: Consumes raw orders and performs critical checks:
   • Verifies KYC status (User DB).
   • Verifies sufficient account margin and wallet balance (Payment DB).
   • Checks if the market is currently open.
4. Order Routing:
   • If validation fails, the order is pushed to the rejected-order topic and marked as rejected.
   • If validation succeeds, it is pushed to the verified-order topic, and the Order Service forwards it via the Exchange Gateway to the Stock Exchange.
5. Persistence & Reconciliation:
   • Order DB (PostgreSQL): Records all submitted orders (Pending, Rejected, Successful).
   • Trade DB (PostgreSQL): Records only executed/allocated trades returned by the exchange.
   • Order Tracker Service: Consumes exchange acknowledgments from Kafka, updates order statuses, calculates trade IDs, and triggers push notifications to the user.

9. Summary & Key Takeaways

• Broker vs. Exchange: A stock broker is an intermediary application that manages users, portfolios, and watchlists, treating the stock exchange as an external execution black box.
• Consistency over Availability: Financial ledgers and stock allocations demand strict ACID consistency (Consistency in CAP theorem) to prevent catastrophic financial discrepancies.
• WebSockets over SSE / Polling: Persistent bidirectional WebSocket connections are mandatory for streaming high-frequency stock prices and handling dynamic client symbol subscriptions efficiently.
• Kafka for Back-Pressure Buffer: Ingesting thousands of stock ticks per second requires Kafka event streaming buffers to prevent downstream database and service crashes.
• Time-Series Databases for History: Historical candlestick charts should be stored in specialized time-series databases like InfluxDB to minimize expensive, chargeable API calls back to the primary stock exchange.
• Decoupled Order Validation: Order placement must be decoupled using message queues (raw-order, verified-order, rejected-order) and dedicated validator services to handle traffic spikes safely.
• Separation of Order and Trade DBs: Splitting raw order requests from successfully executed exchange allocations ensures clean end-of-day reconciliation and accurate portfolio P&L generation.