Skip to main content

Feature Specification: Order Management and Matcher

Feature Branch: 008-order-management-matcher
Created: 2026-04-05
Status: Implemented
Input: Transition delta from 007-pricing-awareness-market-data

User Stories​

  • As a trader, I want to submit limit orders from a dedicated order ticket so market trades and limit orders are distinct workflows.
  • As a trader, I want an orders blotter view for my selected account so I can monitor and cancel outstanding orders without leaving the main trade page.
  • As an operations user, I want an admin view to inspect, filter, cancel, and force-fill orders across all accounts.
  • As a platform engineer, I want order-specific observability so queue depth and open/unfilled orders are visible at all times.
  • As a maintainer, I want this transition to remain spec-first, with order APIs/events/metrics documented before code generation.

Functional Requirements​

  • FR-01301: State introduces order lifecycle management with statuses: NEW, PARTIALLY_FILLED, FILLED, CANCELED, REJECTED.
  • FR-01302: State adds an order matcher component (Spring Boot) that evaluates open orders and emits fill outcomes.
  • FR-01303: State adds a dedicated order ticket in the trader UI for creating limit orders (security, side, quantity, limitPrice, accountId).
  • FR-01304: State adds an account-scoped orders blotter in the trader UI (tabbed with the trade blotter context) for viewing and canceling open orders.
  • FR-01305: State adds an order admin view in the web UI (Admin tab) for cross-account inspection plus cancel and force-fill actions.
  • FR-01306: Order submission, cancellation, and force-fill flows are exposed through order APIs and are propagated in realtime via messaging subjects.
  • FR-01308: Order data is persisted in the shared database so active orders survive order-matcher service restarts.
  • FR-01309: On every matcher tick, in-the-money orders are auto-filled with this policy: remaining < 1000 fills fully, otherwise fills half (rounded up).
  • FR-01310: Any order fill (auto-fill or force-fill) must submit a trade through trade-service so trade history and account positions are updated via the existing trade pipeline.
  • FR-01307: Existing pricing + trade + position flows from state 007 remain compatible unless explicitly changed in this pack.

Non-Functional Requirements​

  • NFR-01301: Observability stack from 006 remains intact and now covers order-management components and endpoints.
  • NFR-01302: Order matcher service exposes Prometheus metrics for order book depth and lifecycle transitions.
  • NFR-01303: A gauge metric reports open unfilled orders in near real time and is queryable in Grafana/Prometheus.
  • NFR-01304: Grafana includes order-management dashboards for open orders, fill/cancel rates, matcher latency, and error signals.
  • NFR-01305: Runtime and topology constraints are captured in system/runtime-topology.md.
  • NFR-01306: Architecture updates are encoded in system/architecture.model.json.
  • NFR-01307: Order matcher runtime uses Java 21 + Spring Boot for consistency with existing TraderX JVM services and shared operational patterns.

Success Criteria​

  • SC-01301: Generation hook exists and is runnable (pipeline/generate-state-008-order-management-matcher.sh).
  • SC-01302: State smoke test path is defined (scripts/test-state-008-order-management-matcher.sh).
  • SC-01303: Smoke checks validate user journeys for order create, account-filtered order listing, user cancel, and admin force-fill.
  • SC-01304: Smoke checks validate matcher auto-fill policy for in-the-money orders and terminal completion.
  • SC-01305: Smoke checks validate that a filled order appears as a trade and updates the corresponding account position.
  • SC-01306: Smoke checks validate observability for order components, including open/unfilled order gauges.
  • SC-01307: Grafana dashboards are provisioned for order book health and matcher throughput/latency.
  • SC-01308: Generated snapshot branch and tag strategy are defined in state catalog.