Mini Exchange Backend

A modular digital asset exchange backend built with Spring Boot 3.x, featuring event-driven microservices architecture, high availability, and extensibility. This project implements a comprehensive trading platform including order management, matching engine, account ledger, risk control, clearing & settlement, and real-time market data.

Features

🔐 User & Authentication – JWT-based authentication, role/permission system
📋 Order Management – Complete order lifecycle (place/cancel/modify) via REST API
⚡ Matching Engine – High-performance price-time priority matching algorithm
💰 Account & Ledger – Double-entry bookkeeping, multi-asset balances, fund locking
🛡️ Risk Management – Real-time risk checks (balance, position limits, order validation)
🧮 Clearing & Settlement – Automated daily/periodic settlement via distributed jobs
📈 Market Data – Real-time orderbook & trade streams via WebSocket
🚀 Event-Driven Architecture – Kafka event streaming, Redis caching + distributed locks
📤 Outbox Pattern – Reliable event publishing for external systems
📊 Monitoring & Observability – Prometheus metrics, structured logging, distributed tracing
🐳 Cloud-Native – Docker containerized, Kubernetes ready with Helm charts

Architecture

flowchart TB
    subgraph "Client Layer"
        A[Web Frontend]
        B[Mobile App]
        C[Trading Bot]
    end

    subgraph "API Gateway Layer"
        D[REST API Gateway]
        E[WebSocket Gateway]
    end

    subgraph "Microservices Layer"
        F[Auth Service]
        G[Account Service] 
        H[Order Service]
        I[Matching Engine]
        J[Risk Service]
        K[Clearing Service]
        L[Market Data Service]
        M[Notification Service]
    end

    subgraph "Infrastructure Layer"
        N[(PostgreSQL<br/>Primary DB)]
        O[(H2<br/>Dev DB)]
        P[(Redis<br/>Cache & Locks)]
        Q[(Kafka<br/>Event Streaming)]
        R[XXL-Job<br/>Task Scheduler]
        S[Monitoring Stack<br/>Prometheus/Grafana]
    end

    A & B & C --> D
    A & B & C --> E
    
    D --> F & G & H & J
    E --> L & M
    
    H --> I
    I --> Q
    Q --> L & K & M
    
    F & G & H --> N
    F & G & H --> O
    J --> P
    K --> R
    
    style I fill:#ff6b6b
    style Q fill:#4ecdc4
    style N fill:#45b7d1

Tech Stack

Layer	Technology
Language	Java 17
Framework	Spring Boot 3.3.2, Spring Security, Spring Data JPA
API	RESTful APIs, WebSocket, OpenAPI/Swagger
Database	PostgreSQL (Production), H2 (Development)
Caching	Redis (Distributed Cache & Locks)
Messaging	Apache Kafka (Event Streaming)
Task Scheduling	XXL-Job (Distributed Tasks)
Security	JWT Authentication, Spring Security
Monitoring	Prometheus, Grafana, OpenTelemetry
Logging	SLF4J, Logback, ELK Stack
Build	Maven 3.9+
Containerization	Docker, Docker Compose
Orchestration	Kubernetes, Helm
Testing	JUnit 5, Testcontainers, MockMvc

Getting Started

Prerequisites

Java 17+ (OpenJDK recommended)
Maven 3.9+
Docker & Docker Compose (for infrastructure)
Git (for version control)
(Optional) Kubernetes + Helm (for production deployment)

Quick Setup

# 1. Clone the repository
git clone https://github.com/waynetyou/mini-exchange-backend.git
cd mini-exchange-backend

# 2. Build the project
./mvnw clean compile

# 3. Run tests
./mvnw test

# 4. Start the application (Development mode with H2 database)
./mvnw spring-boot:run

Access Points

Once the application is running, you can access:

Service	URL	Description
REST API	`http://localhost:9977/api`	Main API endpoints
H2 Console	`http://localhost:9977/api/h2-console`	Database console (dev only)
Swagger UI	`http://localhost:9977/swagger-ui/index.html`	API documentation
Actuator	`http://localhost:9977/api/actuator`	Health checks & metrics
WebSocket	`ws://localhost:9977/ws`	Real-time data stream

Docker Setup (Optional)

# Build Docker image
docker build -t mini-exchange-backend .

# Run with Docker Compose (includes PostgreSQL, Redis, Kafka)
docker-compose up -d

# View logs
docker-compose logs -f mini-exchange-backend

Module Structure

The project follows a Domain-Driven Design (DDD) approach with clear module separation:

mini-exchange-backend/
├── README.md
├── pom.xml                          # Maven dependencies & plugins
├── docker-compose.yml               # Development infrastructure
├── 
├── src/main/java/io/tyou/mini_exchange_backend/
│   ├── MiniExchangeBackendApplication.java    # Spring Boot main class
│   │
│   ├── auth/                        # Authentication & Authorization
│   │   ├── controller/              # JWT, login/logout endpoints  
│   │   ├── service/                 # User management, security logic
│   │   ├── entity/                  # User, Role, Permission entities
│   │   ├── repository/              # Data access layer
│   │   └── dto/                     # API request/response objects
│   │
│   ├── account/                     # Account & Asset Management
│   │   ├── controller/              # Balance, deposit/withdraw APIs
│   │   ├── service/                 # Ledger logic, fund operations
│   │   ├── entity/                  # Account, Balance, Transaction
│   │   ├── repository/              # Account data persistence
│   │   └── dto/                     # Account-related DTOs
│   │
│   ├── order/                       # Order Management
│   │   ├── controller/              # Place/cancel/query orders
│   │   ├── service/                 # Order lifecycle management
│   │   ├── entity/                  # Order, OrderStatus entities
│   │   ├── repository/              # Order data persistence
│   │   └── dto/                     # Order request/response DTOs
│   │
│   ├── match/                       # Matching Engine
│   │   ├── engine/                  # Core matching algorithms
│   │   ├── service/                 # Order book management
│   │   ├── dto/                     # Trade, OrderBook DTOs
│   │   └── event/                   # Matching events
│   │
│   ├── risk/                        # Risk Management
│   │   ├── service/                 # Risk validation logic
│   │   ├── engine/                  # Risk calculation engine
│   │   ├── dto/                     # Risk assessment DTOs
│   │   └── config/                  # Risk parameters
│   │
│   ├── clearing/                    # Clearing & Settlement
│   │   ├── service/                 # Settlement logic
│   │   ├── job/                     # Scheduled settlement tasks
│   │   ├── entity/                  # Settlement records
│   │   └── repository/              # Settlement data access
│   │
│   ├── market/                      # Market Data Service
│   │   ├── service/                 # Market data aggregation
│   │   ├── websocket/               # WebSocket endpoints
│   │   ├── dto/                     # Market data DTOs
│   │   └── publisher/               # Real-time data publishing
│   │
│   ├── notification/                # Notification Service
│   │   ├── service/                 # Message delivery
│   │   ├── channel/                 # Email, SMS, Push channels
│   │   └── template/                # Message templates
│   │
│   ├── admin/                       # Admin Management
│   │   ├── controller/              # Admin APIs
│   │   ├── service/                 # Admin operations
│   │   └── dto/                     # Admin DTOs
│   │
│   ├── api/                         # Global API Layer
│   │   ├── controller/              # Health check, global endpoints
│   │   ├── exception/               # Global exception handling
│   │   ├── dto/                     # Common API DTOs
│   │   └── response/                # Standardized API responses
│   │
│   ├── infra/                       # Infrastructure Layer
│   │   ├── config/                  # Spring configuration
│   │   ├── kafka/                   # Kafka producers/consumers
│   │   ├── redis/                   # Redis operations
│   │   ├── job/                     # XXL-Job integration
│   │   ├── security/                # Security configurations
│   │   └── util/                    # Utility classes
│   │
│   ├── common/                      # Shared Components
│   │   ├── constant/                # Application constants
│   │   ├── util/                    # Common utilities
│   │   ├── dto/                     # Shared DTOs
│   │   └── exception/               # Business exceptions
│   │
│   └── logging/                     # Logging Configuration
│       ├── aspect/                  # Logging aspects
│       ├── config/                  # Log configuration
│       └── formatter/               # Custom formatters
│
└── src/main/resources/
    ├── application.yml              # Multi-environment configuration
    ├── logback-spring.xml           # Logging configuration
    ├── schema/                      # Database schema files
    │   ├── schema.sql              # DDL scripts
    │   └── data.sql                # Initial data
    └── static/                      # Static resources

Testing Strategy

Running Tests

# Run all tests
./mvnw test

# Run tests with coverage report
./mvnw test jacoco:report

# Run only unit tests
./mvnw test -Dtest="**/*Test"

# Run only integration tests
./mvnw test -Dtest="**/*IT"

Test Architecture

Test Type	Framework	Purpose
Unit Tests	JUnit 5 + Mockito	Service layer logic, utilities
Integration Tests	Spring Boot Test + Testcontainers	API endpoints, database operations
Repository Tests	@DataJpaTest	JPA repositories, custom queries
Web Layer Tests	@WebMvcTest	Controllers, REST API validation
Security Tests	Spring Security Test	Authentication, authorization

Test Containers Setup

The project uses Testcontainers for integration testing with real databases:

@SpringBootTest
@Testcontainers
class OrderServiceIntegrationTest {
    
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")
            .withDatabaseName("testdb")
            .withUsername("test")
            .withPassword("test");
            
