🏦 Trading Engine

A production-grade, event-driven stock trading platform built with a Java Spring Boot microservices architecture. The system handles real-time order placement, order matching, trade execution, market-data streaming, and user portfolio management — all coordinated through Apache Kafka and backed by PostgreSQL.

---

📑 Table of Contents

• Architecture Overview
• Microservices
• Technology Stack
• Getting Started
  • Prerequisites
  • Infrastructure Setup
  • Configuration
  • Running the Services
• API Reference
• Kafka Event Flow
• Security
• Project Structure
• Contributing

---

🏗 Architecture Overview

                        ┌────────────────────────────┐
                        │        API Gateway          │
                        │  (Port 8080 · JWT Filter)   │
                        └────────────┬───────────────┘
                                     │ routes requests
           ┌─────────────────────────┼──────────────────────────┐
           ▼                         ▼                          ▼
   ┌──────────────┐        ┌──────────────────┐      ┌─────────────────────┐
   │ User Service │        │  Order Service   │      │ Market Data Service │
   │  (Port 8081) │        │  (Port 8082)     │      │    (Port 8085)      │
   └──────────────┘        └────────┬─────────┘      └─────────────────────┘
                                    │ Kafka: orders-topic
                                    ▼
                         ┌──────────────────────┐
                         │   Matching Engine    │
                         │    (Port 8083)       │
                         └──────────┬───────────┘
                                    │ Kafka: trades-topic
                                    ▼
                         ┌──────────────────────┐
                         │    Trade Service     │
                         │    (Port 8084)       │
                         └──────────────────────┘

   ┌────────────────────────────────────────────────────────┐
   │          Eureka Discovery Server (Port 8761)           │
   └────────────────────────────────────────────────────────┘

   Infrastructure: Apache Kafka · PostgreSQL (Supabase) · Redis

---

🛠 Microservices

Service	Port	Responsibility
Eureka Server	8761	Service discovery & registry
API Gateway	8080	Single entry point, JWT validation, routing
User Service	8081	Registration, login, JWT issuance, portfolio
Order Service	8082	Order placement, validation, Kafka publishing
Matching Engine	8083	Order book, buy/sell matching, trade generation
Trade Service	8084	Trade event consumption, history persistence
Market Data Service	8085	Real-time price feeds, WebSocket streaming

---

⚙️ Technology Stack

Category	Technology
Language	Java 17
Framework	Spring Boot 3.x
Service Discovery	Spring Cloud Netflix Eureka
API Gateway	Spring Cloud Gateway MVC
Messaging	Apache Kafka (Confluent 7.5)
Database	PostgreSQL 15 (Supabase)
Caching	Redis 7.2
Security	Spring Security + JWT (JJWT)
ORM	Spring Data JPA / Hibernate
Build Tool	Maven (Maven Wrapper included)
Containerisation	Docker + Docker Compose

---

🚀 Getting Started

Prerequisites

Tool	Version
Java JDK	17+
Maven	3.9+ (or use included mvnw)
Docker & Docker Compose	Latest
Git	Any

Infrastructure Setup

Start Kafka, Zookeeper, PostgreSQL and Redis via Docker Compose:

docker-compose up -d

This spins up:

• Zookeeper on port 2181
• Kafka on port 9092
• PostgreSQL on port 5432 (db: tradingdb, user: postgres)
• Redis on port 6379

Configuration

Every service ships with an application.properties.example template located at:

<service>/src/main/resources/application.properties.example

Copy and populate the template for each service:

# Example for user-service
cp user-service/src/main/resources/application.properties.example \
   user-service/src/main/resources/application.properties

Then edit the file and replace the placeholder values:

Placeholder	Description
<DB_HOST>	PostgreSQL hostname (e.g. localhost or Supabase host)
<DB_NAME>	Database name (e.g. postgres)
<DB_USER>	Database username
<DB_PASSWORD>	Database password
<YOUR_JWT_SECRET_MIN_32_CHARS>	A random 32+ character secret key

⚠️ Never commit application.properties — it is excluded by .gitignore.

Running the Services

Start services in order (each in its own terminal):

# 1. Eureka Discovery Server (must start first)
cd eureka-server && ./mvnw clean spring-boot:run

# 2. API Gateway
cd api-gateway && ./mvnw clean spring-boot:run

# 3. User Service
cd user-service && ./mvnw clean spring-boot:run

