signal-platform/.kiro/specs/score-transparency-trade-overlay/requirements.md

Requirements Document

Introduction

This feature adds two capabilities to the stock trading signal platform:

1. Score Transparency — Each dimension score (sentiment, fundamental, momentum, technical, sr_quality) and the composite score currently appear as opaque numbers. This feature exposes the scoring formulas, sub-scores, weights, and input values so users can understand exactly how each score was calculated.

2. Trade Setup Chart Overlay — When a trade setup exists for a ticker (from the R:R scanner), the candlestick chart on the ticker detail page renders visual overlays showing the entry price, stop-loss zone, and take-profit zone as colored regions, similar to TradingView trade visualization.

Glossary

• Scoring_API: The backend API endpoint (GET /api/v1/scores/{symbol}) that returns composite and dimension scores for a ticker
• Score_Breakdown: A structured object containing the sub-scores, input values, weights, and formula description for a single dimension score
• Dimension_Panel: A frontend UI component that displays a single dimension score along with its Score_Breakdown details
• ScoreCard_Component: The frontend component (ScoreCard.tsx) that displays the composite score ring and dimension bar list
• CandlestickChart_Component: The frontend canvas-based chart component (CandlestickChart.tsx) that renders OHLCV data with overlays
• Trade_Overlay: A set of visual elements drawn on the CandlestickChart_Component representing a trade setup's entry, stop-loss, and target levels
• TradeSetup: A data object with fields: symbol, direction, entry_price, stop_loss, target, rr_ratio, representing a detected trade opportunity
• TickerDetail_Page: The page (TickerDetailPage.tsx) that displays all data for a single ticker

Requirements

Requirement 1: Score Breakdown API Response

User Story: As a trader, I want the scores API to return detailed breakdowns for each dimension score, so that the frontend can display how scores were calculated.

Acceptance Criteria

1. WHEN a score request is made for a symbol, THE Scoring_API SHALL return a Score_Breakdown object for each dimension containing: sub-score names, sub-score values, input values used, weights applied, and the formula description
2. WHEN the technical dimension is computed, THE Scoring_API SHALL include sub-scores for ADX (weight 0.4), EMA (weight 0.3), and RSI (weight 0.3), along with the raw indicator values (adx_value, ema_value, latest_close, rsi_value)
3. WHEN the sentiment dimension is computed, THE Scoring_API SHALL include the number of sentiment records used, the decay rate, the lookback window, and the time-decay weighted average formula parameters
4. WHEN the fundamental dimension is computed, THE Scoring_API SHALL include sub-scores for PE Ratio, Revenue Growth, and Earnings Surprise, along with the raw metric values and the normalization formula for each
5. WHEN the momentum dimension is computed, THE Scoring_API SHALL include sub-scores for 5-day ROC (weight 0.5) and 20-day ROC (weight 0.5), along with the raw ROC percentage values
6. WHEN the sr_quality dimension is computed, THE Scoring_API SHALL include sub-scores for strong level count (max 40 pts), proximity (max 30 pts), and average strength (max 30 pts), along with the input values (strong_count, nearest_distance_pct, avg_strength)
7. WHEN the composite score is computed, THE Scoring_API SHALL include the per-dimension weights used and indicate which dimensions were available versus missing for the re-normalization calculation
8. IF a sub-score component has insufficient data, THEN THE Scoring_API SHALL omit that sub-score from the breakdown and include a reason string explaining the data gap

Requirement 2: Score Transparency UI — Dimension Panels

User Story: As a trader, I want to see a detailed breakdown of each dimension score in the UI, so that I can understand what drives each score.

Acceptance Criteria

