# Web PRD (Source of Truth)

## 1. Scope
This document defines the product behavior for the Streamlit web app in `web/src/`.

This PRD is intentionally web-only:
- Data fetch and analysis logic
- Classification/trend rules
- Filters, chart behavior, exports, and persisted settings

Out of scope:
- macOS shell/wrapper architecture and packaging

## 2. Product Goal
Provide an analysis-only charting tool that classifies OHLC bars as real/fake, tracks trend state using only real bars, and exposes clear visual, training-oriented guidance, and exportable outputs.

## 3. Inputs and Data Pipeline
1. User configures:
- `symbol`
- `interval`
- `period`
- `max_bars`
- filter/toggle settings
2. App fetches OHLCV via Yahoo Finance (`yfinance`).
3. Optional last-bar drop (live-bar guard) for intraday intervals.
4. Bars are classified (`real_bull`, `real_bear`, `fake`, `unclassified` for first bar).
5. Trend state is derived from classification sequence.
6. UI renders metrics, chart, events, and export artifacts.

## 4. Settings Contract
Persisted settings path:
- Primary: `~/.web_local_shell/settings.json`
- Legacy fallback read: `~/.manesh_trader/settings.json`

Normalization constraints:
- `symbol`: uppercase, non-empty fallback `AAPL`
- `interval`: must be one of `INTERVAL_OPTIONS`, fallback `1d`
- `period`: must be one of `PERIOD_OPTIONS`, fallback `6mo`
- `max_bars`: `[20, 5000]`, fallback `500`
- `volume_sma_window`: `[2, 100]`, fallback `20`
- `volume_multiplier`: `[0.1, 3.0]`, rounded to 0.1, fallback `1.0`
- `refresh_sec`: `[10, 600]`, fallback `60`
- `show_live_guide`: boolean, fallback `true`
- `show_past_behavior`: boolean, fallback `true`
- `show_trade_markers`: boolean, fallback `true`
- `focus_chart_on_selected_example`: boolean, fallback `false`
- `max_training_examples`: `[5, 100]`, fallback `20`
- booleans normalized from common truthy/falsy strings and numbers

## 5. Classification Rules
For each bar `i` (starting at index 1):
- Reference prior bar `i-1`.
- If `use_body_range = false`:
  - `prev_high = prev.High`
  - `prev_low = prev.Low`
- If `use_body_range = true`:
  - `prev_high = max(prev.Open, prev.Close)`
  - `prev_low = min(prev.Open, prev.Close)`

Volume filter:
- If enabled, `volume_ok = Volume >= SMA(Volume, volume_sma_window) * volume_multiplier`
- If `volume_ok` is false, classification is `fake` regardless of price break.

Price logic (when volume is OK):
- `Close > prev_high` -> `real_bull`
- `Close < prev_low` -> `real_bear`
- otherwise -> `fake`

First bar is always `unclassified`.

## 6. Trend-State Rules
Trend states:
- `No Active Trend`
- `Bullish Trend Active`
- `Bearish Trend Active`

State machine:
- From neutral:
  - 2 consecutive `real_bull` -> bullish trend started
  - 2 consecutive `real_bear` -> bearish trend started
- From bullish:
  - 2 consecutive `real_bear` -> bearish reversal confirmed
- From bearish:
  - 2 consecutive `real_bull` -> bullish reversal confirmed

Important:
- `fake` bars do not increment opposite-run counters enough to reverse trend.

## 7. Chart and Visualization Behavior
- Main candlestick chart with bullish/bearish markers:
  - `real_bull`: green triangle-up
  - `real_bear`: red triangle-down
- Optional fake-bar de-emphasis via gray candle layer (`gray_fake`).
- Optional example-trade overlay markers (`show_trade_markers`):
  - long entry marker
  - short entry marker
  - winning exit marker
  - loss/flat exit marker
- If a past-behavior row is selected, chart highlights that trade window and path.
- Optional focused zoom around selected trade (`focus_chart_on_selected_example`).
- Volume subplot colored by trend state.

Gap handling (`hide_market_closed_gaps`):
- Always removes weekend gaps (`sat` -> `mon`).
- For intraday intervals, also removes inferred overnight hours using session bounds.
- For daily interval, weekend break removal is applied.

## 8. Help and Onboarding Behavior
- Web-only fallback help entry exists in sidebar:
  - `Help / Quick Start`
- Content source: `web/src/web_core/help.html` (primary), `web/src/ONBOARDING.md` (fallback)
- Help appears in a dialog.

## 9. Outputs
- Metrics:
  - current trend
  - real bullish count
  - real bearish count
  - fake count
- Live decision guide (optional):
  - bias (long/short/neutral)
  - signal confirmation status
  - latest bar interpretation
  - action + invalidation guidance
- Trend events table (latest events)
- Backtest snapshot:
  - signal at trend-change rows to active bull/bear states
  - next-bar close determines win/loss
- Past behavior examples (optional training panel):
  - historical examples using trend-confirmation entries and opposite-confirmation exits
  - per-example direction, entry/exit timestamps, bars held, P/L%, and outcome
  - aggregate example metrics (count, win/loss, win rate, average P/L)
  - selectable table rows that drive chart highlight of chosen example
  - plain-language explanation for selected example
- Exports:
  - CSV always available
  - PDF via Plotly image export (requires Kaleido runtime)

## 10. Validation Expectations
Code-level checks:
- `python -m py_compile web/src/app.py`
- `PYTHONPATH=web/src pytest -q web/src/tests`

Behavior checks:
- No crash on missing/invalid persisted settings
- Symbol/interval/period invalid combinations show actionable data error
- Trend logic matches two-consecutive-real-bars contract
- Exports include normalized timestamp column
