CryptoFlash

CryptoFlash is a distributed, high-frequency trading (HFT) simulation platform engineered for ultra-low latency, deterministic order matching, and resilient event settlement. The system employs a bifurcated architectural model that strictly separates the synchronous "hot-path" of trade execution from the asynchronous "cold-path" of data persistence and historical auditing.

---

Academic Context

This project is submitted as part of the evaluation process for the Large Scale and Multi-Structured Databases course, taught by Prof. Pietro Ducange at the University of Pisa, during the Master's Degree course in Artificial Intelligence and Data Engineering, Academic Year 2025/2026.

Group Members:

• Chandrakant Yadav;
• Pedro Carneiro Junior.

---

Architecture

Overview

CryptoFlash is built upon a modular, layered Spring Boot service architecture, prioritizing structural separation of concerns and non-blocking I/O.

• Hot Path (In-Memory Tier): Leverages Redis with custom Lua scripts for atomic, thread-safe order matching and volatile state management.
• Cold Path (Persistence Tier): Employs MongoDB for durable storage, utilizing event-sourced patterns to ensure transactional finality and auditability.
• Messaging Backbone: Uses Redis Streams for reliable, decoupled communication between the execution engine and background settlement workers.

Highlights

• Core Technology Stack: The platform is built using Spring Boot, leveraging Redis as the high-velocity "Hot Store" and MongoDB as the durable "Cold Store."

• Consistency via Event-Driven Design: The system utilizes an Event-Driven Architecture to solve the dual-write consistency problem at scale.

• CQRS Pattern Implementation: By applying a strict Command Query Responsibility Segregation (CQRS) pattern, the system isolates high-velocity matching commands in Redis from analytical queries in MongoDB.

• Performance Optimization: This design ensures the order-matching engine remains ultra-responsive by offloading historical logging, reporting, and settlement tasks to an asynchronous background layer.

---

Core Features

• Atomic Matching Engine: Server-side Lua scripting (match_order.lua) ensures microsecond-level matching while preventing race conditions and double-allocation.
• Exactly-Once Settlement: Implements manual acknowledgment modes and unique trade identifiers (tradeId) to guarantee system integrity against duplicate message processing.
• Embedded Asset Modeling: Utilizes MongoDB’s document-level atomicity by embedding wallet structures directly within user documents, eliminating the need for complex, cross-collection distributed transactions.
• Stateless API: Declarative REST controllers expose a secure, high-throughput interface for system interaction.

---

Technical Stack

• Backend: Java 17+, Spring Boot
• Build System: Apache Maven
• In-Memory Store: Redis (with spring-boot-starter-data-redis-reactive)
• Document Store: MongoDB (with spring-boot-starter-data-mongodb)
• Scripting: Lua (for Redis-side atomicity)
• Deployment: Docker / Docker Compose

---

Development

• Configuration: Externalized environmental management via application.yml.
• Modularity: Seven specialized packages (config, controller, dto, model, repository, service, worker) enforce clean architectural boundaries.

---

Getting Started

CryptoFlash is designed for containerized deployment. Ensure you have Docker and Docker Compose installed on your machine.

1. Clone the Repository:

   git clone <repository-url>
   cd cryptoflash

2. Start the Infrastructure: The project includes a docker-compose-dev.yml file to spin up the required Redis and MongoDB instances.

   docker-compose -f docker-compose-dev.yml up -d

3. Run the Application: You can run the Spring Boot application directly via Maven:

   ./mvnw spring-boot:run

   The application will automatically connect to the services defined in the compose file and initialize the necessary Redis consumer groups and database collections.

---

API Quick Guide

The CryptoFlash platform exposes a RESTful API to interact with the matching engine and view system metrics.

Method	Endpoint	Description
POST	/api/v1/orders	Places a new limit order (requires JSON payload).
GET	/api/v1/market/depth/{symbol}	Retrieves the current order book depth for a symbol.
GET	/api/v1/users/{id}/wallet	Returns the current balance state for a user.
GET	/api/v1/users/{id}/history	Fetches historical trade executions for a specific user.
GET	/api/v1/system/health	Checks the connectivity status of Redis and MongoDB.

Detailed API specifications are available via the OpenAPI interface at /swagger-ui.html once the application is running.