AEGIS Cloud Trading Platform

Enterprise-Grade Cloud Trading Platform with Institutional Risk Controls

---

📖 Table of Contents

• About the Project
• Key Features
• Architecture
• Technology Stack
• Getting Started
• Project Structure
• Trading Engine Pipeline
• Security & Compliance
• API Documentation
• Contributing
• License

---

🎯 About the Project

AEGIS (Advanced Electronic Global Investment System) is a modern, cloud-native trading platform designed with institutional-grade risk controls and regulatory compliance at its core. Built on event-driven microservices architecture, AEGIS provides real-time order processing, immutable audit trails, and comprehensive risk management.

🏛️ Project Purpose

The platform was developed to address critical gaps in retail and institutional trading systems:

1. Regulatory Compliance First: Built-in compliance checks ensure all trades adhere to regulatory requirements before execution (KYC, sanctions screening, trading windows, position limits).

2. Multi-Layer Risk Management: Sophisticated risk engine prevents catastrophic losses through real-time balance verification, exposure limits, concentration risks, and rate limiting.

3. Immutable Audit Trail: Every transaction is recorded in an immutable hashchain ledger, providing cryptographic proof of trade integrity for audits and regulatory reporting.

4. Real-Time Processing: Event-driven architecture powered by Kafka enables microsecond-latency trade processing and real-time risk assessments.

5. Institutional Controls: Implements controls typically found in institutional trading systems: pre-trade risk checks, compliance reviews, order size limits, and execution price validation.

🎯 Target Use Cases

• Proprietary Trading Firms: Real-time risk controls and P&L tracking
• Wealth Management Platforms: Client order management with compliance oversight
• Broker-Dealers: Multi-client trading with regulatory reporting
• FinTech Startups: Production-ready trading infrastructure
• Educational Institutions: Teaching platform for trading systems architecture

---

✨ Key Features

🔒 Three-Engine Validation Architecture

Every order passes through three independent validation engines in sequence:

1. Compliance Engine 🛡️

   • Symbol whitelist enforcement (10 approved instruments)
   • User sanctions screening (OFAC, EU sanctions lists)
   • Trading window restrictions (maintenance windows, market hours)
   • Crypto position limits (BTC: 10 max, ETH: 100 max)
   • Large order flagging for manual review

2. Risk Engine ⚖️

   • Real-time balance verification
   • Position size limits (BTC: 5 max per order)
   • Notional value limits ($250k per order)
   • Daily trading limits ($1M per day)
   • Exposure limits ($500k total open positions)
   • Rate limiting (10 orders per minute)
   • Slippage tolerance checks (0.5% max)

3. Execution Engine 🎯

   • Market impact modeling (spread + slippage)
   • Realistic price execution simulation
   • Trade confirmation and settlement
   • Balance debit/credit accounting
   • Immutable ledger recording

📊 Trading Features

• Multi-Asset Support: Equities (AAPL, MSFT, GOOGL, etc.) and Cryptocurrencies (BTC, ETH)
• Real-Time Market Data: Live price feeds for all instruments
• Order Management: Full order lifecycle (PENDING → ACCEPTED → EXECUTED/REJECTED)
• Balance Management: Real-time balance tracking with available/reserved funds
• Transaction History: Complete audit trail with CSV/PDF export
• Immutable Ledger: Cryptographic hashchain for trade verification

🔐 Security & Compliance

• JWT Authentication: Secure token-based authentication
• Role-Based Access Control: User permissions and access levels
• Audit Logging: Structured logging for all system events
• Data Encryption: Secure communication between services
• Immutable Records: Hashchain-based ledger prevents tampering

---

🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend (Next.js)                       │
│                    http://localhost:3000                         │
└────────────────────────────┬────────────────────────────────────┘
                             │ REST API
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│                      API Gateway (FastAPI)                       │
│                    http://localhost:8000                         │
└────────────────────────────┬────────────────────────────────────┘
                             │ Kafka Events
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│                     Order Processor (Worker)                     │
│                                                                   │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
│  │  Compliance  │ -> │     Risk     │ -> │  Execution   │      │
│  │    Engine    │    │    Engine    │    │    Engine    │      │
│  └──────────────┘    └──────────────┘    └──────────────┘      │
│                             │                     │              │
│                             ↓                     ↓              │
│                      ┌─────────────┐      ┌─────────────┐       │
│                      │  Balance    │      │   Ledger    │       │
│                      │   Update    │      │  (Hashchain)│       │
│                      └─────────────┘      └─────────────┘       │
└─────────────────────────────────────────────────────────────────┘
                             │
                             ↓
┌──────────────┬──────────────┬──────────────┬──────────────┐
│  PostgreSQL  │    Redis     │   Redpanda   │   Adminer    │
│   (Data)     │   (Cache)    │   (Kafka)    │    (UI)      │
│   :5432      │   :6379      │   :9092      │   :8081      │
└──────────────┴──────────────┴──────────────┴──────────────┘

Event-Driven Flow

1. User places order → 2. API validates & publishes to Kafka
                        ↓
3. Worker consumes event → 4. Compliance Engine validates
                        ↓
5. Risk Engine checks limits → 6. Execution Engine processes
                        ↓
7. Update balances → 8. Write to ledger → 9. Notify user

---

🛠️ Technology Stack

Frontend

• Next.js 14 - React framework with server-side rendering
• TypeScript - Type-safe development
• Tailwind CSS - Modern, responsive design
• jsPDF - PDF export functionality

Backend

• FastAPI - High-performance Python web framework
• Python 3.12 - Latest Python features and performance
• Pydantic - Data validation using Python type annotations
• psycopg3 - PostgreSQL database adapter

Infrastructure

• PostgreSQL 17 - Primary database for orders, users, balances
• Redis 7 - Caching and rate limiting
• Redpanda - Kafka-compatible event streaming (simpler than Kafka)
• Docker Compose - Container orchestration

Development Tools

• Adminer - Database management UI
• Structured Logging - JSON-based logging for observability
• Hot Reload - Fast development iteration

---

🚀 Getting Started

Prerequisites

• Docker Desktop (or Docker Engine + Docker Compose)
• Git
• Ports Available: 3000, 8000, 8081, 5432, 6379, 9092

Quick Start

1. Clone the repository

   git clone https://github.com/yourusername/aegis-cloud-trading-platform.git
   cd aegis-cloud-trading-platform

2. Start all services

   docker-compose up -d

3. Wait for services to be healthy (~30 seconds)

   docker-compose ps

4. Access the platform

   • Trading UI: http://localhost:3000
   • API Docs: http://localhost:8000/docs
   • Database UI: http://localhost:8081 (PostgreSQL: app/app)

5. Create an account

   • Navigate to http://localhost:3000/register
   • Register a new user
   • Initial balance: $100,000 USD

Useful Commands

# View logs from all services
docker-compose logs -f

# View logs from specific service
docker-compose logs -f back-worker

# Rebuild after code changes
docker-compose build
docker-compose up -d

# Stop all services
docker-compose down

# Stop and remove all data
docker-compose down -v

# Execute commands in containers
docker exec -it aegis-cloud-trading-platform-postgres-1 psql -U app -d trading

---

📁 Project Structure

