Last Updated: 2026-05-03 Owner: Data-Dev Summary: Reference for QuantMatrix entities, tables, Redis keys, events, and analytics fields.

QuantMatrix Data Dictionary and Schema Reference¶

This document defines the core data entities, schemas, Redis keys, event contracts, and naming conventions used across QuantMatrix.

Its purpose is to: - create a shared language across modules - reduce ambiguity between UI, backend, broker, and analytics layers - support consistent implementation - improve auditability and maintainability

Use this document together with: - the Implementation Specification - the Trade Analytics Specification - the Module Build Checklist Pack - the Deployment Guide

1. Naming Principles¶

QuantMatrix data should follow these rules: - prefer explicit business names over vague generic names - use stable identifiers for entities that cross module boundaries - keep raw broker fields separate from normalized internal fields - distinguish source-of-truth records from caches and derived data - separate raw facts, derived features, labels, explanations, and recommendations

2. Core Entity Map¶

Primary entities in QuantMatrix: - Account Summary - Market Tick - Momentum Snapshot - Top Gainer Scan Result - Watchlist Candidate - Strategy Assignment - Signal - Order - Execution - Position - Risk Violation - Trade - Trade Event - Trade Feature - Trade Outcome - Trade Explanation - Recommendation - Health Status - Settings Override

3. Canonical Identifier Conventions¶

`symbol`¶

Type: string
Meaning: normalized trading symbol, for example AAPL
Source: market data provider or broker, normalized internally

`client_order_id`¶

Type: string
Meaning: unique internal idempotent order identifier
Scope: unique per order command

`broker_order_id`¶

Type: string
Meaning: broker-issued order identifier
Scope: unique within broker

`execution_id`¶

Type: string
Meaning: unique fill or execution identifier from broker or normalized internal source

`trade_id`¶

Type: string or UUID
Meaning: unique identifier for one full trade lifecycle from first fill to full close

`strategy_id`¶

Type: string
Meaning: logical strategy name or id

`strategy_version`¶

Type: string
Meaning: version of strategy logic used for the trade

`session_id`¶

Type: string
Meaning: trading session identifier, typically date-based or environment-scoped

4. Relational Source-of-Truth Tables¶

These are the primary durable tables recommended for PostgreSQL.

4.1 `orders`¶

Purpose: - durable source of truth for order lifecycle state

Key fields: - id - client_order_id - broker_order_id - symbol - side - order_type - time_in_force - quantity - limit_price - stop_price - status - source_strategy_id - source_strategy_version - submitted_at - acknowledged_at - cancelled_at - rejected_at - created_at - updated_at

Status examples: - NEW - VALIDATED - SENT - ACK - PARTIALLY_FILLED - FILLED - CANCELLED - REJECTED - CLOSED

Indexes: - client_order_id unique - broker_order_id - symbol - status - submitted_at

4.2 `executions`¶

Purpose: - durable source of truth for fills and partial fills

Key fields: - id - execution_id - client_order_id - broker_order_id - symbol - side - filled_quantity - fill_price - fill_timestamp - liquidity_flag - commission - fees - created_at

Indexes: - execution_id unique - client_order_id - broker_order_id - symbol - fill_timestamp

4.3 `positions`¶

Purpose: - current normalized internal position state

Key fields: - id - symbol - side - quantity - average_entry_price - market_price - unrealized_pnl - realized_pnl - opened_at - closed_at - status - last_reconciled_at - created_at - updated_at

Indexes: - symbol - status - updated_at

4.4 `pnl_snapshots`¶

Purpose: - historical account and symbol-level P&L snapshots

Key fields: - id - snapshot_time - account_equity - buying_power - cash - realized_pnl - unrealized_pnl - day_pnl - symbol - symbol_realized_pnl - symbol_unrealized_pnl

Indexes: - snapshot_time - symbol

4.5 `active_watchlist`¶

Purpose: - durable state for watchlist lifecycle

Key fields: - id - symbol - source - strategy_id - strategy_version - status - time_added - time_closed - time_completed - polling_status - notes - created_at - updated_at

Status examples: - WAITING - ACTIVE - HOLD - CLOSED - BUY - SELL

Indexes: - symbol - status - time_added

