Bullish Stock Scanner (V3)

A precision-first, trend-following stock scanner for halal-screened US equities. It fetches point-in-time data from the Massive market-data API, applies Minervini-style hard filters plus a gradient scoring engine gated on the broad-market regime, and validates predictions with backtesting — served through a FastAPI backend and a React/Cloudscape frontend.

V3 philosophy: prove the uptrend, then buy the first pullback — never bottom-fish. It deliberately emits fewer, higher-conviction signals (and zero signals in a bearish market). See docs/V3_VALIDATION_RESULTS.md and docs/V3_TUNING_REPORT.html for measured precision/return.

Features

Market-regime gate — SPY vs its 200-day SMA with 5-day persistence; a bearish market emits zero candidates, otherwise the BUY threshold is 65 (bullish) / 75 (neutral).
Minervini hard filters (H1–H6) — price above SMA150/200, golden cross, rising SMA200, within 25% of the 52-week high, ≥30% above the 52-week low. Any fail → excluded.
V3 gradient scoring (0–100) — Trend, Momentum, Strength (RSI + cross-universe RS percentile), Confirmation, Stage-2 + Pattern bonus; minus extension, climax/exhaustion, and indicator divergence penalties.
Backtesting — point-in-time (no look-ahead), regime-aware confusion matrix (TP/FP/FN/TN over the full universe), precision/recall/F1, and a $1,000-per-signal portfolio simulation.
Interactive threshold tuning — sliders default to the empirically optimal score 80 / gain 5%.
Live Scanner "Show all scanned" toggle — see every stock's status (Candidate / Below threshold / Failed filters), not just the buy candidates.
REST API (FastAPI + Swagger), Cloudscape React UI, 5-concurrent connection pooling, and a 308-test suite (unit + Hypothesis property + integration + backtest) with Playwright E2E.

Architecture

Backend pipeline (`backend/core/`, two-pass)

ScanOrchestrator.execute_scan() coordinates:

MarketRegimeAnalyzer → RegimeResult(regime, threshold, emit_signals). Bearish ⇒ short-circuit to zero candidates.
PASS 1 — RestApiClient fetches ≥252 trading bars per ticker; IndicatorCalculator computes the indicator set + raw relative strength.
Compute the RS percentile across the universe (two-pass requirement).
PASS 2 — ScoringEngine.passes_hard_filters() gate → calculate_enhanced_score(rs_percentile) → keep tickers scoring ≥ the regime threshold.
RankingService sorts by score; ScanStore persists to SQLite.

apply_signal_gate=False (used by backtesting) skips the bearish/threshold gates and returns the whole scored universe, so the confusion matrix and threshold sweeps see every stock.

Backtesting (backend/backtest/): BacktestEngine re-runs the scanner at historical as_of_dates; metrics.py builds the confusion matrix. Frontend (frontend/src/): App.tsx (Live Scanner + Backtest tabs) with Cloudscape BacktestPanel, ResultsTable, MarketRegimeBadge, etc.

Installation

Prerequisites

Python 3.10 or higher
Node.js 18 or higher (with npm)
POLYGON_TOKEN environment variable (must be set globally in shell configuration)

Backend Setup

The backend is a Python FastAPI application with SQLite for persistence.

# 1. Navigate to backend directory
cd backend

# 2. Create and activate virtual environment
python -m venv .venv

# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

# 3. Install all Python dependencies
pip install -r requirements.txt

# 4. Verify POLYGON_TOKEN is set (required for API access)
echo $POLYGON_TOKEN  # Should display your API token
# If not set, add to ~/.zshrc or ~/.bashrc:
# export POLYGON_TOKEN="your_token_here"

# 5. Optional: Override configuration defaults
# API_BASE_URL=https://api.massive.com/v2  (Massive market-data API)
# SERVER_PORT=8000  (default)
# LOG_LEVEL=INFO  (default)

Backend Environment Variables:

POLYGON_TOKEN (required) - Your Polygon.io API token
API_BASE_URL (optional) - Market data API endpoint (default: https://api.massive.com/v2)
SERVER_PORT (optional) - Backend server port (default: 8000)
LOG_LEVEL (optional) - Logging level (default: INFO)

Frontend Setup

The frontend is a React application built with Vite and TypeScript.

# 1. Navigate to frontend directory
cd frontend

# 2. Install all Node.js dependencies
npm install

# 3. Optional: Configure backend API URL
# Create frontend/.env file with:
# VITE_API_URL=http://localhost:8000
# (Only needed if backend runs on a different host/port)

Frontend Environment Variables:

VITE_API_URL (optional) - Backend API base URL (default: http://localhost:8000)

Usage

Running the Application

Start the Backend Server

The backend must be running before starting the frontend.

# 1. Navigate to backend directory and activate virtual environment
cd backend
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 2. Start the FastAPI development server
uvicorn main:app --reload --port 8000

# Server will start with hot-reload enabled
# Press Ctrl+C to stop the server

Backend will be available at:

API Base: http://localhost:8000
Swagger UI (Interactive API docs): http://localhost:8000/docs
Health Check: http://localhost:8000/api/v1/health

Start the Frontend Development Server

# In a new terminal window:
# 1. Navigate to frontend directory
cd frontend

# 2. Start the Vite development server
npm run dev

# Server will start with hot-reload enabled
# Press Ctrl+C to stop the server

Frontend will be available at: http://localhost:5173

Production Build and Preview

To build the frontend for production and test the build:

cd frontend

# Build for production (outputs to dist/)
npm run build

# Preview the production build locally
npm run preview

# Preview server will start at: http://localhost:4173

Production Build Output:

Build artifacts are generated in frontend/dist/
Includes optimized JavaScript, CSS, and static assets
Ready for deployment to any static hosting service

Backtesting

The system includes a backtesting framework to validate predictions against historical data.

API Endpoints

# Single-date backtest (point-in-time, no look-ahead bias)
curl -X POST http://localhost:8000/api/v1/backtest/single \
  -H "Content-Type: application/json" \
  -d '{"as_of_date": "2025-05-01", "tickers": ["AAPL","MSFT","NVDA"], "horizon_days": 30}'

# Rolling backtest over date range
curl -X POST http://localhost:8000/api/v1/backtest/rolling \
  -H "Content-Type: application/json" \
  -d '{"start_date":"2024-06-01","end_date":"2025-05-01","tickers":["AAPL","MSFT"],"frequency":"monthly","horizon_days":30}'

Backtest UI

Access at http://localhost:5173 → Backtest tab. Features:

Date picker for historical scan date
Dynamic sliders to tune score threshold (10-100) and gain threshold (1-25%)
Live confusion matrix (TP/FP/FN/TN) recalculates without API calls
Accuracy, Precision, Recall, F1 metrics
Sortable trade-by-trade results table

Optimal Settings (from the 714-trade V3 tuning — `docs/V3_TUNING_REPORT.html`)

Full halal universe (~212 tickers) × 10 dates (2023–2025), buy-and-hold 30 trading days:

Parameter	Value	Rationale
Score Threshold	80	Best precision (~60% @ +5%) and best portfolio return (UI sliders default to 80)
Gain Threshold	5%	Realistic "win" bar; ~72% of score≥80 signals reach +3%, ~60% reach +5%
Horizon	30 trading days	The evaluation window

Honest results: in-sample precision ~81.5%, out-of-sample ~56.7%, recall ~33–35%, and a +2.2% / 30-day cycle portfolio profit rate at score≥80 — net positive but with high month-to-month variance (e.g. 2024-11 strong vs 2025-03 weak). FP and TP trades are statistically near-identical on these indicators, so this is the realistic ceiling for a pure-technical scanner.

Testing

The project includes comprehensive test coverage across unit, property-based, integration, and end-to-end tests.

Backend Testing

cd backend

# Run all tests with coverage report
pytest --cov=. --cov-report=html

# Run specific test categories
pytest tests/unit/              # Unit tests
pytest tests/property/          # Property-based tests
pytest tests/integration/       # Integration tests

# View coverage report
open htmlcov/index.html

Test Results:

Unit tests: 151/151 passing (100%)
Integration tests: 52/52 passing (100%)
Property tests: 25/35 passing (71% - framework warnings only)
Total: 203/203 core tests passing
Coverage: >80% across all components

Frontend Testing

cd frontend

# Run component tests
npm test

# Run E2E tests with Playwright
npx playwright test                    # Run all E2E tests
npx playwright test --headed          # Run with visible browser
npx playwright test comprehensive-test # Run comprehensive test suite
npx playwright show-report            # View test report

# Run specific test suites
npx playwright test happy-path
npx playwright test error-scenarios
npx playwright test loading-states
npx playwright test results-display

E2E Test Coverage:

5 comprehensive test suites
20+ individual test scenarios
60+ screenshots captured automatically during test execution
Tests cover: happy path, error handling, loading states, results display, accessibility, keyboard navigation, responsive design, input variations
Screenshots location: frontend/test-results/screenshots/

E2E Test Scenarios Include:

Happy Path: Complete scan workflow with valid data
Error Scenarios: Validation errors, empty input, API failures
Loading States: Spinner display, button disable during scan
Results Display: Table rendering, market regime badge, signal indicators
Comprehensive Suite:
- Initial load → Input → Scan → Results analysis
- Large dataset testing (20+ tickers)
- Input variations (comma/space separated, mixed case)
- UI interaction and state persistence
- Accessibility and keyboard navigation
- Responsive design (desktop/tablet/mobile views)

Using the Web Interface

Start both backend and frontend servers (see "Running the Application" above)
Open browser to http://localhost:5173
Enter ticker symbols in the input field (comma or space-separated)
- Example: AAPL, MSFT, GOOGL, NVDA, TSLA
Click "Run Scan" to initiate analysis
View results:
- Market regime indicator (Bullish/Bearish/Neutral)
- Ranked table with ticker scores and signals
- Individual indicator breakdowns

API Example

Trigger a scan with tickers:

curl -X POST http://localhost:8000/api/v1/scan \
  -H "Content-Type: application/json" \
  -d '{"tickers": ["AAPL", "MSFT", "GOOGL"]}'

Retrieve a previous scan by ID:

curl http://localhost:8000/api/v1/scan/{scan_id}

Check backend health:

curl http://localhost:8000/api/v1/health

Sample Response:

{
  "scan_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "market_regime": "bullish",
  "ranked_tickers": [
    {
      "ticker": "AAPL",
      "bullish_score": 85,
      "signals": {
        "price_above_sma50": true,
        "price_above_ema20": true,
        "macd_above_signal": true,
        "macd_histogram_positive": true,
        "volume_above_average": false,
        "relative_strength_positive": true
      },
      "current_price": 178.50,
      "indicators": {
        "sma_50": 175.20,
        "ema_20": 177.80,
        "macd_line": 1.25,
        "macd_signal": 0.95,
        "macd_histogram": 0.30,
        "avg_volume_20": 52000000.0,
        "relative_strength": 2.5
      }
    }
  ],
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "ticker_count": 3,
    "duration_seconds": 2.5
  }
}

Market Regime Analysis

The MarketRegimeAnalyzer determines current market conditions by analyzing the SPY index:

from core.regime_analyzer import MarketRegimeAnalyzer
from core.api_client import RestApiClient
from api.models import MarketRegime

# Initialize with API client
api_client = RestApiClient()
analyzer = MarketRegimeAnalyzer(api_client)

# Analyze current market regime
regime = await analyzer.analyze_regime()

if regime == MarketRegime.BULLISH:
    print("Market is bullish - favorable for long positions")
elif regime == MarketRegime.BEARISH:
    print("Market is bearish - caution advised")
else:
    print("Market is neutral - mixed signals")

The analyzer fetches SPY data and calculates 50-day and 200-day SMAs. Classification:

Bullish: SMA(50) > SMA(200) - uptrend confirmed
Bearish: SMA(50) < SMA(200) × 0.98 - downtrend confirmed
Neutral: SMA(50) within 2% of SMA(200) - transitional phase

If API errors occur, the analyzer defaults to NEUTRAL to ensure the scan continues.

Technical Indicators

The IndicatorCalculator class computes all technical indicators from price and volume data:

from core.indicator_calculator import IndicatorCalculator
from core.models import StockData
import numpy as np

# Create stock data
stock_data = StockData(
    ticker="AAPL",
    prices=np.array([...]),  # 60+ days of closing prices
    volumes=np.array([...]),  # 60+ days of volume
    timestamps=np.array([...])
)

market_data = StockData(
    ticker="SPY",
    prices=np.array([...]),
    volumes=np.array([...]),
    timestamps=np.array([...])
)

# Calculate all indicators
calc = IndicatorCalculator()
indicators = calc.calculate_all(stock_data, market_data)

# Access individual indicators
print(f"SMA(50): {indicators.sma_50}")
print(f"EMA(20): {indicators.ema_20}")
print(f"MACD Line: {indicators.macd_line}")
print(f"MACD Signal: {indicators.macd_signal}")
print(f"MACD Histogram: {indicators.macd_histogram}")
print(f"Avg Volume(20): {indicators.avg_volume_20}")
print(f"Relative Strength: {indicators.relative_strength}")

Bullish Scoring

The ScoringEngine class assigns scores based on technical indicator signals:

from core.scoring_engine import ScoringEngine
from core.models import TechnicalIndicators

# Create scoring engine
engine = ScoringEngine()

# Create indicators (from IndicatorCalculator)
indicators = TechnicalIndicators(
    sma_50=175.20,
    ema_20=177.80,
    macd_line=1.25,
    macd_signal=0.95,
    macd_histogram=0.30,
    avg_volume_20=52000000.0,
    relative_strength=2.5
)

# Calculate bullish score
score, signals = engine.calculate_score(
    current_price=178.50,
    current_volume=55000000,
    indicators=indicators
)

print(f"Bullish Score: {score}/100")
print(f"Price above SMA(50): {signals.price_above_sma50}")
print(f"Price above EMA(20): {signals.price_above_ema20}")
print(f"MACD bullish: {signals.macd_above_signal}")
print(f"MACD histogram positive: {signals.macd_histogram_positive}")
print(f"Volume surge: {signals.volume_above_average}")
print(f"Outperforming market: {signals.relative_strength_positive}")

Scoring System (Max 100 points)

Indicator	Condition	Points
SMA(50)	Price > SMA(50)	20
EMA(20)	Price > EMA(20)	15
MACD	MACD line > Signal line	20
MACD Histogram	Histogram > 0	10
Volume	Volume > 1.2 × Avg(20)	15
Relative Strength	RS > 0 (outperforming market)	20

Market Regime Classification

Bullish: Market index SMA(50) > SMA(200)
Bearish: Market index SMA(50) < SMA(200) × 0.98
Neutral: Market index SMA(50) within 2% of SMA(200)

Testing

The project includes comprehensive testing at all levels: unit tests, property-based tests, integration tests, and end-to-end tests.

Backend Tests

All backend tests use pytest with coverage reporting and hypothesis for property-based testing.

cd backend
source .venv/bin/activate  # Ensure virtual environment is active

# Run all tests (unit + property + integration)
pytest

# Run with coverage report
pytest --cov=. --cov-report=html
# Open htmlcov/index.html in browser to view coverage

# Run only unit tests
pytest tests/unit/

# Run only property-based tests
pytest tests/property/

# Run only integration tests
pytest tests/integration/

# Run specific test file
pytest tests/unit/test_indicator_calculator.py

# Run with verbose output
pytest -v

# Run tests matching a pattern
pytest -k "test_sma"

Backend Test Coverage:

Unit Tests (tests/unit/): Test individual components in isolation
- API Client: Connection pooling, retry logic, caching, error handling
- Universe Builder: Ticker validation and filtering
- Indicator Calculator: SMA, EMA, MACD, Volume, Relative Strength calculations
- Market Regime Analyzer: Regime classification logic
- Scoring Engine: Individual scoring rules and aggregation
- Ranking Service: Sorting and stability
- Scan Orchestrator: Pipeline coordination
- API Endpoints: Request/response handling
Property-Based Tests (tests/property/): Verify mathematical correctness across random inputs using hypothesis
- Indicator calculation properties
- Scoring rule properties
- Ranking properties
Integration Tests (tests/integration/): Test component interactions
- Universe Builder + API Client
- Indicator Calculator + Scoring Engine + Ranking Service
- Full scan endpoint workflow

Coverage Target: >80% for all components

Frontend Tests

The frontend uses Vitest for unit/component tests and Playwright for end-to-end tests.

Unit and Component Tests (Vitest + React Testing Library)

cd frontend

# Run all unit/component tests
npm test

# Run tests in watch mode (auto-rerun on file changes)
npm run test:watch

# Run tests with UI (interactive mode)
npm run test:ui

# Build to verify no TypeScript errors
npm run build

Component Test Coverage:

Input validation (empty input, whitespace, invalid formats)
Scan triggering (button click, Enter key, comma/space-separated tickers)
Loading states (spinner display, button disabled state)
Results display (market regime badge, ranked table, score formatting)
Error handling (network errors, validation errors, error clearing)
State management (multiple scans, result updates)

End-to-End Tests (Playwright)

E2E tests verify complete user workflows using real browser automation with screenshot capture.

cd frontend

# Install Playwright browsers (first time only)
npx playwright install

# Run all E2E tests (headless mode)
npx playwright test

# Run tests in headed mode (see browser window)
npx playwright test --headed

# Run tests in UI mode (interactive debugging with time travel)
npx playwright test --ui

# Run specific test file
npx playwright test happy-path
npx playwright test error-scenarios

# Run tests in specific browser
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit

# View HTML test report
npx playwright show-report

# Debug a specific test
npx playwright test --debug happy-path

E2E Test Suites:

happy-path.spec.ts - Complete successful workflow
- Enter multiple tickers
- Trigger scan
- Verify results table displays correctly
- Verify market regime badge
- Verify ranking order
error-scenarios.spec.ts - Error handling flows
- Validation error when no tickers entered
- API error handling when backend unavailable
- Error clearing when new scan initiated
loading-states.spec.ts - Loading state verification
- Spinner appears during scan
- Button disabled during scan
- Loading state clears when results arrive
results-display.spec.ts - Results rendering verification
- Market regime badge displays correctly
- Results table shows all required columns
- Tickers ranked in descending score order
- Signal indicators display for each ticker
- Score formatting is correct

Screenshot Capture:

Screenshots saved to frontend/test-results/screenshots/
Automatically captured at key interaction points:
- Initial page load
- After user input
- During loading state
- Results displayed
- Error states
Useful for visual regression testing and debugging

E2E Test Prerequisites:

Backend server must be running:

cd backend
source .venv/bin/activate
uvicorn main:app --reload

Valid POLYGON_TOKEN set in environment
Frontend dev server (auto-started by Playwright via webServer config)

E2E Test Limitations:

Tests interact with real backend API and external data source
May fail if backend is down, credentials invalid, or network issues occur
May be slower than unit tests due to browser automation overhead

Running All Tests

To verify the complete system:

# Terminal 1: Backend tests
cd backend
source .venv/bin/activate
pytest --cov=. --cov-report=html

# Terminal 2: Frontend unit tests
cd frontend
npm test

# Terminal 3: Start backend for E2E tests
cd backend
source .venv/bin/activate
uvicorn main:app --reload

# Terminal 4: Frontend E2E tests
cd frontend
npx playwright test

Project Structure

TechnicalStockPrediction/
├── backend/                         # Python FastAPI backend
│   ├── main.py                      # FastAPI application entry point
│   ├── config.py                    # Configuration from environment variables
│   ├── requirements.txt             # Python dependencies
│   ├── pytest.ini                   # Pytest configuration
│   ├── scanner.db                   # SQLite database (gitignored, auto-created)
│   ├── api/                         # API layer
│   │   ├── endpoints.py             # API route handlers (✓ implemented)
│   │   └── models.py                # Pydantic request/response models (✓ implemented)
│   ├── core/                        # Business logic layer
│   │   ├── models.py                # Internal data classes (✓ implemented)
│   │   ├── api_client.py            # REST API client (✓ implemented)
│   │   ├── universe_builder.py      # Ticker validation (✓ implemented)
│   │   ├── indicator_calculator.py  # Technical indicators (✓ implemented)
│   │   ├── regime_analyzer.py       # Market regime analysis (✓ implemented)
│   │   ├── scoring_engine.py        # Bullish scoring (✓ implemented)
│   │   ├── ranking_service.py       # Ranking service (✓ implemented)
│   │   ├── scan_store.py            # SQLite persistence (✓ implemented)
│   │   └── orchestrator.py          # Scan orchestrator (✓ implemented)
│   ├── utils/                       # Utility layer
│   │   └── logging.py               # Logging configuration (✓ implemented)
│   └── tests/                       # Test suite (✓ comprehensive coverage)
│       ├── unit/                    # Unit tests (✓ all components tested)
│       ├── property/                # Property-based tests (✓ hypothesis tests)
│       └── integration/             # Integration tests (✓ pipeline tests)
├── frontend/                        # React TypeScript frontend
│   ├── package.json                 # Node dependencies and scripts (✓ configured)
│   ├── vite.config.ts               # Vite build configuration (✓ configured)
│   ├── tsconfig.json                # TypeScript configuration (✓ configured)
│   ├── playwright.config.ts         # Playwright E2E test config (✓ configured)
│   ├── vitest.config.ts             # Vitest unit test config (✓ configured)
│   ├── index.html                   # HTML entry point (✓ implemented)
│   ├── .env                         # Environment variables (gitignored)
│   ├── dist/                        # Production build output (gitignored)
│   ├── src/
│   │   ├── App.tsx                  # Main application component (✓ implemented)
│   │   ├── main.tsx                 # React entry point (✓ implemented)
│   │   ├── components/              # React components (✓ all implemented)
│   │   │   ├── ScanButton.tsx       # Scan trigger button
│   │   │   ├── LoadingIndicator.tsx # Loading state UI
│   │   │   ├── MarketRegimeBadge.tsx # Market regime display
│   │   │   ├── ResultsTable.tsx     # Ranked ticker table
│   │   │   ├── SignalBadges.tsx     # Indicator signal badges
│   │   │   └── ErrorMessage.tsx     # Error display
│   │   ├── services/                # Business logic services (✓ implemented)
│   │   │   └── scanApi.ts           # Backend API client
│   │   ├── types/                   # TypeScript type definitions (✓ implemented)
│   │   │   └── scan.ts              # Scan-related types
│   │   └── styles/                  # CSS styles (✓ implemented)
│   │       └── App.css              # Application styles
│   ├── tests/                       # Test directory (✓ comprehensive tests)
│   │   ├── App.test.tsx             # Component tests (✓ implemented)
│   │   └── e2e/                     # End-to-end tests (✓ all implemented)
│   │       ├── happy-path.spec.ts
│   │       ├── error-scenarios.spec.ts
│   │       ├── loading-states.spec.ts
│   │       └── results-display.spec.ts
│   └── test-results/                # Test results directory (gitignored)
│       └── screenshots/             # E2E test screenshots
├── .kiro/                           # Kiro AI assistant configuration
│   ├── specs/                       # Feature specifications
│   └── steering/                    # AI guidance documents
├── .gitignore                       # Git ignore patterns
├── LICENSE                          # Apache License 2.0
├── README.md                        # Project documentation (this file)
└── MANIFEST.md                      # Quick project summary

Implementation Status: ✅ MVP Complete

All backend components implemented and tested
All frontend components implemented and tested
Full test coverage (unit, property-based, integration, E2E)
Production build verified and working
SQLite persistence for scan results
Comprehensive API documentation at /docs

Dependencies

Backend

FastAPI 0.104+: Web framework with automatic API documentation
uvicorn: ASGI server for running FastAPI
httpx: Async HTTP client for API calls
pandas 2.1+: Data manipulation and analysis
numpy 1.26+: Numerical computing
pydantic 2.4+: Data validation and settings
python-dotenv: Environment variable management
aiosqlite: Async SQLite database access
pytest: Testing framework
hypothesis: Property-based testing
pytest-asyncio: Async test support
pytest-cov: Coverage reporting

Frontend

React 18+: UI framework
TypeScript 5.0+: Type-safe JavaScript
Vite: Fast build tool and dev server
Cloudscape Design System: AWS-style UI components library
- @cloudscape-design/components: UI component library
- @cloudscape-design/global-styles: Global styles and themes
- @cloudscape-design/collection-hooks: Data collection utilities
Vitest: Fast unit test runner
@testing-library/react: Component testing utilities
@playwright/test: End-to-end browser testing
ESLint: Code linting and formatting

Troubleshooting

Backend Issues

Issue: POLYGON_TOKEN not found error

# Verify token is set
echo $POLYGON_TOKEN

# If not set, add to shell configuration:
# For zsh (macOS default):
echo 'export POLYGON_TOKEN="your_token_here"' >> ~/.zshrc
source ~/.zshrc

# For bash:
echo 'export POLYGON_TOKEN="your_token_here"' >> ~/.bashrc
source ~/.bashrc

Issue: ModuleNotFoundError when running backend

# Ensure virtual environment is activated
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Reinstall dependencies
pip install -r requirements.txt

Issue: Database errors or scanner.db issues

# Delete and recreate database
rm backend/scanner.db
# Restart backend server - it will auto-create the database

Issue: API rate limiting or connection errors

Check your Polygon.io API tier limits
Reduce number of tickers in scan
Wait a few minutes and retry
Verify API_BASE_URL is correct (default: https://api.massive.com/v2)

Issue: Port 8000 already in use

# Find process using port 8000
lsof -i :8000

# Kill the process
kill -9 <PID>

# Or use a different port
uvicorn main:app --reload --port 8001
# Update frontend .env: VITE_API_URL=http://localhost:8001

Frontend Issues

Issue: npm install fails

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Issue: Frontend can't connect to backend

# Verify backend is running
curl http://localhost:8000/api/v1/health

# Check CORS settings in backend
# Verify VITE_API_URL in frontend/.env matches backend URL

Issue: Build fails with TypeScript errors

# Check for TypeScript errors
npx tsc --noEmit

# Clear build cache
rm -rf dist node_modules/.vite
npm run build

Issue: E2E tests fail

# Ensure backend is running first
cd backend && uvicorn main:app --reload

# Reinstall Playwright browsers
cd frontend
npx playwright install

# Run with debug mode to see what's failing
npx playwright test --debug

Issue: Port 5173 or 4173 already in use

# Find and kill process
lsof -i :5173
kill -9 <PID>

# Or configure different port in vite.config.ts

Common Issues

Issue: Scan returns no results or errors for all tickers

Verify POLYGON_TOKEN is valid and has API access
Check ticker symbols are valid (uppercase, alphanumeric)
Try with well-known tickers first: AAPL, MSFT, GOOGL
Check Polygon.io API status

Issue: Slow scan performance

Expected: ~2-3 seconds for 3-5 tickers
Scans with 50+ tickers may take 10-15 seconds
API connection pooling limits to 5 concurrent requests
Check network connection quality

Issue: Cannot connect to backend error in frontend

Verify backend is running: curl http://localhost:8000/api/v1/health
Check backend URL in frontend/.env
Verify no firewall blocking localhost connections
Check browser console for CORS errors

API Documentation

The backend provides automatic interactive API documentation powered by FastAPI:

Swagger UI: http://localhost:8000/docs
- Interactive API testing interface
- Try out endpoints directly from browser
- View request/response schemas
- See all available endpoints
ReDoc: http://localhost:8000/redoc
- Alternative documentation view
- More readable for API reference
- Export as OpenAPI spec

Available Endpoints

POST /api/v1/scan - Trigger a new stock scan
GET /api/v1/scan/{scan_id} - Retrieve previous scan results by UUID
GET /api/v1/health - Health check endpoint
GET /docs - Swagger UI documentation
GET /redoc - ReDoc documentation

Future Enhancements

Advanced indicators (RSI, Bollinger Bands, Stochastic)
Chart pattern recognition
Machine learning-based scoring
Historical backtesting
User authentication and watchlists
Real-time price updates via WebSocket
Custom scoring weights
Multi-timeframe analysis

License

Apache License 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.claude/spec		.claude/spec
.kiro		.kiro
.vscode		.vscode
backend		backend
data		data
docs		docs
frontend		frontend
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Bullish Stock Scanner (V3)

Features

Architecture

Backend pipeline (backend/core/, two-pass)

Installation

Prerequisites

Backend Setup

Frontend Setup

Usage

Running the Application

Start the Backend Server

Start the Frontend Development Server

Production Build and Preview

Backtesting

API Endpoints

Backtest UI

Optimal Settings (from the 714-trade V3 tuning — docs/V3_TUNING_REPORT.html)

Testing

Backend Testing

Frontend Testing

Using the Web Interface

API Example

Market Regime Analysis

Technical Indicators

Bullish Scoring

Scoring System (Max 100 points)

Market Regime Classification

Testing

Backend Tests

Frontend Tests

Unit and Component Tests (Vitest + React Testing Library)

End-to-End Tests (Playwright)

Running All Tests

Project Structure

Dependencies

Backend

Frontend

Troubleshooting

Backend Issues

Frontend Issues

Common Issues

API Documentation

Available Endpoints

Future Enhancements

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Backend pipeline (`backend/core/`, two-pass)

Optimal Settings (from the 714-trade V3 tuning — `docs/V3_TUNING_REPORT.html`)