aegis-cloud-trading-platform/
├── back/                           # Backend services
│   ├── app/
│   │   ├── api/                    # REST API endpoints
│   │   │   └── routes/
│   │   │       ├── auth.py         # Authentication (register, login)
│   │   │       ├── orders.py       # Order management
│   │   │       ├── symbols.py      # Market data
│   │   │       ├── balance.py      # Account balances
│   │   │       └── ledger.py       # Transaction history
│   │   ├── engines/                # Trading engines
│   │   │   ├── compliance.py       # Regulatory validation
│   │   │   ├── risk.py             # Risk management
│   │   │   └── execution.py        # Trade execution
│   │   ├── workers/                # Kafka consumers
│   │   │   └── processor.py        # Main order processor
│   │   ├── core/                   # Core utilities
│   │   │   ├── config.py           # Configuration
│   │   │   ├── security.py         # JWT authentication
│   │   │   └── logging.py          # Structured logging
│   │   ├── domain/                 # Domain models
│   │   │   └── models.py           # Pydantic models
│   │   ├── infra/                  # Infrastructure
│   │   │   ├── db/                 # Database
│   │   │   │   ├── init.sql        # Schema & seed data
│   │   │   │   └── session.py      # Connection pool
│   │   │   ├── broker/             # Kafka
│   │   │   │   ├── producer.py     # Event publishing
│   │   │   │   └── consumer.py     # Event consumption
│   │   │   └── redis/              # Cache
│   │   │       └── client.py       # Redis operations
│   │   ├── utils/                  # Utilities
│   │   │   └── hashchain.py        # Ledger hashing
│   │   └── main.py                 # FastAPI application
│   ├── Dockerfile                  # Backend container
│   └── requirements.txt            # Python dependencies
├── front/                          # Frontend application
│   ├── src/
│   │   ├── app/                    # Next.js pages
│   │   │   ├── login/              # Login page
│   │   │   ├── register/           # Registration page
│   │   │   ├── dashboard/          # Portfolio overview
│   │   │   ├── market/             # Market data & trading
│   │   │   ├── orders/             # Order management
│   │   │   ├── ledger/             # Transaction history
│   │   │   ├── layout.tsx          # Root layout
│   │   │   ├── page.tsx            # Landing page
│   │   │   └── globals.css         # Global styles
│   │   └── lib/
│   │       └── api.ts              # API client
│   ├── public/
│   │   └── brand/                  # Logo and branding
│   ├── Dockerfile                  # Frontend container
│   ├── package.json                # Node dependencies
│   ├── next.config.js              # Next.js config
│   └── tsconfig.json               # TypeScript config
├── docker-compose.yml              # Service orchestration
├── start.sh                        # Start script
├── stop.sh                         # Stop script
├── rebuild.sh                      # Rebuild script
└── README.md                       # This file

---

🔄 Trading Engine Pipeline

Order Processing Flow

# 1. API receives order
POST /orders {
  "symbol": "BTC",
  "side": "BUY",
  "quantity": 2.5
}

# 2. Publish to Kafka
kafka.publish('orders', order_event)

# 3. Worker consumes event
worker.process_order(order_event)

# 4. Compliance Engine
✓ Symbol in whitelist (BTC ✓)
✓ User not sanctioned
✓ Within trading window
✓ Quantity ≤ 10 BTC (2.5 ✓)
→ STATUS: ACCEPTED

# 5. Risk Engine
✓ Balance sufficient ($250k available, needs $212k)
✓ Order size ≤ 5 BTC (2.5 ✓)
✓ Notional ≤ $250k ($212k ✓)
✓ Daily limit ≤ $1M ($212k ✓)
✓ Exposure ≤ $500k ($212k + $0 existing ✓)
✓ Rate limit ≤ 10/min (1 ✓)
✓ Slippage ≤ 0.5% (0.025% ✓)
→ STATUS: ACCEPTED

# 6. Execution Engine
Market Price: $85,000.00
Spread (0.02%): +$17.00
Slippage (0.0251%): +$21.34
Execution Price: $85,038.34
Total Cost: $212,595.85
→ STATUS: EXECUTED

# 7. Balance Update
Before: $250,000.00
After:  $37,404.15
Reserved: $0.00

# 8. Ledger Entry
{
  "trade_id": "uuid",
  "order_id": "uuid",
  "symbol": "BTC",
  "quantity": 2.5,
  "exec_price": 85038.34,
  "spread_pct": 0.02,
  "slippage_pct": 0.0251,
  "prev_hash": "abc123...",
  "current_hash": "def456..."
}

Rejection Scenarios

# Insufficient Balance
Risk Engine → REJECTED
Reason: "Insufficient balance: available $10,000, required $212,596"

