Confluence Engine

Multi-method price level aggregation for futures trading. Computes levels from 10 independent technical methods, clusters them into zones, and scores by confluence density. High-scoring zones represent price levels where multiple unrelated methods agree — the idea being that independent confirmation across methods and timeframes produces higher-probability support/resistance.

Setup

Prerequisites: Python 3.12+, Node.js 18+, uv

# Clone and install
git clone <repo-url> && cd someday_ill_be_saturday_night
uv sync --dev
cp .env.example .env

# Warm the data cache (fetches OHLCV for all symbols, takes ~30s)
uv run python scripts/warm_cache.py

# Start the API server
uv run uvicorn confluence_engine.api.app:create_app --factory --port 8000

# In a second terminal — start the dashboard
cd frontend && npm install && npm run dev

Open http://localhost:5173 to view the dashboard.

What You'll See

• Candlestick chart with zone overlay lines (green = A-grade, yellow = B-grade)
• Scored zone table — click any zone to expand and see which methods contributed
• Method weights panel — the 10 methods and their current scoring weights
• Symbol selector — switch between ES, NQ, CL, GC futures
• Auto-refresh — toggle live recomputation on a 1m/5m/15m/30m interval
• Data age badges — shows how stale each timeframe's cached data is

How It Works

         ┌──────────────────────────────────────────────────┐
         │              10 Technical Methods                 │
         │                                                  │
         │  Standard Pivots    Bollinger Bands   Fibonacci  │
         │  Camarilla Pivots   Keltner Channels  MA Cluster │
         │  Prior Session H/L  ATR Envelopes     Vol Profile│
         │  VWAP Bands                                      │
         └──────────────┬───────────────────────────────────┘
                        │ Each produces price levels
                        ▼
              ┌───────────────────┐
              │     Clusterer     │  Groups nearby levels into zones
              │  (ATR-adaptive)   │  using volatility-scaled width
              └────────┬──────────┘
                       ▼
              ┌───────────────────┐
              │      Scorer       │  Scores by method diversity,
              │                   │  timeframe weight, proximity
              └────────┬──────────┘
                       ▼
              ┌───────────────────┐
              │   A / B / C       │  A = high confluence (3+ methods)
              │   Grade Zones     │  B = moderate   C = single-method
              └───────────────────┘

Each method runs independently across its configured timeframes (daily, weekly, monthly, intraday). The clustering step detects where methods converge on the same price — a zone where Standard Pivots, Fibonacci 61.8%, and the prior week's high all land within a few points of each other scores much higher than a zone from a single moving average.

Methods

Method	Family	What It Computes
Standard Pivots	pivot	Classic floor trader PP, R1-R3, S1-S3
Camarilla	pivot	Camarilla H1-H4, L1-L4 from prior bar
Prior Session	session	Prior day/week/month high, low, close
VWAP Bands	volume	VWAP with 1/2/3 standard deviation bands
Volume Profile	volume	POC, Value Area High/Low from volume distribution
Bollinger Bands	envelope	20-period SMA with 2σ bands
Keltner Channels	envelope	20-period EMA with ATR-based bands
ATR Envelopes	envelope	Close ± 1x/2x ATR
MA Cluster	moving_average	SMA at 9, 21, 50, 100, 200 periods
Fibonacci	fibonacci	5-level retracement from swing high/low

API

Endpoint	Method	Description
/api/zones/{symbol}	GET	Compute and return scored zones
/api/recompute/{symbol}	POST	Force fresh data fetch and recompute
/api/methods	GET	List active methods and weights
/api/symbols	GET	List configured symbols
/api/ohlcv/{symbol}	GET	Daily OHLCV bars for charting

Project Structure

src/confluence_engine/
  models.py          Pydantic data models (Level, Zone, ScoredZone)
  methods/           10 technical analysis methods (Protocol-based plugins)
  engine/            Pipeline: fetch → compute → cluster → score
  data/              DuckDB cache + yfinance/Alpaca fetcher
  api/               FastAPI REST API
config/
  methods.yaml       Method config + data source TTLs
  symbols.yaml       Watchlist
  weights.json       Live-tunable method weights
frontend/            React + Vite + Tailwind + lightweight-charts
scripts/
  warm_cache.py      Pre-fetch data for instant dashboard loads
  daily_scan.py      CLI zone scanner for all symbols

CLI Scanner

uv run python scripts/daily_scan.py

Prints color-coded confluence zones for all configured symbols.

Development

uv run pytest                    # run tests (137 passing)
uv run pytest -m "not live" -v   # skip live data tests
uv run ruff check src/           # lint
uv run ruff format src/          # format

Tech Stack

• Backend: Python 3.12, FastAPI, Pydantic v2, DuckDB, pandas, yfinance
• Frontend: React 19, Vite, TypeScript, Tailwind CSS v4, lightweight-charts v5, Zustand
• Package management: uv (Python), npm (frontend)

License

MIT