From 146dadf06f2a1e27385ee9c8ee56790a85fed95a Mon Sep 17 00:00:00 2001 From: Dennis Thiessen Date: Sat, 27 Jun 2026 16:12:59 +0200 Subject: [PATCH] docs: refresh README and document how it works - Add "How It Works": daily load (ordered pipeline steps), intraday flow, other jobs, and the score -> activation gate -> top pick chain. - Add "Key Use Cases" (find today's best long setup; track a paper trade). - Fix stale facts: user-curated (not auto) watchlist, actual routes/pages, scheduler description, wrong env defaults (RR 3.0->1.5, fundamentals daily->weekly). - Add missing surface: paper trading, activation gate, market regime, Telegram alerts, backtest; API groups (paper-trades, market/regime, jobs); FRED + Telegram env vars; note that pipeline timing is admin-cron, not env. Co-Authored-By: Claude Opus 4.8 --- README.md | 79 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 66 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index c136c1a..d749fea 100644 --- a/README.md +++ b/README.md @@ -4,20 +4,57 @@ Investing-signal platform for NASDAQ stocks. Surfaces the best trading opportuni **Philosophy:** Don't predict price. Find the path of least resistance, key S/R zones, and asymmetric R:R setups. +## How It Works + +Scheduled pipelines turn raw prices into a ranked, gated list of tradeable setups. Everything downstream of OHLCV is recomputed from stored data, so each refresh is cheap and idempotent. Job timing is cron-based and configurable in **Admin → Jobs** (default timezone Europe/Berlin). + +### Daily Load — the full refresh + +Once a day (default 07:00). Steps run **in dependency order**, each consuming the previous step's fresh output: + +1. **OHLCV** — fetch the latest daily bars for every tracked ticker (Alpaca); new tickers backfill ~5 years. +2. **Sentiment** — fetch sentiment for the names that matter and are stale (> 5 days): top-pick feeders (momentum leaders with a tradeable long setup), the watchlist, and open paper trades, plus a top-N-by-composite discovery net. Runs *before* the scan so the scan sees fresh sentiment. +3. **R:R Scan** — recompute S/R zones, the 5-dimension scores and long/short setups (ATR stops, S/R targets) for every ticker, and attach each ticker's 12‑1 momentum percentile. +4. **Outcome Eval** — resolve setups that hit target/stop or expired (default 30 trading days) and close paper trades that hit a level. +5. **Market Regime** — recompute the regime index (breadth/trend). +6. **Regime Monitor** — observational early-warning snapshot (VIX, credit spreads via FRED); feeds nothing else. + +A failing step is logged; the pipeline continues with the next. + +### Intraday — light refresh + +Hourly across the US session (Mon–Fri): only **OHLCV → Outcome Eval**, to keep prices current and close paper trades intraday. No scan/sentiment — the dashboard recomputes live R:R from the latest price, so fresh prices are enough. + +### Other jobs + +Fundamentals (weekly, early Monday) · Alerts (hourly, Telegram) · Backtest (weekly) · Ticker-universe sync (daily). Deep history backfill and event study are manual-only (Admin → Jobs). + +### From score to "top pick" + +1. **Composite score** — technical, S/R-quality, sentiment, fundamental and momentum sub-scores (0–100) combine into a weighted composite (weights configurable; missing dimensions re-normalize). +2. **Setups** — the scanner builds long/short setups with ATR stops and S/R targets, then adds a confidence score, conflict flags and a target reach-probability. +3. **Activation gate** — a setup *qualifies* only if it clears the R:R and confidence floors **and** ranks in the top momentum percentile of the universe (the validated edge is long-only momentum). +4. **Top pick** — the highest-momentum qualified setup; highlighted on the Dashboard and labelled on the ticker page. + +## Key Use Cases + +- **Find today's best long setup.** On the **Dashboard**, the *Top Setups* table lists qualified setups ranked by momentum with the #1 flagged "Top pick". Each row opens the ticker page for the chart, scores, S/R targets and entry/stop. +- **Track a trade you took.** Mark a setup as a **paper trade**: it's marked-to-market against the latest close, auto-closed on stop/target, and its sentiment stays fresh while open. *Signals → Track Record* shows the realized edge. + ## Stack | Layer | Tech | |---|---| | Backend | Python 3.12+, FastAPI, Uvicorn, async SQLAlchemy, Alembic | | Database | PostgreSQL (asyncpg) | -| Scheduler | APScheduler — OHLCV, sentiment, fundamentals, R:R scan | +| Scheduler | APScheduler — daily & intraday pipelines, fundamentals, alerts, regime, backtest | | Frontend | React 18, TypeScript, Vite 5 | | Styling | Tailwind CSS 3 with custom glassmorphism design system | | State | TanStack React Query v5 (server), Zustand (client/auth) | | Charts | Canvas 2D candlestick chart with S/R overlays | | Routing | React Router v6 (SPA) | | HTTP | Axios with JWT interceptor | -| Data providers | Alpaca (OHLCV), OpenAI (sentiment, optional micro-batch), Fundamentals chain: FMP → Finnhub → Alpha Vantage | +| Data providers | Alpaca (OHLCV); OpenAI / Gemini / DeepSeek / xAI (sentiment, pluggable); Fundamentals chain: FMP → Finnhub → Alpha Vantage; FRED (regime); Telegram (alerts) | ## Features @@ -30,10 +67,15 @@ Investing-signal platform for NASDAQ stocks. Surfaces the best trading opportuni - Sentiment analysis with time-decay weighted scoring - Fundamental data tracking (P/E, revenue growth, earnings surprise, market cap) - 5-dimension scoring engine (technical, S/R quality, sentiment, fundamental, momentum) with configurable weights -- Risk:Reward scanner — long and short setups, ATR-based stops, configurable R:R threshold (default 1.5:1) -- Auto-populated watchlist (top-10 by composite score) + manual entries (cap: 20) +- Risk:Reward scanner — long and short setups, ATR-based stops, S/R-based targets, configurable R:R threshold (default 1.5:1) +- Activation gate — qualifies setups on a momentum-percentile floor plus R:R/confidence (validated long-only edge); ranks the rest by expected value +- Recommendation layer — directional confidence, conflict detection, per-target reach-probability +- Paper trading — take a setup, mark-to-market vs. latest close, auto-close on stop/target, realized track record + outcome evaluation +- Market-regime index + FRED early-warning monitor (VIX, credit spreads); weekly backtest + manual event study +- Telegram alerts (e.g. regime-quadrant changes) +- User-curated watchlist (cap: 20), enriched with composite score, R:R and S/R summary - JWT auth with admin role, configurable registration, user access control -- Scheduled jobs with enable/disable control and status monitoring +- Cron-scheduled pipelines (admin-configurable) with per-job enable/disable and live status monitoring - Admin panel: user management, data cleanup, job control, system settings ### Frontend @@ -56,12 +98,15 @@ Investing-signal platform for NASDAQ stocks. Surfaces the best trading opportuni |---|---|---| | `/login` | Login | Public | | `/register` | Register | Public (when enabled) | -| `/watchlist` | Watchlist (default) | Authenticated | +| `/` | Dashboard — top setups, open trades, regime (default) | Authenticated | +| `/market` | Market — watchlist + rankings tabs | Authenticated | +| `/signals` | Signals — scanner + track record tabs | Authenticated | +| `/regime` | Market Regime | Authenticated | | `/ticker/:symbol` | Ticker Detail | Authenticated | -| `/scanner` | Trade Scanner | Authenticated | -| `/rankings` | Rankings | Authenticated | | `/admin` | Admin Panel | Admin only | +Legacy routes redirect: `/watchlist` → `/market`, `/rankings` → `/market?tab=rankings`, `/scanner` → `/signals`, `/performance` → `/signals?tab=track`. + ## API Endpoints All under `/api/v1/`. Interactive docs at `/docs` (Swagger) and `/redoc`. @@ -78,7 +123,10 @@ All under `/api/v1/`. Interactive docs at `/docs` (Swagger) and `/redoc`. | Sentiment | `GET /sentiment/{symbol}` | | Fundamentals | `GET /fundamentals/{symbol}` | | Scores | `GET /scores/{symbol}`, `GET /rankings`, `PUT /scores/weights` | -| Trades | `GET /trades` | +| Trades | `GET /trades`, `GET /trades/{symbol}`, `GET /trades/{symbol}/history`, `GET /trades/activation`, `GET /trades/performance` | +| Paper Trades | `GET /paper-trades`, `POST /paper-trades`, `POST /paper-trades/{id}/close` | +| Market / Regime | `GET /market/regime`, `GET /regime/monitor`, `GET/PUT /regime/config`, `GET /regime/history`, `GET /regime/event-study`, `GET/PUT /regime/fundamentals`, `GET /backtest/report` | +| Jobs | `GET /jobs/running` | | Watchlist | `GET /watchlist`, `POST /watchlist/{symbol}`, `DELETE /watchlist/{symbol}` | | Admin | `GET /admin/users`, `POST /admin/users`, `PUT /admin/users/{id}/access`, `PUT /admin/users/{id}/password`, `PUT /admin/settings/registration`, `GET /admin/settings`, `PUT /admin/settings/{key}`, `GET/PUT /admin/settings/recommendations`, `GET/PUT /admin/settings/ticker-universe`, `POST /admin/tickers/bootstrap`, `POST /admin/data/cleanup`, `GET /admin/jobs`, `POST /admin/jobs/{name}/trigger`, `PUT /admin/jobs/{name}/toggle`, `GET /admin/pipeline/readiness` | @@ -164,17 +212,22 @@ Configure in `.env` (copy from `.env.example`): | `FMP_API_KEY` | Optional (fundamentals) | — | Financial Modeling Prep API key (first provider in chain) | | `FINNHUB_API_KEY` | Optional (fundamentals) | — | Finnhub API key (fallback provider) | | `ALPHA_VANTAGE_API_KEY` | Optional (fundamentals) | — | Alpha Vantage API key (fallback provider) | -| `DATA_COLLECTOR_FREQUENCY` | No | `daily` | OHLCV collection schedule | +| `FRED_API_KEY` | Optional (regime) | — | FRED key for the regime monitor (VIX, credit spreads) | +| `TELEGRAM_BOT_TOKEN` | Optional (alerts) | — | Telegram bot token for alerts (can also be set in Admin) | +| `TELEGRAM_CHAT_ID` | Optional (alerts) | — | Telegram chat id for alerts | +| `DATA_COLLECTOR_FREQUENCY` | No | `daily` | OHLCV collection schedule (legacy — see note below) | | `SENTIMENT_POLL_INTERVAL_MINUTES` | No | `30` | Sentiment polling interval | -| `FUNDAMENTAL_FETCH_FREQUENCY` | No | `daily` | Fundamentals fetch schedule | +| `FUNDAMENTAL_FETCH_FREQUENCY` | No | `weekly` | Fundamentals fetch cadence | | `RR_SCAN_FREQUENCY` | No | `daily` | R:R scanner schedule | | `FUNDAMENTAL_RATE_LIMIT_RETRIES` | No | `3` | Retries per ticker on fundamentals rate-limit | | `FUNDAMENTAL_RATE_LIMIT_BACKOFF_SECONDS` | No | `15` | Base backoff seconds for fundamentals retry (exponential) | | `DEFAULT_WATCHLIST_AUTO_SIZE` | No | `10` | Auto-watchlist size | -| `DEFAULT_RR_THRESHOLD` | No | `3.0` | Minimum R:R ratio for setups | +| `DEFAULT_RR_THRESHOLD` | No | `1.5` | Minimum R:R ratio for setups | | `DB_POOL_SIZE` | No | `5` | Database connection pool size | | `LOG_LEVEL` | No | `INFO` | Logging level | +> **Note:** Pipeline timing (daily / intraday / fundamentals cron, timezone) is configured at runtime in **Admin → Jobs** and stored in the DB — the `*_FREQUENCY` env vars are legacy fallbacks for the few jobs still on interval triggers (alerts, universe sync). + ## Production Deployment (Debian 12) ### 1. Install dependencies @@ -292,7 +345,7 @@ frontend/ │ └── watchlist/ # Watchlist table, add ticker form ├── hooks/ # React Query hooks (one per resource) ├── lib/ # Types, formatting utilities - ├── pages/ # Page components (7 pages) + ├── pages/ # Page components (Login, Register, Dashboard, Market, Signals, Regime, Ticker, Admin) ├── stores/ # Zustand auth store └── styles/ # Global CSS with glassmorphism classes