# Quantity Limit Exceeded
Risk Engine → REJECTED
Reason: "Quantity 6.0 exceeds limit 5.0 for BTC"

# Sanctioned User
Compliance Engine → REJECTED
Reason: "User on sanctions list"

# Symbol Not Allowed
Compliance Engine → REJECTED
Reason: "Trading symbol 'DOGE' is not allowed"

# Trading Window Closed
Compliance Engine → REJECTED
Reason: "Trading is disabled during maintenance (00:00-02:00 UTC)"

# Large Order Review
Compliance Engine → PENDING_REVIEW (Risk passed)
Reason: "Large BTC order (7.5 units) requires compliance review (threshold: 3.0)"

---

🔐 Security & Compliance

Compliance Checks

Check	Description	Example Limit
Symbol Whitelist	Only approved instruments can be traded	10 symbols (BTC, ETH, AAPL, etc.)
Sanctions Screening	Block sanctioned entities	OFAC, EU lists
Trading Windows	Restrict trading during maintenance	00:00-02:00 UTC blocked
Position Limits	Maximum position size per asset	BTC: 10, ETH: 100
Review Thresholds	Flag large orders for manual review	BTC > 3, ETH > 20

Risk Controls

Control	Purpose	Limit
Balance Check	Prevent overdrafts	Available balance
Order Size	Limit single order risk	BTC: 5 per order
Notional Limit	Cap order value	$250k per order
Daily Limit	Prevent excessive trading	$1M per day
Exposure Limit	Total open position risk	$500k total
Rate Limiting	Prevent order spam	10 orders/minute
Slippage Tolerance	Execution price protection	0.5% max

Authentication

• JWT Tokens: Secure, stateless authentication
• Password Hashing: bcrypt with salt
• Token Expiration: Configurable expiry
• Protected Routes: All trading endpoints require authentication

---

📚 API Documentation

Authentication

# Register
POST /auth/register
{
  "name": "John Doe",
  "username": "johndoe",
  "password": "securepassword123"
}

# Login
POST /auth/login
{
  "username": "johndoe",
  "password": "securepassword123"
}
→ Returns: { "access_token": "eyJ...", "token_type": "bearer" }

Orders

# Place Order
POST /orders
Authorization: Bearer <token>
{
  "symbol": "BTC",
  "side": "BUY",
  "quantity": 1.5
}

# Get Orders
GET /orders
Authorization: Bearer <token>

# Get Order Details
GET /orders/{order_id}
Authorization: Bearer <token>

Market Data

# Get All Symbols
GET /symbols

# Get Symbol Price
GET /symbols/{symbol}

Balance

# Get Balance
GET /balance
Authorization: Bearer <token>

# Get Transaction History
GET /balance/transactions
Authorization: Bearer <token>

Full API Documentation

Interactive API docs available at: http://localhost:8000/docs

---

🧪 Testing

Manual Testing

# Test order placement
curl -X POST http://localhost:8000/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "BTC", "side": "BUY", "quantity": 1.0}'

# Check order status
curl http://localhost:8000/orders/<order_id> \
  -H "Authorization: Bearer <token>"

# View balance
curl http://localhost:8000/balance \
  -H "Authorization: Bearer <token>"

Testing Scenarios

1. Normal Order: 1 BTC at market price
2. Large Order: 8 BTC (triggers compliance review)
3. Excessive Order: 15 BTC (rejected - exceeds max limit)
4. Insufficient Funds: Order exceeding available balance
5. Invalid Symbol: Try to trade "DOGE" (not whitelisted)
6. Rate Limiting: Place 15 orders in 1 minute

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

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

---

🙏 Acknowledgments

• Inspired by institutional trading systems
• Built with modern cloud-native practices
• Designed for educational and commercial use

---

📞 Contact

Project Maintainer: Olivier Dubo

For questions, suggestions, or support, please open an issue on GitHub.

---

AEGIS - Enterprise Trading Infrastructure

Built with ❤️ using FastAPI, Next.js, and Docker