Skip to content

Last Updated: 2026-05-03 Owner: UI-Dev Summary: Review of gaps between the documented target UI and the current MomentumTrader application screens and contracts.

QuantMatrix UI Document Alignment Review

This document compares the current Markdown documentation set with the actual UI implementation in /Users/dhinakarmanni/projects/MomentumTrader.

Its purpose is to identify where the documents are: - still accurate - describing the intended target state - out of sync with the current implementation

This review should be used before updating any architecture, API, UI, or runbook document so we do not accidentally erase useful target-state planning.

1. Review Outcome

The current documentation set is still useful, but it mixes: - future-state product design - target architecture - partially implemented UI behavior

The current MomentumTrader UI is a real working prototype, but it does not fully match the documented QuantMatrix screen model.

The best documentation approach going forward is: 1. keep the existing architecture and design docs as the target-state design 2. document the current MomentumTrader UI as the current implementation state 3. explicitly mark gaps between current state and target state

2. Current MomentumTrader UI Inventory

Observed current top-level UI structure: - top header with account summary metrics, mode badge, theme toggle, and emergency control - top tab navigation, not left-sidebar screen navigation

Current tabs in the app: - Radar - Positions - Orders - P&L - Health - Settings

Current Radar tab composition: - Momentum Radar table - P&L widget - System Health & Control widget - Active Strategy Watchlist table - Active Positions widget - Order History Log widget - Scanner Controls footer widget

Current Health tab composition: - risk status summary bar - risk violations table - blocked symbols table - system components table

Current Settings tab scope: - runtime / environment - opportunity scanner - strategy allocator - risk management - position sizing - operational settings - analytics settings - symbol universe

3. Main Gaps Between Docs and UI

3.1 Branding Gap

Documentation uses: - QuantMatrix

Current application uses: - MomentumTrader

Recommended doc update: - add an explicit note in the relevant docs that the implementation currently runs under the MomentumTrader app name while the target documentation set is being maintained under QuantMatrix

3.2 Navigation Model Gap

Documentation generally describes a screen set centered around: - Command Center - Account - Positions - Orders - Risk & Health - Settings - Data & Backtests

Current implementation uses: - Radar - Positions - Orders - P&L - Health - Settings

Recommended doc update: - document the current tab model as the implemented navigation structure - keep the documented screen model as the target-state operator workflow

3.3 Account Screen Gap

Documentation expects: - a dedicated Account screen - account performance - P&L by day and by symbol

Current implementation: - no dedicated Account tab - account metrics appear in the header - no account-performance breakdown screen

Recommended doc update: - mark the Account screen as planned / target-state - document the current header-based account summary as the implemented state

3.4 P&L Screen Gap

Documentation currently places P&L mostly as: - account summary support data - command center / account-adjacent widget

Current implementation: - has a dedicated P&L tab - includes overview, trade statistics, and best/worst summaries

Recommended doc update: - update UI documents to acknowledge a current dedicated P&L screen - decide whether target-state should keep a standalone P&L tab or fold it back into Account

3.5 Risk & Health Screen Gap

Documentation expects: - broker health - latency - emergency control - global risk state

Current implementation provides more detail: - daily loss usage - trade-count usage - drawdown - reconciliation status - risk violations - blocked symbols - system components table

Recommended doc update: - expand the Risk & Health documentation to include: - reconciliation status - blocked symbols management - risk violation table - component-level system table

3.6 Data & Backtests Screen Gap

Documentation expects: - a Data & Backtests screen - historical download flow - backtest runner

Current implementation: - does not include this screen

Recommended doc update: - mark Data & Backtests as not yet implemented - keep it in roadmap and target UI docs

4. Widget and Column-Level Gaps

4.1 Momentum Radar

Documentation expects columns: - Symbol - Price - % Gain - Last 1 Min % Change - Last 5 Mins % Change - Sector - Float - Volume - Average Volume - Actions

Current implementation includes: - Symbol - Price - % Gain - 1 Min % - 5 Min % - Sector - Float - Volume - Avg Vol - RVol - Actions

