# ymidortega/titaniumboe-sim architecture

> Architecture diagram of the GitHub repository ymidortega/titaniumboe-sim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ymidortega/titaniumboe-sim
- Repository: https://github.com/ymidortega/titaniumboe-sim

## Overview

##### Project Type and Purpose
- This is a full-stack, enterprise-grade **trading infrastructure simulator** for the Cboe Titanium BOE protocol.
- It bundles a **binary TCP server** (the BOE Server), **REST API & WebSocket** endpoints, **interactive CLI** client, client SDK, **trading bots**, real-time **matching engine**, and **persistent storage** (RocksDB).

##### File Structure
Top-level directories of interest:
· src/main/java/com/boe/simulator/api → REST controllers, DTOs, WebSocket handlers
· src/main/java/com/boe/simulator/server → TCP connection, matching engine, order management, authentication, rate limiting, session management, persistence service
· src/main/java/com/boe/simulator/client → BOE protocol client SDK and interactive CLI
· src/main/java/com/boe/simulator/bot → Automated trading bots with pluggable strategies
· src/main/java/com/boe/simulator/protocol → Message definitions, factories, serialization
· src/main/java/com/boe/simulator/server/persistence → RocksDB configuration, repositories, services
Additional: configuration and build scripts (Dockerfile, docker-compose.yml, pom.xml), docs, CI/CD workflows.

##### README Insights
- Confirms components: **Interactive CLI**, **BOE Server (Ports 8080 TCP / 8081 HTTP)**, **Matching Engine**, **Trading Bots**, **RocksDB**.
- Mentions tech stack: Java 21, Maven, Javalin for REST & WebSocket, BCrypt, rate limiter, Jackson, JUnit/Mockito.
- Provides a sketch of architecture tying CLI → Server → matching, bots, and DB.

##### Main Components & Boundaries
A. Clients
- Interactive CLI (uses BOE client SDK over TCP)
- REST API & WebSocket consumers (e.g., third-party UIs, monitoring tools)
B. BOE Server
- TCP Connection Handler (port 8080)
- Authentication & Rate Limiting
- Session Management & Heartbeat Monitor
- Matching Engine & Order Manager
- Trading Bots (internal modules invoking matching engine)
- REST API & WebSocket Layer (port 8081 via Javalin)
- Persistence Layer (RocksDB via repository services)
- Metrics & Health
C. Protocol Layer
- Message Factory, Serializer, Session Manager
D. Data Stores & External Services
- Embedded RocksDB
- External configuration (via file or environment)

##### Relationships & Data Flows
- **Interactive CLI** ←TCP binary BOE protocol→ **BOE Server (Connection Handler → Protocol → Authentication → Session)**
- **REST API** & **WebSocket** ←HTTP/WS→ **API Layer** → Service Layer → OrderManager/PositionService → Persistence
- **Trading Bots** invoke the Matching Engine directly in-process (simulate market participants)
- **Matching Engine** publishes trade events to connected WebSocket sessions and persists executions
- **Persistence Services** write audit, sessions, user, trades into RocksDB

##### Architectural Patterns & Principles
- **Layered Architecture**: Presentation (CLI / REST / WS) → Application (Controllers, Services) → Domain (Matching, Orders, Bots) → Infrastructure (Persistence, Networking)
- **Hexagonal/Ports-and-Adapters** feel: protocol adapters (TCP, HTTP, WebSocket) plug into core services
- **Separation of Concerns**: distinct modules for API, core server logic, protocol, client SDK, bots
- **Event-Driven Flow**: matching engine publishes updates to WebSocket subscribers and persistence listeners
- **Security & Resilience**: authentication filter, CORS, rate limiter, error handlers

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        CLI["Interactive CLI Client"]:::adapter
        RESTClient["REST API Consumer"]:::adapter
        WSClient["WebSocket Consumer"]:::adapter
    end

    %% BOE Client SDK
    subgraph "BOE Client SDK"
        BoeClient["BoeClient (SDK)"]:::adapter
        ConnHandlerClient["BoeConnectionHandler"]:::adapter
        ClientHB["ClientHeartbeatManager"]:::adapter
    end

    %% BOE Server
    subgraph "BOE Server"
        CboeServer["CboeServer"]:::infra

        subgraph "TCP Layer"
            ServerConn["ClientConnectionHandler"]:::infra
        end

        subgraph "API Layer"
            AuthService["AuthenticationService"]:::infra
            AuthFilter["AuthenticationFilter"]:::infra
            RateLimiter["RateLimiter"]:::infra
        end

        subgraph "Session & Heartbeat"
            SessionMgr["ClientSessionManager"]:::infra
            HBMonitor["HeartbeatMonitor"]:::infra
        end

        subgraph "Domain Core"
            Matching["MatchingEngine"]:::core
            OrderMgr["OrderManager"]:::core
            BotMgr["BotManager"]:::core
            Strategy["TradingStrategy"]:::core
        end

        subgraph "REST/WebSocket"
            RestServer["RestApiServer"]:::adapter
            OrderCtrl["OrderController"]:::adapter
            DTOs["DTOs"]:::adapter
            WSHandler["WebSocketHandler"]:::adapter
            WSMsg["TradeUpdateMessage"]:::adapter
        end

        subgraph "Protocol"
            MsgFactory["BoeMessageFactory"]:::infra
            SessionProt["BoeSessionManager"]:::infra
            Serializer["BoeMessageSerializer"]:::infra
        end

        subgraph "Persistence"
            DBMgr["RocksDBManager"]:::infra
            SessionRepo["SessionRepository"]:::infra
            AuditRepo["AuditRepository"]:::infra
            MsgLogger["MessageLogger"]:::infra
        end

        Health["HealthMetrics"]:::infra
    end

    %% Connections: Client SDK to Server
    CLI -->|BOE TCP| BoeClient
    BoeClient --> ConnHandlerClient
    ConnHandlerClient --> ClientHB
    ConnHandlerClient -->|connects| ServerConn

    %% TCP Flow inside server
    ServerConn --> AuthService
    AuthService --> RateLimiter
    RateLimiter --> SessionMgr
    SessionMgr --> HBMonitor
    ServerConn --> MsgFactory
    MsgFactory --> Serializer
    Serializer --> SessionProt
    SessionProt --> SessionMgr

    %% Domain interactions
    SessionMgr --> Matching
    Matching --> OrderMgr
    BotMgr --> Matching

    %% Persistence events
    Matching --> MsgLogger
    OrderMgr --> DBMgr
    MsgLogger --> AuditRepo
    DBMgr --> SessionRepo

    %% REST/WebSocket Flow
    RESTClient -->|HTTP REST| RestServer
    RestServer --> AuthFilter
    AuthFilter --> RateLimiter
    RateLimiter --> OrderCtrl
    OrderCtrl -->|uses| DTOs
    OrderCtrl --> OrderMgr
    Matching -->|publishes| WSHandler
    WSHandler -->|JSON WS| WSClient
    WSHandler --> WSMsg

    %% Health metrics
    CboeServer --> Health

    %% Click Events
    click CLI "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/client/interactive/InteractiveCLI.java"
    click BoeClient "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/client/BoeClient.java"
    click ConnHandlerClient "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/client/connection/BoeConnectionHandler.java"
    click ClientHB "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/client/heartbeat/ClientHeartbeatManager.java"
    click CboeServer "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/CboeServer.java"
    click ServerConn "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/connection/ClientConnectionHandler.java"
    click AuthService "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/auth/AuthenticationService.java"
    click AuthFilter "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/api/middleware/AuthenticationFilter.java"
    click RateLimiter "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/ratelimit/RateLimiter.java"
    click SessionMgr "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/session/ClientSessionManager.java"
    click HBMonitor "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/heartbeat/HeartbeatMonitor.java"
    click Matching "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/matching/MatchingEngine.java"
    click OrderMgr "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/order/OrderManager.java"
    click BotMgr "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/bot/BotManager.java"
    click Strategy "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/bot/strategy/TradingStrategy.java"
    click RestServer "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/api/RestApiServer.java"
    click OrderCtrl "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/api/controller/OrderController.java"
    click DTOs "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/api/dto/OrderRequest.java"
    click WSHandler "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/api/websocket/WebSocketHandler.java"
    click WSMsg "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/api/websocket/dto/TradeUpdateMessage.java"
    click MsgFactory "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/protocol/message/BoeMessageFactory.java"
    click SessionProt "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/protocol/message/BoeSessionManager.java"
    click Serializer "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/protocol/serialization/BoeMessageSerializer.java"
    click DBMgr "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/persistence/RocksDBManager.java"
    click SessionRepo "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/persistence/repository/SessionRepository.java"
    click AuditRepo "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/persistence/repository/AuditRepository.java"
    click MsgLogger "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/persistence/service/MessageLogger.java"
    click Health "https://github.com/ymidortega/titaniumboe-sim/blob/main/src/main/java/com/boe/simulator/server/metrics/HealthMetrics.java"

    %% Styles
    classDef adapter fill:#ACE7EF,stroke:#036b74,color:#000;
    classDef core fill:#B2F2B6,stroke:#2b6f2b,color:#000;
    classDef infra fill:#FFD8A8,stroke:#a35f00,color:#000;
```