1. WHEN a dimension score is displayed in the ScoreCard_Component, THE Dimension_Panel SHALL show an expandable breakdown section listing each sub-score name, its value, its weight, and the raw input value
2. WHEN the user expands a dimension breakdown, THE Dimension_Panel SHALL display the formula description as human-readable text explaining how the sub-scores combine into the dimension score
3. WHEN the technical dimension breakdown is expanded, THE Dimension_Panel SHALL display ADX score and raw ADX value, EMA score and percentage difference from EMA, and RSI score and raw RSI value, each with their respective weights (40%, 30%, 30%)
4. WHEN the sentiment dimension breakdown is expanded, THE Dimension_Panel SHALL display the number of sentiment records, the decay rate, and the weighted average calculation summary
5. WHEN the fundamental dimension breakdown is expanded, THE Dimension_Panel SHALL display PE Ratio sub-score with raw PE value, Revenue Growth sub-score with raw growth percentage, and Earnings Surprise sub-score with raw surprise percentage
6. WHEN the momentum dimension breakdown is expanded, THE Dimension_Panel SHALL display 5-day ROC sub-score with raw ROC percentage and 20-day ROC sub-score with raw ROC percentage
7. WHEN the sr_quality dimension breakdown is expanded, THE Dimension_Panel SHALL display strong level count score, proximity score, and average strength score with their respective input values
8. IF a sub-score is unavailable due to insufficient data, THEN THE Dimension_Panel SHALL display a muted label indicating the sub-score is unavailable with the reason

Requirement 3: Composite Score Transparency

User Story: As a trader, I want to see how the composite score is calculated from dimension scores, so that I can understand the overall signal strength.

Acceptance Criteria

1. WHEN the composite score is displayed, THE ScoreCard_Component SHALL show the weight assigned to each dimension next to its bar in the dimensions list
2. WHEN a dimension is missing from the composite calculation, THE ScoreCard_Component SHALL visually indicate the missing dimension and show that its weight was redistributed
3. WHEN the user views the composite score section, THE ScoreCard_Component SHALL display a tooltip or inline text explaining that the composite is a weighted average of available dimensions with re-normalized weights

Requirement 4: Trade Setup Chart Overlay

User Story: As a trader, I want to see my trade setup (entry, stop-loss, target) overlaid on the candlestick chart, so that I can visually assess the trade relative to price action.

Acceptance Criteria

1. WHEN a TradeSetup exists for the current ticker, THE CandlestickChart_Component SHALL render an entry price line as a dashed horizontal line in blue or white color spanning the full chart width
2. WHEN a TradeSetup exists for the current ticker, THE CandlestickChart_Component SHALL render a stop-loss zone as a red semi-transparent shaded rectangle between the entry price and the stop-loss price level
3. WHEN a TradeSetup exists for the current ticker, THE CandlestickChart_Component SHALL render a take-profit zone as a green semi-transparent shaded rectangle between the entry price and the target price level
4. THE CandlestickChart_Component SHALL include the entry price, stop-loss price, and target price in the y-axis price range calculation so that all trade overlay levels are visible within the chart viewport
5. WHEN the user hovers over the trade overlay area, THE CandlestickChart_Component SHALL display a tooltip showing the trade direction, entry price, stop-loss price, target price, and R:R ratio
6. IF no TradeSetup exists for the current ticker, THEN THE CandlestickChart_Component SHALL render the chart without any trade overlay elements

Requirement 5: Trade Setup Data Integration on Ticker Detail Page

User Story: As a trader, I want the ticker detail page to automatically fetch and display trade setups for the current ticker, so that I see the trade overlay without extra navigation.

Acceptance Criteria

1. WHEN the TickerDetail_Page loads for a symbol, THE TickerDetail_Page SHALL fetch trade setups from the trades API and filter for setups matching the current symbol
2. WHEN a matching TradeSetup is found, THE TickerDetail_Page SHALL pass the trade setup data to the CandlestickChart_Component as a prop
3. WHEN a matching TradeSetup is found, THE TickerDetail_Page SHALL display a trade setup summary card below the chart showing direction, entry price, stop-loss, target, and R:R ratio
4. IF the trades API request fails, THEN THE TickerDetail_Page SHALL render the chart without trade overlays and log the error without disrupting the page
5. IF multiple TradeSetups exist for the same symbol, THEN THE TickerDetail_Page SHALL use the most recently detected setup (latest detected_at)