KLineLens

For traders and developers, KLineLens stresses data ownership and strategy extensibility.

• Bring-your-own market data: switch Yahoo Finance, TwelveData, Alpaca, Alpha Vantage, etc. via environment variables; free tiers to start, paid keys when you need reliable volume—no single-vendor lock-in.
• Code your own strategies: implement modules against a unified strategy interface, register them, and they flow through the terminal UI and API; built-in playbooks and 0DTE are reference implementations—community can add strategies and providers (see CUSTOM_STRATEGY.md, CONTRIBUTING.md).

• Full timeframe stack: 1m/5m intraday through 15m/1h/1d swing; trend / range / chop with confidence.
• Built-in 0DTE: state-machine-driven same-day options plan at the underlying level—no options-chain quotes required.
• Pluggable strategies: extend as modules on the same analysis + UI rails.
• Breakout confirmation: three factors to reduce false breaks—close confirmation, RVOL ≥ 1.8, outcome vs ATR threshold (see engine spec).
• Optional AI narrative: OpenAI / Google APIs for bilingual commentary.

Market structure

Extended hours

Languages

Full Chinese UI and AI commentary; English UI and commentary; extend via i18n.

Same-day ultra short-dated options planning driven by a state machine; typical path:

WAIT → WATCH → ARMED → ENTER → HOLD → TRIM → EXIT

Output is an underlying-level plan (prices, targets, stops, phases)—usable in MVP without live options-chain feeds.

Suggestion: prove the loop on Yahoo, then switch to TwelveData or similar for better volume-sensitive metrics.

MVP uses monorepo + three tiers: Web (Next.js) ↔ API (FastAPI) ↔ Core (pure Python analytics package).

┌─────────────────────────────────────────────┐
│              Next.js Frontend                │
│  Chart · Zones · Strategy · Timeline · AI  │
│  i18n · Settings · Watchlist                 │
└────────────────────┬────────────────────────┘
                     │ REST API + SSE
┌────────────────────▼────────────────────────┐
│              FastAPI Backend                │
│  Analysis Engine (Pure Python call)        │
│  Strategy Layer: Playbook | 0DTE | Custom   │
│  Provider Layer: Yahoo | TwelveData | …    │
└─────────────────────────────────────────────┘

Directory layout (summary)

KLineLens/
├── apps/web/          # Next.js
├── apps/api/          # FastAPI: routes / providers / cache
├── packages/core/     # Pure Python: features, structure, behavior, …
├── docs/
├── infra/             # Docker, etc.
├── MASTER_SPEC.md
└── README.md

Typical detail-page requests

1. GET /v1/bars: TTL cache hit skips downstream; miss pulls bars from the provider.
2. POST /v1/analyze: Core analyze() returns structure/behavior/timeline/playbook reports for the UI panels.

Auto refresh

Frontend re-issues POST /analyze about every 60s; bars may be cached while timeline state compares successive reports server-side to decide whether to emit events.

Storage notes (from architecture doc)

• Bars: in-process TTL cache in the API (e.g. 60s).
• Timeline state: MVP in-memory dict (lost on restart); future Redis/DB.
• Signal evaluations: persisted to apps/api/data/klinelens.db SQLite.
• Frontend evidence/timeline: localStorage keyed by trading day.

MVP acceptance checklist

• Home ticker search navigates to the detail page.
• 1m candles with zones/signals visible.
• Behavior probabilities, evidence, timeline, playbook panels visible.
• Language setting applies globally.
• docker compose up brings up a working stack.

Interfaces, state-machine patterns, frontend wiring, and tests live in CUSTOM_STRATEGY.md and ENGINE_SPEC.md.

Prereq: Docker Desktop installed and running.

git clone https://github.com/songzhiyuan98/KLineLens.git
cd KLineLens
cp .env.example .env
# Edit .env: PROVIDER, API keys, CACHE_TTL, API_PORT, WEB_PORT, etc.

docker compose up -d --build
docker compose ps

Open http://localhost:3000 and enter a ticker (e.g. TSLA, QQQ, SPY).

docker compose down          # stop
git pull && docker compose up -d --build   # update

Local dev (no Docker)

# Terminal 1
cd apps/api && pip install -r requirements.txt
uvicorn src.main:app --reload --port 8000

# Terminal 2
cd apps/web && npm install && npm run dev

Environment variables: docs/CONFIG.md; deployment: docs/DEPLOYMENT.md.

PRs welcome: bugs, features, providers, docs, tests, UI, custom strategies. Check Issues first; open a discussion issue for large changes.

• Branches: feature/…, fix/…, docs/…
• Commits: Conventional Commits (feat:, fix:, etc.)
• New provider: implement MarketDataProvider, register factory, update .env.example and docs/PROVIDER.md, add tests
• Standards: Python type hints + docstrings; explicit TS types; avoid magic numbers; solid errors and tests

Full guide: CONTRIBUTING.md and CLAUDE.md.

• v0.8 — Extended hours, 0DTE, custom strategies
• v0.7 — Responsive layout, multilingual
• v0.6 — Terminal-style UI, AI commentary
• v1.0 — WebSocket streaming, signal backtests
• v1.1 — Dark mode, mobile
• v2.0 — Multi-timeframe linkage, options chain integration

License: MIT—personal or commercial use allowed; retain license notices.

For education and information only. The tool applies technical analysis to price/volume data and is not investment advice. Past performance does not guarantee future results. Do your own research and accept trading risk.