4.6 `blocked_symbols`¶

Purpose: - durable block rules for symbols

Key fields: - id - symbol - block_scope - reason - effective_from - expires_at - created_by - created_at

Block scope examples: - SESSION - TODAY - PERMANENT

Indexes: - symbol - expires_at

5. Trade Analytics Tables¶

5.1 `trades`¶

Purpose: - normalized completed trade lifecycle record

Key fields: - id - trade_id - symbol - side - entry_time - exit_time - entry_price - exit_price - quantity - gross_pnl - net_pnl - strategy_id - strategy_version - mode - entry_reason - exit_reason - hold_duration_seconds - status - created_at - updated_at

Indexes: - trade_id unique - symbol - strategy_id - entry_time - exit_time

5.2 `trade_events`¶

Purpose: - immutable chronology of trade lifecycle events

Key fields: - id - trade_id - event_type - event_time - payload_json - source_module - created_at

Event examples: - CANDIDATE_CREATED - SIGNAL_GENERATED - ORDER_SUBMITTED - ENTRY_FILLED - PARTIAL_FILL - EXIT_SIGNAL - EXIT_FILLED - TRADE_CLOSED

Indexes: - trade_id - event_type - event_time

5.3 `trade_features`¶

Purpose: - feature vector captured for trade analysis

Key fields: - id - trade_id - capture_stage - feature_name - feature_type - feature_value_text - feature_value_number - feature_value_boolean - feature_source - captured_at

Capture stages: - ENTRY - IN_TRADE - EXIT - CLOSE

Indexes: - trade_id - capture_stage - feature_name

5.4 `trade_outcomes`¶

Purpose: - normalized labels and outcome metrics

Key fields: - id - trade_id - winner_loser_label - exit_outcome_label - execution_quality_label - setup_quality_label - mfe - mae - slippage - profit_factor_component - created_at

Indexes: - trade_id - winner_loser_label - exit_outcome_label

5.5 `trade_explanations`¶

Purpose: - human-readable or machine-generated reasoning for trade behavior

Key fields: - id - trade_id - explanation_type - explanation_version - content - created_at

Explanation types: - ENTRY_EXPLANATION - EXIT_EXPLANATION - POST_TRADE_SUMMARY

Indexes: - trade_id - explanation_type

5.6 `recommendation_history`¶

Purpose: - persisted recommendations derived from prior trades

Key fields: - id - recommendation_id - scope_type - scope_value - recommendation_version - recommendation_text - confidence_score - sample_size - evidence_summary - created_at

Scope examples: - GLOBAL - STRATEGY - SYMBOL - TIME_OF_DAY

Indexes: - recommendation_id unique - scope_type - scope_value - created_at

6. Redis Key Reference¶

Redis is recommended for live cache, streams, and fast-moving operational state.

6.1 Market Data Cache¶

Pattern: - market:last:{symbol}

Example: - market:last:AAPL

Suggested fields: - symbol - price - bid - ask - volume - timestamp

6.2 Momentum Snapshot Cache¶

Pattern: - momentum:snapshot:{session_id}:{minute_ts}:{symbol}

Example: - momentum:snapshot:2026-05-03:09:31:AAPL

Suggested fields: - symbol - price - percentage_gain - volume - captured_at

TTL: - intraday session TTL or 1-2 day TTL

6.3 Top Gainers Snapshot Index¶

Pattern: - momentum:leaders:{session_id}:{minute_ts}

Purpose: - group the top N names captured for a scan window

6.4 Watchlist Cache¶

Pattern: - watchlist:active - watchlist:waiting - watchlist:item:{symbol}

Purpose: - fast UI reads or operational cache only

6.5 Blocked Symbols Cache¶

Pattern: - risk:blocked_symbols

Purpose: - fast lookup during scanner and order validation

6.6 Health State Cache¶

Pattern: - health:{component_name}

Suggested fields: - status - latency_ms - last_ok_at - detail

6.7 Idempotency Keys¶

Pattern: - idempotency:order:{client_order_id}

Purpose: - prevent duplicate submission paths

7. Event Contract Reference¶

7.1 `MARKET_TICK`¶

