# Feature Specification: Order Management and Matcher

> For the complete documentation index, see [llms.txt](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/llms.txt).

**Feature Branch**: `009-order-management-matcher`  
**Created**: 2026-04-05  
**Status**: Implemented  
**Input**: Transition delta from `008-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-01303A: In states that support order management (`009` and descendants), the trade page SHALL render a visible order-create launcher button whenever the trade ticket launcher is rendered.
*   FR-01303B: Trade and order launcher buttons SHALL both remain visible but disabled in `All Accounts` mode, and neither launcher SHALL open its ticket modal while that guard is active.
*   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-01311: Order matcher publishes order lifecycle updates to `/accounts/{accountId}/orders` (account scope) and `/orders` (all accounts) for every persisted transition (`NEW`, `PARTIALLY_FILLED`, `FILLED`, `CANCELED`, `REJECTED`).
*   FR-01312: Published order events use the same payload contract as order REST responses so UI consumers can apply updates without an immediate follow-up HTTP fetch.
*   FR-01313: Realtime TraderX views (`trade` blotter, `position` blotter, account order blotter, and admin order blotter) SHALL subscribe to messaging subjects and apply push updates as their source of incremental change.
*   FR-01314: Realtime views SHALL bootstrap initial state from REST and then continue via pub/sub stream updates, without requiring periodic background polling loops.
*   FR-01315: API explorer pub/sub inspector contract introduced in state `008` SHALL be preserved, and generated inspector topic buttons SHALL include order subjects (`/accounts/{accountId}/orders`, `/orders`) in this state.
*   FR-01317: The state-specific header override in this feature SHALL retain the inherited System menu contract (API Explorer + About + conditional Status) and state-id title rendering while adding the `Admin` functional tab.
*   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 `008` remain compatible unless explicitly changed in this pack.

## Non-Functional Requirements

*   NFR-01301: Observability stack from `007` 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.
*   NFR-01308: Every service in this state that exposes Prometheus-compatible metrics MUST be scraped by Prometheus and represented in provisioned Grafana dashboards.
*   NFR-01309: As convergence level `C2`, generated state branches MUST include `.github/workflows/build-and-publish.yml` for container image publication.
*   NFR-01310: `C2` image publication namespace MUST use `ghcr.io/finos/traderx-c2/<component>` with immutable commit-SHA tags plus `latest`.
*   NFR-01311: Generated artifacts MUST include a GHCR run bundle for running this state from published images.
*   NFR-01312: Generator output MUST deterministically include `database/initialSchema.sql` with an `OrderBook` table definition whenever `order-matcher` is present in generated state artifacts.
*   NFR-01313: Generated-state publish gates MUST fail if `order-matcher` is present and the generated database schema contract for `OrderBook` is missing.
*   NFR-01314: Order-facing UI views (`trade` order blotter, admin order view) MUST use messaging-bus push subscriptions for live updates and MUST NOT run periodic background polling loops against `GET /orders`.
*   NFR-01315: Trade and position blotters MUST retain push-based realtime updates (`/accounts/{accountId}/trades`, `/accounts/{accountId}/positions`) after initial REST bootstrap and MUST NOT introduce periodic polling loops as a substitute for stream updates.
*   NFR-01316: Generated API explorer catalog for this state SHALL include cumulative `messagingSubjects` metadata for inspector topic generation, including wildcard semantics (`pricing.*`) and parameterized subject prefill patterns.
*   NFR-01317: Browser-offered API explorer and pub/sub inspector links in this state SHALL resolve with non-404 responses and browser-renderable content types (HTML for pages, JSON for catalog payloads).
*   NFR-01318: As a demo-target containerized state, generated snapshots SHALL include a deployment bundle under `runtime/deploy/` for profile-scoped environment rollout scripts and runbooks.
*   NFR-01319: Deployment bundle scripts SHALL be dry-run-capable, rely on env vars for environment-specific values, and SHALL NOT include embedded secrets/tokens.
*   NFR-01320: Inherited observability ingress routes SHALL keep Grafana dashboards anonymously readable as Viewer-only demo surfaces while retaining non-default state-scoped admin credentials for local administration.
*   NFR-01321: Generated runtime startup SHALL configure Promtail with the local Docker daemon API version by default so Loki log ingestion is not blocked by Docker client/server API mismatch.

## Success Criteria

*   SC-01301: Generation hook exists and is runnable (`pipeline/generate-state-009-order-management-matcher.sh`).
*   SC-01302: State smoke test path is defined (`scripts/test-state-009-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.
*   SC-01309: Generated branch artifacts include `C2` build/publish workflow and GHCR run-bundle assets.
*   SC-01310: `pipeline/validate-generated-state-contracts.sh` fails on generated snapshots that include `order-matcher` without `OrderBook` schema and passes when the contract is present.
*   SC-01311: Smoke checks validate that open-order views update in real time on create/auto-fill/cancel/force-fill via `/accounts/{accountId}/orders` and `/orders`, without periodic `GET /orders` polling traffic.
*   SC-01312: Smoke checks validate `/api/docs/pubsub-inspector.html` availability (no-extension compatibility path included), URL/content-type contracts, and topic metadata coverage against `system/messaging-subject-map.md`.
*   SC-01313: Smoke checks validate that the generated frontend still satisfies the inherited state-aware header/System-menu contract after the `Admin` tab extension.
*   SC-01314: Generated snapshot contains deployment-bundle assets for demo rollout and those assets pass local dry-run validation.
*   SC-01315: State `009` Grafana dashboard URLs under `/grafana/` load through ingress without login and datasource API requests remain same-origin.
*   SC-01316: State `009` Promtail logs do not contain Docker API mismatch errors when launched through the generated runtime harness on a supported Docker host.