PostTradeClearingPlatform

A distributed, event-driven post-trade clearing and settlement platform that simulates a production-grade stock exchange clearing backend.

---

What This System Does

• Accepts trade submissions from market participants
• Validates trades (instrument, accounts, quantity)
• Updates buyer and seller positions atomically
• Performs final settlement of confirmed trades
• Publishes events across the system via Apache Kafka
• Notifies participants of settlement outcomes
• Maintains reference data for instruments and participants
• Handles corporate actions (dividends, stock splits)

---

Architecture

Style: Event-Driven Microservices
Communication: REST (client) + Kafka (internal)
Consistency: Strong consistency for settlement via transactional writes
Scalability: Horizontal — each service scales independently

Participants
     │
     ▼
API Gateway (8080)
     │
     ▼
MarketIntegrationGateway (8088)
     │
     ▼
Kafka Event Bus
     │
 ┌────┼──────┬──────────────┐
 ▼    ▼      ▼              ▼
Trade Position ReferenceData CorporateAction
Svc   Svc     Svc            Svc
     │
     ▼
Clearing Service
     │
     ▼
Notification Service

---

Services

Service	Port	Responsibility
api-gateway	8080	Auth, routing, rate limiting
market-integration-gateway	8088	Protocol translation, event publishing
trade-service	8081	Trade validation, persistence, event emission
position-service	8082	Position updates, oversell protection
clearing-service	8083	Settlement finalization
reference-data-service	8085	Instruments and participant management
corporate-action-service	8086	Dividends and stock splits (skeleton)
notification-service	8084	Participant notifications

---

Tech Stack

Layer	Technology
Language	Java 21
Framework	Spring Boot 3.3
Gateway	Spring Cloud Gateway
Messaging	Apache Kafka
Database	PostgreSQL
Cache	Redis
Identity	Keycloak (OAuth2 + OIDC)
Migrations	Flyway
Metrics	Prometheus + Grafana
Logging	Fluentd → Elasticsearch → Kibana
Infrastructure	Docker Compose

---

Kafka Topics

Topic	Producer	Consumer(s)
trade-submitted	TradeService	PositionService
trade-validated	PositionService	PositionService, ClearingService
position-updated	PositionService	ClearingService
settlement-completed	ClearingService	NotificationService
notification-events	NotificationService	—
reference-data-events	ReferenceDataService	—
corporate-action-events	CorporateActionService	—
trade-dead-letter	All (DLQ)	Monitoring

Partition key: accountId — ensures ordered processing per account.

---

Local Setup

Prerequisites

• Java 21
• Docker + Docker Compose
• Maven 3.9+

Start Infrastructure

cd infrastructure/docker
docker compose up -d

Build All Services

mvn clean install -DskipTests

Run a Service

cd trade-service
mvn spring-boot:run

---

Infrastructure URLs

Service	URL
API Gateway	http://localhost:8080
Kafka UI	http://localhost:8090
Keycloak	http://localhost:8180
Prometheus	http://localhost:9090
Grafana	http://localhost:3000
Kibana	http://localhost:5601
PostgreSQL	localhost:5432

---

Submit a Trade (Quick Test)

# Get token from Keycloak
TOKEN=$(curl -s -X POST http://localhost:8180/realms/clearing/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=clearing-client" \
  -d "client_secret=secret" \
  -d "username=user" \
  -d "password=password" \
  -d "grant_type=password" \
  | jq -r '.access_token')

# Submit trade to API Gateway
curl -X POST http://localhost:8080/api/v1/trades \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instrumentId": "AAPL",
    "buyerAccountId": "ACC100",
    "sellerAccountId": "ACC200",
    "quantity": 100,
    "price": 150.00
  }'

---

Success Criteria

• POST /trades → returns { tradeId, status: SUBMITTED }
• Kafka event appears in trade-submitted topic
• Position records updated in DB
• Trade status becomes SETTLED
• Grafana dashboards populated with metrics
• Notifications logged in notification-service

---

Development Phases

Phase	Focus	Status
0	Mono-repo + build setup	✅ Done
1	Docker infrastructure	✅ Done
2	Database schema + Flyway	✅ Done
3	Shared libraries + event contracts	✅ Done
4	Backend services (Trade, Position)	🔄 In Progress
5	Security (Keycloak + OAuth2)	✅ Done
6	Observability (Prometheus + ELK)	✅ Done
7	Failure handling + DLQ	✅ Done
8	Frontend (Participant Portal)	⏳ Later
9	Performance optimization	⏳ Pending
10	Code review + documentation	⏳ Pending