    // Integration tests here...
}

Monitoring & Observability

Health Checks

Access health information via Spring Boot Actuator:

# Application health
curl http://localhost:9977/api/actuator/health

# Detailed health (includes database, components)
curl http://localhost:9977/api/actuator/health?details=true

# Application metrics
curl http://localhost:9977/api/actuator/metrics

Metrics & Monitoring

Component	Endpoint	Purpose
Prometheus	`/actuator/prometheus`	Application metrics
Health Check	`/actuator/health`	Service health status
Info	`/actuator/info`	Application information
Metrics	`/actuator/metrics`	Custom business metrics

Distributed Tracing

OpenTelemetry integration for request tracing
Correlation IDs for request tracking across services
Structured logging with JSON format for ELK stack

Custom Metrics

The application exposes business-specific metrics:

// Order processing metrics
order.placed.total
order.cancelled.total
order.matched.total

// Matching engine metrics
matching.latency.seconds
matching.throughput.orders_per_second

// Account metrics
account.balance.updates.total
account.funds.locked.total

Development Workflow

Environment Profiles

Profile	Database	Cache	Description
dev	H2 (in-memory)	Local	Development with H2 console
test	H2 (in-memory)	Local	Testing environment
prod	PostgreSQL	Redis	Production environment

Configuration Management

# application.yml - Environment-specific configurations
spring:
  profiles:
    active: dev  # Default profile

---
# Development Profile
spring:
  config:
    activate:
      on-profile: dev
  datasource:
    url: jdbc:h2:mem:testdb
    # ... H2 configuration

---
# Production Profile  
spring:
  config:
    activate:
      on-profile: prod
  datasource:
    url: jdbc:postgresql://localhost:5432/mini_exchange
    # ... PostgreSQL configuration

Hot Reload Development

# Enable Spring Boot DevTools for hot reload
./mvnw spring-boot:run -Dspring.devtools.restart.enabled=true

# Watch for file changes and auto-restart
./mvnw compile spring-boot:run

Deployment

Docker Deployment

# Build application image
docker build -t mini-exchange-backend:latest .

# Run with dependencies using Docker Compose
docker-compose up -d

# Scale services
docker-compose up -d --scale mini-exchange-backend=3

Kubernetes Deployment

# Apply Kubernetes manifests
kubectl apply -f k8s/

# Deploy with Helm (coming soon)
helm install mini-exchange ./helm-chart

Environment Variables

Variable	Description	Default
`SPRING_PROFILES_ACTIVE`	Active Spring profile	`dev`
`DB_HOST`	Database hostname	`localhost`
`DB_PORT`	Database port	`5432`
`DB_NAME`	Database name	`mini_exchange`
`REDIS_HOST`	Redis hostname	`localhost`
`REDIS_PORT`	Redis port	`6379`
`KAFKA_BROKERS`	Kafka broker addresses	`localhost:9092`

Roadmap

Phase 1: Core Foundation ✅

Project structure and basic Spring Boot setup
Authentication & authorization framework
Database integration (H2 dev, PostgreSQL prod)
REST API foundation with OpenAPI documentation
Basic testing framework

Phase 2: Trading Core 🚧

Phase 3: Advanced Features 📋

Phase 4: Infrastructure & Scaling 🎯

Phase 5: Production Ready 🚀

Development Setup

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Ensure all tests pass: ./mvnw test
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Code Standards

Follow Google Java Style Guide
Maintain 80%+ test coverage
Write clear commit messages
Update documentation for new features

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Spring Boot community for excellent documentation
Testcontainers for integration testing capabilities
Apache Kafka for event streaming architecture
All contributors who help improve this project

⭐ Star this repo if you find it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.mvn/wrapper		.mvn/wrapper
docker/postgres/init		docker/postgres/init
docs		docs
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

License

uihctyou/mini-exchange-backend

Folders and files

Latest commit

History

Repository files navigation

Mini Exchange Backend

Features

Architecture

Tech Stack

Getting Started

Prerequisites

Quick Setup

Access Points

Docker Setup (Optional)

Module Structure

Testing Strategy

Running Tests

Test Architecture

Test Containers Setup

Monitoring & Observability

Health Checks

Metrics & Monitoring

Distributed Tracing

Custom Metrics

Development Workflow

Environment Profiles

Configuration Management

Hot Reload Development

Deployment

Docker Deployment

Kubernetes Deployment

Environment Variables

Roadmap

Phase 1: Core Foundation ✅

Phase 2: Trading Core 🚧

Phase 3: Advanced Features 📋

Phase 4: Infrastructure & Scaling 🎯

Phase 5: Production Ready 🚀

Development Setup

Code Standards

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages