CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4## Core Principles
5 
61. **Zero Duplication**: Always reuse or extend existing utilities instead of reimplementing
72. **Code Discovery First**: Search the codebase thoroughly before writing new functions
83. **Scope Discipline**: Edit only files required for the specific ticket
94. **Single Responsibility**: One purpose per function
105. **Atomic Commits**: One logical change per commit
11 
12## What NOT to Do
13 
14- **Build for imaginary future requirements** - Only implement what the current ticket requires
15- **Add complex error handling for unlikely scenarios** - Simple error handling for expected cases only
16- **Suggest design patterns unless actually required** - Use existing patterns, don't introduce new ones
17- **Optimize prematurely** - Focus on correctness first, optimize only when performance issues are proven
18- **Add configuration for rarely changing values** - Hard-code values that don't need to be configurable
19- **Create duplicate functionality** - Always search for and reuse existing utilities
20- **Write speculative code** - Each function should have a single, clear purpose tied to actual requirements
21 
22## Project Overview
23 
24Stock Options Tracker - An Astro-based web application for tracking and analyzing stock options with multi-factor scoring, historical performance tracking, and automated background data refresh via Cloudflare Workers.
25 
26## Tech Stack
27 
28- **Framework**: Astro 5.0.2 with server-side rendering
29- **Styling**: Tailwind CSS (via @astrojs/tailwind)
30- **Database**: Cloudflare D1 (SQLite)
31- **Background Jobs**: Cloudflare Workers with cron scheduling
32- **Data Sources**: Yahoo Finance 2, Finnhub API
33- **Deployment**: Cloudflare Pages
34 
35## Development Commands
36 
37```bash
38# Start development server (localhost:4321)
39npm run dev
40 
41# Build for production (includes type checking)
42npm run build
43 
44# Run linting and type checking
45npm run all
46 
47# Database migrations
48npm run db:migrate        # Local D1 database
49npm run db:migrate:prod    # Production database
50 
51# Background worker
52npm run worker:dev         # Run worker locally
53npm run worker:deploy      # Deploy to development
54npm run worker:deploy:prod # Deploy to production
55```
56 
57## Architecture
58 
59### Data Flow
601. User searches trigger data fetch from Yahoo Finance
612. Results cached in D1 database with scoring calculation
623. Background worker refreshes cached data every ~15 minutes during market hours
634. UI reads from cache (fast <500ms responses)
64 
65### Key Services
66 
67**src/services/optionsService.ts**
68- Fetches options data from Yahoo Finance
69- Manages caching strategy
70- Coordinates with database service
71 
72**src/services/database_service.ts**
73- All D1 database operations
74- Snapshot creation and retrieval
75- Symbol tracking management
76 
77**src/workers/background_refresh.ts**
78- Runs every minute (cron: `* * * * *`)
79- Round-robin refresh of tracked symbols
80- Market hours check (9:30 AM - 4:00 PM ET, weekdays)
81 
82### Database Schema
83 
84Key tables:
85- `stock_snapshots` - Current stock prices
86- `option_snapshots` - Individual option data
87- `option_score_snapshots` - Calculated scores
88- `symbol_tracking` - Symbols for background refresh
89 
90View: `option_data_with_scores` joins all data for display
91 
92### Options Scoring Algorithm
93 
94Multi-factor scoring in `src/utils/optionScorer.ts`:
95- Premium, Theta, Strike, DTE, IV, Liquidity scores
96- Spread penalty for bid-ask spreads
97- Results in score classes: excellent, good, moderate, weak, poor
98 
99## API Endpoints
100 
101All endpoints are server-side rendered Astro pages:
102- `GET /api/stock-options?symbol=AAPL`
103- `GET /api/historical-snapshots?symbol=AAPL`
104- `GET /api/top-performing-options?symbol=AAPL&days=30`
105- `GET /api/stock-performance?symbol=AAPL&days=30`
106- `POST /api/refresh-status` (requires auth)
107 
108## Component Structure
109 
110Astro components with scoped CSS:
111- `src/components/OptionsTable.astro` - Main options display
112- `src/components/optionRow.astro` - Individual option rendering
113- `src/components/historical_data_view.astro` - Historical trends
114 
115Use Tailwind utilities directly in components. Avoid @apply directive.
116 
117## Development Guidelines
118 
119### Astro Best Practices
120- Prioritize static generation where possible
121- Use partial hydration sparingly (client:idle, client:visible)
122- Keep components in `.astro` format when no client JS needed
123- Scoped styles within components
124 
125### TypeScript
126- Strict type checking enabled
127- Interfaces defined in `src/types/`
128- Use proper null checking and error handling
129 
130### Database Operations
131- Always use database_service.ts methods
132- Never expose database IDs in API responses
133- Cache-first approach for all reads
134 
135### Testing Single Features
136```bash
137# Test specific API endpoint
138curl http://localhost:4321/api/stock-options?symbol=AAPL
139 
140# Check worker execution
141npm run worker:dev
142# Then trigger manually via Wrangler dashboard
143 
144# View D1 data
145npx wrangler d1 execute options-tracker-local --local --command &quot;SELECT * FROM symbol_tracking&quot;
146```
147 
148## Environment Setup
149 
150Required `.env` file:
151```
152PUBLIC_FINNHUB_API_KEY=your_key_here
153```
154 
155Local D1 database binding in `astro.config.mjs`:
156- Database: `options-tracker-local`
157- Auto-created on first run
158 
159## Preferred Stocks
160 
161Hardcoded list in `src/enums/preferredStocks.ts`:
162TSLA, NET, LRCX, CRWD, NVDA, SE, KKR, BX, AAPL, GOOGL, META, AMD, AMZN, NFLX, MSFT
163 
164These receive priority 10 in background refresh (vs priority 5 for user-searched).
165 
166## Common Modifications
167 
168### Add New Preferred Stock
1691. Update `src/enums/preferredStocks.ts`
1702. Symbol automatically added to tracking on next page load
171 
172### Adjust Scoring Algorithm
1731. Modify weights in `src/utils/optionScorer.ts`
1742. Update thresholds in `src/enums/scoreThresholds.ts`
175 
176### Change Refresh Frequency
1771. Edit cron schedule in `wrangler.background.toml`
1782. Adjust round-robin logic in `background_refresh.ts` if needed
179 
180### Add New API Endpoint
1811. Create new file in `src/pages/api/`
1822. Export async GET/POST handler
1833. Use database_service.ts for data access
184 
185## Deployment Notes
186 
187Production uses Cloudflare Pages with Workers:
188- Main app deploys automatically via GitHub
189- Worker requires manual deployment: `npm run worker:deploy:prod`
190- Database migrations must be run separately: `npm run db:migrate:prod`
191 
192Monitor worker execution in Cloudflare dashboard under Workers > Logs.