# 4. Order Service
cd order-service && ./mvnw clean spring-boot:run

# 5. Matching Engine
cd matching-engine && ./mvnw clean spring-boot:run

# 6. Trade Service
cd trade-service && ./mvnw clean spring-boot:run

# 7. Market Data Service
cd market-data-service && ./mvnw clean spring-boot:run

Verify everything is up:

• Eureka Dashboard → http://localhost:8761
• All 6 services should appear as UP in the registry.

---

📡 API Reference

All requests go through the API Gateway at http://localhost:8080.

Auth — User Service (/api/users)

Method	Endpoint	Auth	Description
POST	/api/users/register	❌ Public	Register a new user
POST	/api/users/login	❌ Public	Login & receive JWT token
GET	/api/users/portfolio	✅ Bearer	View user portfolio

Register

POST /api/users/register
{
  "username": "akhil",
  "email": "akhil@example.com",
  "password": "secret123"
}

Login

POST /api/users/login
{
  "email": "akhil@example.com",
  "password": "secret123"
}
// Response: { "token": "eyJhbGci..." }

---

Orders — Order Service (/api/orders)

Method	Endpoint	Auth	Description
POST	/api/orders	✅ Bearer	Place a new order
GET	/api/orders/{userId}	✅ Bearer	Get orders for a user

Place Order

POST /api/orders
Authorization: Bearer <token>
{
  "userId": 1,
  "symbol": "AAPL",
  "quantity": 10,
  "price": 185.50,
  "orderType": "LIMIT",
  "orderSide": "BUY"
}

Order types: LIMIT, MARKET
Order sides: BUY, SELL

---

Trades — Trade Service (/api/trades)

Method	Endpoint	Auth	Description
GET	/api/trades/{userId}	✅ Bearer	Get trade history for a user

---

Market Data — Market Data Service (/api/market)

Method	Endpoint	Auth	Description
GET	/api/market/{symbol}	❌ Public	Get latest price for a symbol
WS	/ws/market	❌ Public	WebSocket real-time price feed

---

📨 Kafka Event Flow

Order Service
    │
    │  orders-topic  (OrderEventDTO)
    ▼
Matching Engine
    │  — Matches BUY/SELL orders from the in-memory order book
    │
    │  trades-topic  (TradeEventDTO)
    ▼
Trade Service
    │  — Persists executed trades to PostgreSQL
    │  — Updates user portfolios

Key Kafka Topics

Topic	Producer	Consumer	Payload
orders-topic	Order Service	Matching Engine	OrderEventDTO
trades-topic	Matching Engine	Trade Service	TradeEventDTO

---

🔐 Security

• JWT Authentication is enforced at the API Gateway level via JwtAuthFilter.
• Tokens are issued by the User Service on successful login.
• The JWT secret must be identical in user-service and api-gateway configs.
• Public endpoints (no token required):
  • POST /api/users/register
  • POST /api/users/login
  • GET /api/market/**
  • WebSocket /ws

---

📁 Project Structure

trading-engine/
├── docker-compose.yml              # Infrastructure (Kafka, PG, Redis)
├── .gitignore                      # Protects secrets & build artifacts
│
├── eureka-server/                  # Service registry
├── api-gateway/                    # JWT auth + routing
│   └── src/main/
│       ├── java/.../filter/JwtAuthFilter.java
│       └── resources/application.properties.example
│
├── user-service/                   # Auth, registration, portfolio
│   └── src/main/
│       ├── java/.../model/User.java
│       └── resources/application.properties.example
│
├── order-service/                  # Order placement & Kafka publishing
│   └── src/main/
│       ├── java/.../dto/OrderRequestDTO.java
│       └── resources/application.properties.example
│
├── matching-engine/                # Order book & trade matching
│   └── src/main/
│       └── resources/application.properties.example
│
├── trade-service/                  # Trade event consumer & history
│   └── src/main/
│       └── resources/application.properties.example
│
└── market-data-service/            # Price feeds & WebSocket
    └── src/main/
        └── resources/application.properties.example

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Copy and configure all application.properties.example files — do not commit real credentials
4. Commit your changes: git commit -m "feat: add my feature"
5. Push and open a Pull Request

---

📄 License

This project is open-source and available under the MIT License.

---

Built with ☕ Java · 🍃 Spring Boot · ⚡ Apache Kafka