| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 35 | 0% |
| Commands | 0 | 0 | 9 | 0% |
| Section tags | 2 | 2 | 9 | 15% |
What each file covers
Sections
0 shared · 5 only in A · 35 only in B- − TypeScript Best Practices
- − Type Safety & Configuration
- − Type Definitions
- − Advanced Patterns
- − Code Organization
- + CLAUDE.md
- + Core Principles
- + What NOT to Do
- + Project Overview
- + Tech Stack
- + Development Commands
- + Start development server (localhost:4321)
- + Build for production (includes type checking)
- + Run linting and type checking
- + Database migrations
- + Background worker
- + Architecture
- + Data Flow
- + Key Services
- + Database Schema
- + Options Scoring Algorithm
- + API Endpoints
- + Component Structure
- + Development Guidelines
- + Astro Best Practices
- + TypeScript
- + Database Operations
- + Testing Single Features
- + Test specific API endpoint
- + Check worker execution
- + Then trigger manually via Wrangler dashboard
- + View D1 data
- + Environment Setup
- + Preferred Stocks
- + Common Modifications
- + Add New Preferred Stock
- + Adjust Scoring Algorithm
- + Change Refresh Frequency
- + Add New API Endpoint
- + Deployment Notes
Commands
0 shared · 0 only in A · 9 only in B- + npm run dev
- + npm run build
- + npm run all
- + npm run db:migrate
- + npm run db:migrate:prod
- + npm run worker:dev
- + npm run worker:deploy
- + npm run worker:deploy:prod
- + npx wrangler d1 execute options-tracker-local --local --command "SELECT * FROM symbol_tracking"
Section tags
2 shared · 2 only in A · 9 only in B- − do-not
- − docs
- + setup
- + build
- + test
- + architecture
- + database
- + api
- + ui
- + deployment
- + agent-behaviour
- code-style
- types
Line diff
sferg989/fergfo.om · .cursor/rules/ts.mdc
@@ −1 @@
1---
2description:
3globs:
4alwaysApply: true
5---
6# TypeScript Best Practices
7
8## Type Safety & Configuration
9
10- Enable `strict: true` in [tsconfig.json](mdc:tsconfig.json) with additional flags:
11 - `noImplicitAny: true`
12 - `strictNullChecks: true`
13 - `strictFunctionTypes: true`
14 - `strictBindCallApply: true`
15 - `strictPropertyInitialization: true`
16 - `noImplicitThis: true`
17 - `alwaysStrict: true`
18 - `exactOptionalPropertyTypes: true`
19- Never use `// @ts-ignore` or `// @ts-expect-error` without explanatory comments
20- Use `--noEmitOnError` compiler flag to prevent generating JS files when TypeScript errors exist
21
22## Type Definitions
23
24- Do not ever use `any`. Ever. If you feel like you have to use `any`, use `unknown` instead.
25- Explicitly type function parameters, return types, and object literals.
26- Please don't ever use Enums. Use a union if you feel tempted to use an Enum.
27- Use `readonly` modifiers for immutable properties and arrays
28- Leverage TypeScript's utility types (`Partial`, `Required`, `Pick`, `Omit`, `Record`, etc.)
29- Use discriminated unions with exhaustiveness checking for type narrowing
30
31## Advanced Patterns
32
33- Implement proper generics with appropriate constraints
34- Use mapped types and conditional types to reduce type duplication
35- Leverage `const` assertions for literal types
36- Implement branded/nominal types for type-level validation
37## Code Organization
38
39- Organize types in dedicated files (types.ts) or alongside implementations
40- Document complex types with JSDoc comments
41- Create a central `types.ts` file or a `src/types` directory for shared types
42
sferg989/fergfo.om · CLAUDE.md
@@ +1 @@
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 "SELECT * FROM symbol_tracking"
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.
@@ −1 +1 @@
1−---
2−description:
3−globs:
4−alwaysApply: true
5−---
6−# TypeScript Best Practices
1+# CLAUDE.md
72
8−## Type Safety & Configuration
3+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+## Core Principles
95
10−- Enable `strict: true` in [tsconfig.json](mdc:tsconfig.json) with additional flags:
11− - `noImplicitAny: true`
12− - `strictNullChecks: true`
13− - `strictFunctionTypes: true`
14− - `strictBindCallApply: true`
15− - `strictPropertyInitialization: true`
16− - `noImplicitThis: true`
17− - `alwaysStrict: true`
18− - `exactOptionalPropertyTypes: true`
19−- Never use `// @ts-ignore` or `// @ts-expect-error` without explanatory comments
20−- Use `--noEmitOnError` compiler flag to prevent generating JS files when TypeScript errors exist
6+1. **Zero Duplication**: Always reuse or extend existing utilities instead of reimplementing
7+2. **Code Discovery First**: Search the codebase thoroughly before writing new functions
8+3. **Scope Discipline**: Edit only files required for the specific ticket
9+4. **Single Responsibility**: One purpose per function
10+5. **Atomic Commits**: One logical change per commit
2111
22−## Type Definitions
12+## What NOT to Do
2313
24−- Do not ever use `any`. Ever. If you feel like you have to use `any`, use `unknown` instead.
25−- Explicitly type function parameters, return types, and object literals.
26−- Please don't ever use Enums. Use a union if you feel tempted to use an Enum.
27−- Use `readonly` modifiers for immutable properties and arrays
28−- Leverage TypeScript's utility types (`Partial`, `Required`, `Pick`, `Omit`, `Record`, etc.)
29−- Use discriminated unions with exhaustiveness checking for type narrowing
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
3021
31−## Advanced Patterns
22+## Project Overview
3223
33−- Implement proper generics with appropriate constraints
34−- Use mapped types and conditional types to reduce type duplication
35−- Leverage `const` assertions for literal types
36−- Implement branded/nominal types for type-level validation
37−## Code Organization
24+Stock 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.
3825
39−- Organize types in dedicated files (types.ts) or alongside implementations
40−- Document complex types with JSDoc comments
41−- Create a central `types.ts` file or a `src/types` directory for shared types
26+## Tech Stack
4227
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)
39+npm run dev
40+
41+# Build for production (includes type checking)
42+npm run build
43+
44+# Run linting and type checking
45+npm run all
46+
47+# Database migrations
48+npm run db:migrate # Local D1 database
49+npm run db:migrate:prod # Production database
50+
51+# Background worker
52+npm run worker:dev # Run worker locally
53+npm run worker:deploy # Deploy to development
54+npm run worker:deploy:prod # Deploy to production
55+```
56+
57+## Architecture
58+
59+### Data Flow
60+1. User searches trigger data fetch from Yahoo Finance
61+2. Results cached in D1 database with scoring calculation
62+3. Background worker refreshes cached data every ~15 minutes during market hours
63+4. 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+
84+Key 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+
90+View: `option_data_with_scores` joins all data for display
91+
92+### Options Scoring Algorithm
93+
94+Multi-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+
101+All 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+
110+Astro 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+
115+Use 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
138+curl http://localhost:4321/api/stock-options?symbol=AAPL
139+
140+# Check worker execution
141+npm run worker:dev
142+# Then trigger manually via Wrangler dashboard
143+
144+# View D1 data
145+npx wrangler d1 execute options-tracker-local --local --command "SELECT * FROM symbol_tracking"
146+```
147+
148+## Environment Setup
149+
150+Required `.env` file:
151+```
152+PUBLIC_FINNHUB_API_KEY=your_key_here
153+```
154+
155+Local D1 database binding in `astro.config.mjs`:
156+- Database: `options-tracker-local`
157+- Auto-created on first run
158+
159+## Preferred Stocks
160+
161+Hardcoded list in `src/enums/preferredStocks.ts`:
162+TSLA, NET, LRCX, CRWD, NVDA, SE, KKR, BX, AAPL, GOOGL, META, AMD, AMZN, NFLX, MSFT
163+
164+These receive priority 10 in background refresh (vs priority 5 for user-searched).
165+
166+## Common Modifications
167+
168+### Add New Preferred Stock
169+1. Update `src/enums/preferredStocks.ts`
170+2. Symbol automatically added to tracking on next page load
171+
172+### Adjust Scoring Algorithm
173+1. Modify weights in `src/utils/optionScorer.ts`
174+2. Update thresholds in `src/enums/scoreThresholds.ts`
175+
176+### Change Refresh Frequency
177+1. Edit cron schedule in `wrangler.background.toml`
178+2. Adjust round-robin logic in `background_refresh.ts` if needed
179+
180+### Add New API Endpoint
181+1. Create new file in `src/pages/api/`
182+2. Export async GET/POST handler
183+3. Use database_service.ts for data access
184+
185+## Deployment Notes
186+
187+Production 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+
192+Monitor worker execution in Cloudflare dashboard under Workers > Logs.