{
  "type": "MARKET_TICK",
  "symbol": "AAPL",
  "price": 189.23,
  "bid": 189.22,
  "ask": 189.24,
  "volume": 1200345,
  "timestamp": "2026-05-03T09:31:04Z",
  "provider": "alpaca"
}

7.2 `TOP_GAINER_SCAN_RESULT`¶

{
  "type": "TOP_GAINER_SCAN_RESULT",
  "session_id": "2026-05-03",
  "captured_at": "2026-05-03T09:31:00Z",
  "leaders": [
    {
      "symbol": "AAPL",
      "price": 189.23,
      "percentage_gain": 10.4,
      "volume": 1200345,
      "average_volume": 300000,
      "float": 15000000,
      "sector": "Technology",
      "change_1m": 1.1,
      "change_5m": 3.9
    }
  ]
}

7.3 `SIGNAL`¶

{
  "type": "SIGNAL",
  "signal_id": "sig_001",
  "strategy_id": "opening_breakout_v1",
  "strategy_version": "1.0.0",
  "symbol": "AAPL",
  "action": "BUY",
  "confidence": 0.82,
  "generated_at": "2026-05-03T09:33:00Z"
}

7.4 `ORDER_COMMAND`¶

{
  "type": "ORDER_COMMAND",
  "client_order_id": "ord_001",
  "symbol": "AAPL",
  "side": "BUY",
  "order_type": "MARKET",
  "quantity": 100,
  "strategy_id": "opening_breakout_v1",
  "created_at": "2026-05-03T09:33:01Z"
}

7.5 `FILL_EVENT`¶

{
  "type": "FILL_EVENT",
  "execution_id": "fill_001",
  "client_order_id": "ord_001",
  "broker_order_id": "broker_001",
  "symbol": "AAPL",
  "side": "BUY",
  "filled_quantity": 100,
  "fill_price": 189.28,
  "fill_timestamp": "2026-05-03T09:33:02Z"
}

7.6 `RISK_VIOLATION`¶

{
  "type": "RISK_VIOLATION",
  "rule": "MAX_DAILY_LOSS",
  "symbol": "AAPL",
  "client_order_id": "ord_001",
  "detail": "Daily loss threshold exceeded",
  "timestamp": "2026-05-03T10:45:00Z"
}

8. UI Field Mapping Reference¶

Command Center Cards¶

buying_power -> Buying Power
equity -> Equity
realized_pnl -> Realized P&L
unrealized_pnl -> Unrealized P&L

Momentum Radar Columns¶

symbol
price
percentage_gain
change_1m
change_5m
sector
float
volume
average_volume

Active Strategy Watchlist Columns¶

symbol
current_price
time_added
time_closed
time_completed
strategy_status
strategy_id
polling_status

Positions Columns¶

symbol
market_price
average_entry_price
quantity
unrealized_pnl
strategy_status

Orders Columns¶

submitted_at
status
symbol
side
quantity
broker_name
client_order_id

9. Feature Dictionary for Trade Analytics¶

Recommended high-value feature names: - entry_price - exit_price - signal_price - daily_percent_gain - change_1m - change_5m - volume - average_volume - relative_volume - float - spread - vwap_distance - ema_9_relation - ema_20_relation - ema_200_relation - macd_state - high_of_day_distance - sector - time_of_day_bucket - opening_range_state - halt_status - slippage_bps - hold_duration_seconds - mfe - mae - account_equity_at_entry - concurrent_open_positions

10. Enum Reference¶

Trading Mode¶

LOCAL
PAPER
LIVE
BACKTEST

Order Side¶

BUY
SELL

Order Type¶

MARKET
LIMIT
STOP
STOP_LIMIT

Health Status¶

HEALTHY
DEGRADED
FAILED

Polling Status¶

RUNNING
STALLED
STOPPED

11. Recommended Next Companion Document¶

The next best precision document after this one is an API Reference, so the runtime contracts are documented endpoint by endpoint and event by event.

QuantMatrix Data Dictionary and Schema Reference¶

1. Naming Principles¶

2. Core Entity Map¶

3. Canonical Identifier Conventions¶

symbol¶

client_order_id¶

broker_order_id¶

execution_id¶

trade_id¶

strategy_id¶

strategy_version¶

session_id¶