Alpha Screener

Personal, self-hosted market screener and learning platform. Every signal is computed in-house from raw OHLCV (Hyperliquid for crypto, yfinance EOD for equities) — nothing is scraped from TradingView. On top of the screener sits a deliberately staged beginner loop: interpret a chart and commit Watch or Pass, separate decision quality from market outcome, practice on outcome-blind historical setups, compare against matched Market Twin cohorts, and graduate saved setups only when forward evidence supports them.

Spec: docs/alpha-screener-build-spec.md — the single source of truth. Phase summaries land in docs/ as each phase completes.

What's in the app

The web UI is a single-origin Next.js app with nine views:

• Today — personalised Daily Mission: turns practice, live discovery, and due reviews into one next action.
• Discover — the screener itself: signal badges, Basic/Pro modes, Stage-2-Breakout-style filters, ranked results, TradingView hand-off.
• Practice — outcome-blind historical setups; decision quality is scored separately from market outcome.
• Playbook — reusable personal lessons saved from practice and reviews.
• Watchlist — committed Watch/Pass decisions with forward outcome tracking.
• Review — spaced learning reviews and Market Twin comparisons.
• Strength — Mansfield relative performance vs type benchmarks.
• Evidence — evidence-gated graduation of saved setups.
• Ops — pipeline health, data freshness pulse, and job telemetry.

Morning Brief (ranked live brief + risk-based trade plans) and daily pre-market Pushover/ntfy/Telegram alerts run off the same signal store.

Layout

• backend/ — Python 3.12 (uv), FastAPI, SQLAlchemy 2 + Alembic on Postgres 16, Typer CLI (alpha), pure pandas/numpy indicator library.
  • alpha/indicators/ — AlphaTrend/SuperTrend/Chandelier/gated-pursuit tracks, dots, TD counts, RSI divergence, squeeze, breakouts, candles, volume, OBV, MACD, and more.
  • alpha/signals/ — badge computation, scoring, Mansfield RS, materialised outputs.
  • alpha/backtest/ — event-driven backtester driven by strategies.yaml (alpha backtest --strategy <name>|all, grid variants, in-sample splits).
  • alpha/brief/, alpha/evidence/, alpha/alerts/ — ranking, learning loop, setup graduation, push notifications.
  • signals.yaml — every tunable signal parameter; calibration edits this file, not code.
  • calibration/ — harness fitting the in-house indicators against reference exports; calibration/scoreboard.py scores every calibrated signal. The exports and calibration notes are local-only and not tracked in this repo.
• frontend/ — Next.js 15 / React 19, TypeScript, Tailwind 4, TanStack Query, lightweight-charts; Playwright e2e; enforced bundle-size budget.
• deploy/ — docker-compose stack (Postgres 16, api, web, Caddy single-origin proxy, optional Cloudflare Tunnel), systemd timers (hourly/nightly compute, alerts, meta refresh, health, backups + restore-verify, reconcile), rollout and release-sync scripts, migration runbook.
• data/universe/ — instrument universes (S&P 500, FTSE 350) and TV symbol overrides.
• docs/ — build spec, per-phase summaries and acceptance notes.

CLI

The backend installs a single alpha entry point (run via uv run alpha … or the compose job profile):

alpha ingest <crypto|equity>     # pull closed candles from providers
alpha compute --type … --tf …    # indicators + signal badges per timeframe
alpha hourly / alpha nightly     # scheduled pipeline bundles (systemd timers)
alpha alert                      # evaluate setup alerts, push notifications
alpha refresh-meta               # instrument metadata refresh
alpha health                     # data-freshness / pipeline health checks
alpha backtest --strategy …      # strategy battery from strategies.yaml

Development

Prerequisites: Python 3.12 + uv, Node 20+, Docker.

make db        # start Postgres 16 (Docker)
make dev-api   # FastAPI with reload on :8000
make dev-web   # Next dev server on :3000
make test      # backend pytest
make check     # ruff + pytest + tsc --noEmit + eslint
make e2e       # Playwright smoke: seeds demo DB, boots API+web, steps the S2B filter
make scoreboard  # accuracy baseline vs TV exports — run around any indicator change

Indicator code is pure (pandas/numpy in, Series/DataFrame out) with golden-fixture tests; networks are mocked in tests, financial maths never is. Only closed candles enter the database.