Recommended doc update: - add Relative Volume (RVol) as an implemented/current column - clarify scanner interval drift: - docs target exact minute-boundary scanning - current UI presents a 30-second scanner control rhythm and 10-second radar fetch refresh

4.2 Active Strategy Watchlist

Documentation expects: - sortable grid - latest time-added first - strategy ID/name - polling indicator - stop and restart actions - status coverage including Active, Closed, Buy, Sell

Current implementation includes: - Symbol - Price - Time Added - Time Closed - Completed - Status - Strategy - Actions

Current implementation does not clearly expose: - polling indicator - source column - sell status - hold status

Recommended doc update: - note that polling health is still missing in the current UI - note that source, hold, and sell states are not yet surfaced in the current table - preserve these as target-state requirements

4.3 Positions

Documentation expects: - Symbol - Current Price - Average Entry Price - Shares - Unrealized P&L - Strategy Status - actions for Close Position and Halt Strategy

Current implementation includes: - Symbol - Qty - Entry - Current - Unrealized - Realized - Alert - Actions

Current implementation does not clearly expose: - explicit strategy status column - Halt Strategy action in the positions tab UI

Recommended doc update: - document realized P&L and alert level as current columns - keep halt strategy as a target-state operator control if still desired

4.4 Orders

Documentation expects: - Time - Status - Symbol - Side - Quantity - Broker - Client Order ID

Current implementation includes: - Symbol - Side - Qty - Filled - Type - Price - Status - Reason - Time

Recommended doc update: - explicitly distinguish: - documented target operator/audit view - current implementation view - add Type, Filled, Price, and Reason as current columns - note that Broker and Client Order ID are not currently shown in the UI

5. API Contract Drift Found During UI Review

The frontend and backend are not fully aligned yet.

Most important mismatch found: - frontend client calls POST /risk/emergency-halt - backend router currently exposes POST /emergency/liquidate

Recommended doc update: - add a document note that the emergency-halt contract needs alignment before the API docs are considered implementation-accurate

Other observations: - several backend endpoints are still placeholders - README claims broader phase readiness than the actual backend behavior supports

6. Documents That Should Be Updated First

Highest Priority

  1. documentation/docs/api_reference_document.md
  2. add a “current implementation drift” note
  3. reconcile emergency endpoint naming

  4. distinguish implemented vs target endpoints where needed

  5. documentation/docs/data_dictionary_schema_reference.md

  6. update UI field mapping to include:
  7. Radar RVol
  8. Positions realized P&L
  9. Positions alert level
  10. Orders reason

  11. Health reconciliation fields

  12. documentation/docs/operations_runbook.md

  13. update screen navigation references to reflect the current tab-based UI

  14. clarify that the working operator surface is currently Radar / Positions / Orders / P&L / Health / Settings

  15. documentation/docs/live_trading_go_live_checklist.md

  16. clarify which target screens do not yet exist as dedicated tabs
  17. avoid implying an Account screen or Data & Backtests screen is already available

Medium Priority

  1. documentation/docs/project_roadmap_milestone_plan.md

  2. distinguish target-state screens from current implementation tabs

  3. documentation/docs/milestone_sprint_plan_first_4_weeks.md

  4. clarify whether the Account screen is a planned Week 3 target or a deferred screen

  5. documentation/docs/module_build_checklist_pack.md

  6. add missing current UI gaps:
  7. watchlist polling indicator
  8. watchlist source visibility
  9. halt action in positions view
  10. broker/client order ID visibility in orders view

Do not simply rewrite the docs to mirror the current prototype.

Instead:

Keep As Target-State Design

  • architecture docs
  • roadmap docs
  • implementation prompt docs
  • target UI screen descriptions

Add Current-State Implementation Notes

  • current navigation model
  • currently implemented tabs
  • current widget inventory
  • current API contract differences
  • current missing operator controls

Use This Rule

If a document answers: - “What are we trying to build?” -> keep it target-state - “What exists right now?” -> update it with current implementation truth

The best next step is:

Update the API Reference, Data Dictionary, and Operations Runbook with explicit current-state vs target-state notes.

That will give you: - cleaner implementation truth - less confusion while building - safer operator expectations - better coordination between UI, API, and process work