Fincast Development Instructions
This skill provides comprehensive development guidance for working with the Fincast codebase - a financial analysis platform built with Next.js 14, Python FastAPI, and Claude AI integration.
Technology Stack
**Frontend**: Next.js 14 with App Router, React 18, TypeScript**Styling**: Tailwind CSS with shadcn/ui components (Radix UI primitives)**Backend**: Hybrid Next.js API routes + Python FastAPI**Data Sources**: Yahoo Finance via `yfinance` (Python) and `yahoo-finance2` (Node.js)**AI Integration**: Claude AI (Anthropic) for financial analysis and projections**Deployment**: Vercel with serverless functionsDevelopment Commands
When working with this codebase, use these commands:
Next.js Application
```bash
npm run dev # Start development server on http://localhost:3000
npm run build # Build production application
npm run start # Start production server
npm run lint # Run ESLint for code quality checks
```
Python API Services
```bash
npm run py:serve # Start local Python FastAPI server (requires virtual environment)
npm run py:tunnel # Start localtunnel for Python API (development tunneling)
```
Manual Python Setup
```bash
source venv/bin/activate
uvicorn python_api:app --host 127.0.0.1 --port 8000
```
Architecture Overview
Financial Data Pipeline
The application uses a hybrid approach for fetching financial data:
1. **Primary Source**: Python services (`api/py-yf/index.py` and `scripts/fetch_yfinance.py`) fetch data from Yahoo Finance
2. **Fallback Source**: Node.js service (`app/api/yfinance-data/route.js`) provides backup when Python service fails
3. **Currency Conversion**: Automatic conversion to USD for international stocks
4. **Bank Detection**: Special handling for financial institutions with different valuation methods
Key API Endpoints
**DCF Valuation**: `/api/dcf-valuation` - Main valuation endpoint with Claude AI integration**Portfolio Management**: `/api/portfolio*` - Portfolio CRUD operations**Financial Data**: `/api/yfinance-data` - Yahoo Finance data proxy**Company Data**: `/api/company-data` - Company profile and metricsFrontend Structure
**App Router**: Next.js 14 app directory structure in `/app`**Components**: Mix of `.js` and `.tsx` files in `app/components/`**UI Library**: shadcn/ui components in `components/ui/`**State Management**: React state with context providersFile Organization
`/app` - Next.js app router pages and API routes`/components` - Reusable UI components (shadcn/ui)`/scripts` - Python utilities for financial data`/api` - Vercel serverless functions (Python)`/lib` - Utility functions and configurationsEnvironment Configuration
Required environment variables (see `env.example`):
`ANTHROPIC_API_KEY` - Claude AI API key for financial analysis`DATABASE_URL` - PostgreSQL connection (planned)`NEXTAUTH_*` - Authentication configuration (planned)`GOOGLE_CLIENT_*` - OAuth configuration (planned)Python Environment
The Python services require a virtual environment with:
`yfinance` - Yahoo Finance data fetching`pandas` - Data manipulation`numpy` - Numerical operations`requests` - HTTP requestsFastAPI server for financial data endpointsVirtual environment location: `venv/` directory
Deployment Configuration
Vercel Settings
Next.js framework detection enabledPython serverless functions in `api/py-yf/`Extended timeout (60s) for financial API callsMemory allocation (1024MB) for Python functionsData Flow
1. Frontend requests financial data
2. Next.js API routes coordinate between services
3. Python services fetch from Yahoo Finance
4. Claude AI analyzes and projects financial data
5. Results formatted and returned to frontend
Special Considerations
Financial Data Handling
Automatic detection of bank stocks for specialized valuationCurrency conversion for international equitiesHistorical data fetching with 5-year price seriesError handling with fallback to secondary data sourcesPerformance Optimizations
Caching strategies for financial dataBackground data fetchingServerless function optimization for financial calculationsTesting
Manual testing scripts in root directory (`test_*.js`, `test_*.py`)No formal test framework currently configuredTest scripts validate Python API integration and data fetchingPath Configuration
TypeScript path alias `@/*` maps to project rootESLint configured for code qualityWhen Making Changes
1. **API Routes**: Consider both Next.js and Python service impacts
2. **Financial Data**: Test with both US and international stocks
3. **Currency Handling**: Verify USD conversion logic
4. **Bank Stocks**: Ensure specialized valuation logic is maintained
5. **Error Handling**: Implement fallback strategies for data fetching
6. **Performance**: Consider serverless function timeout and memory constraints