Market-options-stocks-Scanner: Instructions file for Claude Code

CLAUDE.md — AI Agent Constitution

MANDATORY STARTUP PROTOCOL: Read this file COMPLETELY at the start of EVERY session. Then confirm to the user: "Ready. [X modules complete]. Next step: [Y]. Shall we begin?"

---

Primary Directives — Never Ignored

ID	Directive	Why it matters
PD-1	NEVER hardcode secrets	Exposed API keys = compromised account
PD-2	NEVER use float for money	Precision errors = real losses
PD-3	ALWAYS Blueprint before code	No plan = spaghetti code
PD-4	MAX 2 files per turn	Controllable, reviewable changes
PD-5	ALWAYS read before modifying	Never assume code state
PD-6	Tests mandatory for financial logic	No tests = no confidence in production
PD-7	Explain in user's language	Communication clarity
PD-8	Complete code, never fragments	Fragments create broken code
PD-9	Update PROJECT_CONFIG.md on end	Next session depends on it

---

System Architecture

Official Tech Stack

BACKEND:   Python 3.12 + FastAPI + SQLAlchemy 2.0 + Pydantic v2
FRONTEND:  TypeScript + Next.js 16 + React 19 + Zustand + Tailwind v4
DATABASE:  PostgreSQL 16 (persistence) + Redis 7 (cache & real-time pub/sub)
INFRA:     Docker Compose (local dev) + GitHub Actions (CI/CD)

Architecture Layers — Never Skip

HTTP Request
    ↓
API Router (FastAPI)     ← Routing and input validation only
    ↓
Service Layer            ← ALL business logic goes here
    ↓
Repository Layer         ← Database access only
    ↓
PostgreSQL / Redis

Golden rule: If business logic is in the router or frontend → it's wrong.

4-Phase Architecture — The Quantitative Funnel

┌─────────────────────────────────────────────────────────────────┐
│  PHASE A — Scanner                                              │
│  Input:   Thousands of market tickers (REST APIs)              │
│  Process: Basic filters: volume, volatility, liquidity         │
│  Output:  ~300 candidates as MarketSnapshot                    │
└────────────────────────────┬────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│  PHASE B — Microstructure Filter (NO network, local only)      │
│  Input:   300 candidates                                       │
│  Process: VPIN + Order Flow Imbalance (OFI)                    │
│  Output:  Top 20 candidates                                    │
└────────────────────────────┬────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│  PHASE C — Options Analysis                                    │
│  Input:   Top 20 candidates                                    │
│  Process: Download options chains, select by criteria           │
│  Output:  Top 5 contracts (symbol + strike + expiry)           │
└────────────────────────────┬────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│  PHASE D — Real-Time Monitor (WebSocket tick-by-tick)          │
│  Input:   5 contracts                                          │
│  Process: Live feed, generates execution signals               │
│  Output:  Signals → Frontend → Dashboard                       │
└─────────────────────────────────────────────────────────────────┘