Order Command Service

Order Command Service

The Order Command Service is the entry gateway for trade command intake in the Emporia Trading Platform. It provides RESTful APIs for placing, modifying, and cancelling orders, validates incoming orders against static exchange listings, and correlates asynchronous Kafka command execution outcomes back to clients.

---

📌 Service Specifications

• Directory: order-command-service
• HTTP Port: 8085
• Database Boundary: Stateless (No database; uses in-memory ConcurrentHashMap for command-result correlation).
• Primary Roles:
  • Expose REST API endpoints (POST /orders, PUT /orders/{id}, POST /orders/{id}/cancel, POST /orders/cancel-all).
  • Validate JWT security context and trader role (ROLE_TRADER).
  • Fetch instrument listing snapshots from static-data-service (:8081).
  • Construct OrderCommand Kafka messages and produce them to emporia.order.commands.v1.
  • Correlate Kafka processing results from emporia.order.results.v1 via KafkaCommandGateway within a configurable timeout (default 8s).

---

🏗️ Architecture & Component Flow

sequenceDiagram
    autonumber
    actor Client as Trader / React UI
    participant Ctrl as OrderCommandController (:8085)
    participant StaticClient as StaticDataClient
    participant StaticData as Static Data Service (:8081)
    participant Gateway as KafkaCommandGateway
    participant KafkaCmds as Kafka (emporia.order.commands.v1)
    participant OMS as Order Management Service (:8086)
    participant KafkaResults as Kafka (emporia.order.results.v1)

    Client->>Ctrl: POST /orders (CreateOrderRequest)
    Ctrl->>Ctrl: Validate JWT & trader role
    Ctrl->>StaticClient: get(listingId, bearerToken)
    StaticClient->>StaticData: GET /listings/{id}
    StaticData-->>StaticClient: ListingSnapshot
    Ctrl->>Gateway: send(OrderCommand)
    Gateway->>KafkaCmds: Publish OrderCommand (commandId)
    KafkaCmds->>OMS: Consume OrderCommand
    OMS->>OMS: Execute OrderCommandHandler
    OMS->>KafkaResults: Publish OrderCommandResult (commandId, success, status, payload)
    KafkaResults->>Gateway: @KafkaListener result(OrderCommandResult)
    Gateway-->>Ctrl: Complete CompletableFuture<OrderCommandResult>
    Ctrl-->>Client: 201 Created (OrderView JSON)

Loading

---

🛠️ API Endpoints

Method	Path	Request Body	Description
POST	/orders	CreateOrderRequest	Places a new order. Validates listing, assigns orderId, and routes to DMA, SMART, or VWAP.
PUT	/orders/{id}	ModifyOrderRequest	Modifies an existing order's requested quantity or limit price with optimistic version check (expectedVersion).
POST	/orders/{id}/cancel	None	Cancels an active order by orderId.
POST	/orders/cancel-all	None	Bulk cancels all active orders for the authenticated trader / desk.

---

⚡ Asynchronous Correlation Gateway (KafkaCommandGateway.java)

Because order command processing across Kafka is inherently asynchronous, order-command-service implements an in-memory Correlation Gateway Pattern to provide synchronous HTTP responses to clients:

1. Pending Correlation Registration: When send(OrderCommand) is called, a CompletableFuture<OrderCommandResult> is registered in a thread-safe ConcurrentHashMap keyed by commandId.
2. Kafka Dispatch: The OrderCommand is sent to topic emporia.order.commands.v1, partitioned by orderId (or userSubject).
3. Kafka Reply Listener: An @KafkaListener listens on emporia.order.results.v1 (with an isolated group ID order-command-service-${random.uuid}).
4. Completion & Timeout: When a matching OrderCommandResult arrives, the corresponding CompletableFuture is completed. If OMS fails to respond within 8 seconds, a 504 Gateway Timeout exception is thrown.