mbrucedogs/maneshtrader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
246c3be86b
maneshtrader/web/src/PRD.md

9.2 KiB
Raw Blame History

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
  • optional watchlist (per-profile)
  • interval
  • period
  • max_bars
  • optional market_preset
  • filter/toggle settings
  • optional advanced controls (alerts, replay, compare symbols, backtest controls, regime filter)
  1. App fetches OHLCV via Yahoo Finance (yfinance).
  • For day-based periods (for example 1d, 5d), fetch widens calendar lookback as needed, then trims to the latest N trading days that actually contain bars.
  1. Optional last-bar drop (live-bar guard) for intraday intervals.
  2. Bars are classified (real_bull, real_bear, fake, unclassified for first bar).
  3. Trend state is derived from classification sequence.
  4. 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

Storage format:

  • Current format stores per-profile settings:
    • last_profile: most recently used profile id
    • profiles: object map of profile_id -> profile record
    • profile record fields:
      • settings: normalized settings payload
      • pin_hash: optional SHA-256 hash for 4-6 digit PIN
      • audit: metadata (created_at, updated_at, last_login_at, last_symbol)
  • Legacy single-profile payloads are read as profile default and migrated to current format on next save.

Profile behavior:

  • App enforces a profile login gate before data/settings UI is shown.
  • Login requires typing an existing profile name.
  • Login checks PIN when profile has one configured.
  • Login includes Remember me on this browser.
  • Create Profile requires typing a new profile name.
  • Create Profile accepts optional 4-6 digit PIN.
  • Profile-name uniqueness is case-insensitive (for example Matt and matt are treated as duplicates).
  • Sidebar shows active profile with a Switch profile control.
  • Sidebar shows profile audit stamps (created/updated/last login/last symbol).
  • Query param profile selects active profile.
  • Save/load are scoped to active profile to avoid cross-user overwrites.
  • If profile has no saved settings, defaults are used.
  • Session activity is tracked in-memory; after 30 minutes of inactivity the app clears active profile and returns to login screen.
  • If remember=1 is present with a known non-PIN profile, app auto-restores that profile without showing login.
  • PIN-protected profiles always require PIN entry after session timeout/reopen.

Watchlist and preset behavior:

  • watchlist is saved per profile and supports comma/newline input.
  • Watchlist supports one-click symbol quick-select buttons.
  • market_preset applies tuned defaults for common workflows (Custom, Stocks Swing, Crypto Intraday, Crypto Swing).
  • Preset application affects defaults for timeframe/period/max bars and related monitoring/gap options.

Advanced feature behavior:

  • Multi-timeframe confirmation (1h, 4h, 1d) can show consensus trend and agreement percent.
  • Alert rules can trigger on bullish/bearish trend events and optionally POST JSON payloads to a webhook URL.
  • Session stats track since-login wins/losses, average move after signal, and fake-bar rate for visible data.
  • Backtest controls include slippage/fees (bps), optional stop-loss/take-profit %, and min/max hold bars.
  • Signal quality score combines trend state, volume-filter usage, and recent fake-bar density.
  • Replay mode limits visible bars to first N rows to simulate no-hindsight review.
  • Compare symbols panel can summarize trend/regime/fake-ratio for a small basket.
  • Regime filter flags choppy periods and can suppress directional bias.

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 false
  • show_past_behavior: boolean, fallback false
  • show_trade_markers: boolean, fallback false
  • focus_chart_on_selected_example: boolean, fallback false
  • max_training_examples: [5, 100], fallback 20
  • watchlist: uppercase de-duplicated symbol list, max 40 items
  • market_preset: one of Custom, Stocks Swing, Crypto Intraday, Crypto Swing, fallback Custom
  • compare_symbols: uppercase de-duplicated symbol list, max 12 items
  • alert_webhook_url: optional string
  • backtest_slippage_bps: [0.0, 100.0], fallback 0.0
  • backtest_fee_bps: [0.0, 100.0], fallback 0.0
  • backtest_stop_loss_pct: [0.0, 25.0], fallback 0.0 (0 disables)
  • backtest_take_profit_pct: [0.0, 25.0], fallback 0.0 (0 disables)
  • backtest_min_hold_bars: [1, 20], fallback 1
  • backtest_max_hold_bars: [1, 40], fallback 1 and clamped to >= min_hold
  • 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).
  • Removes full missing calendar days between first/last bar (for example market holidays with no bars).
  • For intraday intervals, uses contiguous bar-order x-axis (no closed-session spacing) and day-level tick labels.
  • 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
    • advanced mode supports configurable costs/holds/stop/target
  • 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)
  • Additional optional panels:
    • multi-timeframe confirmation
    • compare symbols snapshot
    • session stats

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