📈 TradeSim - Mini Trade Lifecycle Simulator

A lightweight, end-to-end fintech trading system simulation that demonstrates automation engineering, securities lending workflows, and trading systems architecture.

---

🎯 Overview

TradeSim is a self-contained demo project that simulates the core lifecycle of a trading system:

1. Automated Order Generation — Background process creates random buy/sell orders
2. Securities Lending Simulation — Validates share availability for short sells
3. Order Matching Engine — Matches buy/sell orders at compatible prices
4. Real-time Dashboard — Live visualization of orders, trades, and inventory

This project demonstrates understanding of:

• ✅ Business Automation — Eliminating manual inputs through automated workflows
• ✅ Securities Lending — Modeling inventory, borrowing, and lending availability
• ✅ Trading Engineering — Order books, matching logic, and trade execution
• ✅ Systems Thinking — State management, real-time data flow, and API design

---

🚀 Quick Start

Prerequisites

• Node.js 18+ installed

Installation

# Clone/navigate to project
cd TradeSim

# Install dependencies
npm install

# Start the server
npm start

Access the Dashboard

Open http://localhost:3000 in your browser.

---

🔧 Features

1. Automated Order Generation

The generator creates realistic orders at configurable intervals:

{
  "id": 1042,
  "symbol": "AAPL",
  "side": "BUY",
  "quantity": 50,
  "price": 178.32,
  "borrowNeeded": false,
  "status": "PENDING",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

2. Securities Lending Logic

When borrowNeeded: true (simulating short sells):

• ✅ Success: Inventory has sufficient shares → Mark as "borrowed"
• ❌ Failure: Insufficient inventory → Trade fails with reason

// Inventory state example
{
  "AAPL": { "available": 850, "borrowed": 150, "total": 1000 }
}

3. Order Matching Engine

Simple price-time priority matching:

• BUY orders match with SELL orders at same symbol
• Price compatibility: BUY price ≥ SELL price
• Immediate execution if match found
• Otherwise, order rests in the book

4. Real-time Dashboard

Live updates via Server-Sent Events (SSE):

• 📊 Stats: Total orders, executed, failed, open, volume
• 📋 Open Orders: Unmatched orders waiting in the book
• ✅ Executed Trades: Completed transactions
• ❌ Failed Trades: Orders that couldn't execute
• 🔒 Inventory: Securities lending availability

---

📡 API Reference

Method	Endpoint	Description
GET	/api/state	Get full system state
GET	/api/inventory	Get lending inventory
POST	/api/order	Submit a manual order
POST	/api/generator/start	Start auto-generation
POST	/api/generator/stop	Stop auto-generation
GET	/api/generator/status	Check generator status
POST	/api/reset	Reset entire system
GET	/api/events	SSE real-time updates

Example: Submit Order

curl -X POST http://localhost:3000/api/order \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "side": "BUY",
    "quantity": 100,
    "price": 178.50,
    "borrowNeeded": false
  }'

---

📁 Project Structure

TradeSim/
├── server/
│   ├── index.js          # Express server & API routes
│   ├── generator.js      # Automated order generation
│   ├── engine.js         # Matching engine & securities lending
│   └── data/
│       └── inventory.json  # Lendable securities inventory
├── public/
│   └── index.html        # Dashboard frontend
├── package.json
└── README.md

---

💡 Design Decisions

Why These Technologies?

• Node.js/Express: Natural fit for real-time systems with event-driven architecture
• Server-Sent Events: Simpler than WebSockets for unidirectional updates
• JS Frontend: Zero dependencies, instant load, demonstrates fundamentals

Simplifications (by design)

This is a demonstration project, not production software. Intentional simplifications:

• In-memory order books (no database)
• Single-threaded matching (no concurrency handling)
• Price-time priority only (no order types like limit/market/stop)
• No authentication or user management
• No persistence beyond inventory file

What This Demonstrates

Despite simplifications, the project shows understanding of:

• Order lifecycle: Pending → Validated → Matched/Open → Executed/Failed
• Securities lending: Availability check → Borrow → Return
• Matching logic: Price priority, partial fills, order book management
• Real-time systems: Event broadcasting, state synchronization
• API design: RESTful endpoints, proper status codes

---

🎓 Concepts Demonstrated

Domain	Concepts
Business Automation	Scheduled tasks, event-driven workflows, eliminating manual processes
Securities Lending	Inventory management, borrow availability, locate logic
Trading Engineering	Order books, matching engines, trade execution, state machines
Backend Development	REST APIs, SSE, Express.js, modular architecture
Frontend Development	Real-time updates, responsive design, data visualization

---

🔮 Potential Extensions

If expanding this project:

• Add WebSocket support for bidirectional communication
• Implement order types (market, limit, stop-loss)
• Add Redis for distributed state
• Create historical data persistence with PostgreSQL
• Build React/Vue frontend with charts
• Add authentication and user portfolios
• Implement FIX protocol for industry standard messaging

---

📝 License

MIT License - Feel free to use this as a learning resource or portfolio piece.

---

Built to demonstrate fintech engineering skills
_{Automation • Securities Lending • Trading Systems}