update

readme.plan.md

@@ -3,7 +3,7 @@
 Command to reread guidelines: Read /home/philkunz/.claude/CLAUDE.md
 
 ## Overview
-Implementation of a stocks module for fetching current stock prices using various APIs, starting with Yahoo Finance API.
+Implementation of a stocks module for fetching current stock prices using various APIs. The architecture will support multiple providers, but we'll start with implementing only Yahoo Finance API. The design will make it easy to add additional providers (Alpha Vantage, IEX Cloud, etc.) in the future without changing the core architecture.
 
 ## Phase 1: Yahoo Finance Implementation
 
@@ -23,9 +23,10 @@ ts/
     ├── classes.stockservice.ts # Main StockPriceService class
     ├── interfaces/
     │   ├── stockprice.ts      # IStockPrice interface
-    │   └── provider.ts        # IStockProvider interface
+    │   └── provider.ts        # IStockProvider interface (for all providers)
     └── providers/
-        └── provider.yahoo.ts   # Yahoo Finance implementation
+        ├── provider.yahoo.ts   # Yahoo Finance implementation
+        └── (future: provider.alphavantage.ts, provider.iex.ts, etc.)
 ```
 
 ### 1.3 Core Interfaces
@@ -58,18 +59,23 @@ interface IStockProvider {
 - [ ] Add request throttling/rate limiting
 
 ### 1.5 Main Service Class
-- [ ] Create StockPriceService class
-- [ ] Integrate Yahoo provider
+- [ ] Create StockPriceService class with provider registry
+- [ ] Implement provider interface for pluggable providers
+- [ ] Register Yahoo provider (with ability to add more later)
 - [ ] Add method for single ticker lookup
 - [ ] Add method for batch ticker lookup
 - [ ] Implement error handling with graceful degradation
+- [ ] Design fallback mechanism (ready for multiple providers)
 
 ## Phase 2: Core Features
 
-### 2.1 Service Architecture
-- [ ] Create extensible provider architecture
-- [ ] Design provider interface for future additions
-- [ ] Implement provider registration system
+### 2.1 Service Architecture  
+- [ ] Create provider registry pattern for managing multiple providers
+- [ ] Implement provider priority and selection logic
+- [ ] Design provider health check interface
+- [ ] Create provider configuration system
+- [ ] Implement provider discovery mechanism
+- [ ] Add provider capability querying (which tickers/markets supported)
 
 ## Phase 3: Advanced Features
 
@@ -80,10 +86,10 @@ interface IStockProvider {
 - [ ] Make cache configurable per ticker
 
 ### 3.2 Configuration
-- [ ] Environment variable support for API keys
-- [ ] Provider configuration (enabled/disabled, priority)
+- [ ] Provider configuration (timeout, retry settings)
 - [ ] Cache configuration (TTL, max entries)
 - [ ] Request timeout configuration
+- [ ] Error handling configuration
 
 ### 3.3 Error Handling
 - [ ] Define custom error types
@@ -118,10 +124,10 @@ interface IStockProvider {
    - Create core interfaces
    - Basic error handling
 
-2. **Week 2: Additional Providers**
-   - Implement Alpha Vantage provider
-   - Implement IEX Cloud provider
-   - Add provider fallback logic
+2. **Week 2: Service Architecture**
+   - Create extensible provider system
+   - Implement provider interface
+   - Add provider registration
 
 3. **Week 3: Advanced Features**
    - Implement caching system
@@ -151,33 +157,37 @@ interface IStockProvider {
 - No authentication required
 - Returns JSON with price data
 - Rate limits unknown (need to test)
-
-### Alpha Vantage
-- Base URL: `https://www.alphavantage.co/query`
-- Requires API key (free tier available)
-- 5 requests per minute, 500 requests per day (free)
-- Good documentation
-
-### IEX Cloud
-- Base URL: `https://cloud.iexapis.com/stable`
-- Requires authentication token
-- Free tier: 50,000 messages/month
-- Sandbox environment available
+- Alternative endpoints to explore:
+  - `/v7/finance/quote` - Simplified quote data
+  - `/v10/finance/quoteSummary` - Detailed company data
 
 ## Success Criteria
 
 1. Can fetch current stock prices for any valid ticker
-2. Graceful fallback between providers
+2. Extensible architecture for future providers
 3. Response time < 1 second for cached data
 4. Response time < 3 seconds for fresh data
-5. 99% uptime with at least one provider
+5. Proper error handling and recovery
 6. Comprehensive test coverage (>80%)
 
 ## Notes
 
-- Start with Yahoo Finance as it requires no authentication
+- Yahoo Finance provides free stock data without authentication
+- **Architecture designed for multiple providers**: While only implementing Yahoo Finance initially, all interfaces, classes, and patterns are designed to support multiple stock data providers
+- The provider registry pattern allows adding new providers without modifying existing code
+- Each provider implements the same IStockProvider interface for consistency
+- Future providers can be added by simply creating a new provider class and registering it
 - Implement proper TypeScript types for all data structures
 - Follow the project's coding standards (prefix interfaces with 'I')
 - Use plugins.ts for all external dependencies
 - Keep filenames lowercase
-- Write tests using @git.zone/tstest with smartexpect syntax
+- Write tests using @git.zone/tstest with smartexpect syntax
+- Focus on clean, extensible architecture for future growth
+
+## Future Provider Addition Example
+
+When ready to add a new provider (e.g., Alpha Vantage), the process will be:
+1. Create `ts/stocks/providers/provider.alphavantage.ts`
+2. Implement the `IStockProvider` interface
+3. Register the provider in the StockPriceService
+4. No changes needed to existing code or interfaces