ljwx-stock/PROJECT_EXPLORATION_ANALYSIS.md

AI Stock Recommendation System - Comprehensive Architecture Analysis

1. PROJECT OVERVIEW

Project Type: Full-stack AI-powered stock recommendation system Tech Stack: FastAPI (Python) + Vue 3 (JavaScript) Current Status: Production-ready with Claude 4.5 integration Key Feature: Claude AI explains ML model predictions in natural language

---

2. DIRECTORY STRUCTURE

/root/work/stock/
├── backend/
│   ├── app/
│   │   ├── routes/              # API endpoints
│   │   │   ├── ai_assistant.py  # Chat + real data integration
│   │   │   ├── ai_recommendations.py  # AI-enhanced recommendations
│   │   │   ├── analysis.py      # Market analysis
│   │   │   ├── backtest.py      # Backtesting engine
│   │   │   ├── monitoring.py    # Performance monitoring
│   │   │   ├── recommendations.py  # Core recommendations
│   │   │   ├── sentiment_analysis.py  # Sentiment APIs
│   │   │   └── smart_cache.py   # Caching strategies
│   │   ├── modules/             # Business logic
│   │   │   ├── data_fetcher.py  # Multi-source data acquisition
│   │   │   ├── feature_engineer.py  # Technical indicators
│   │   │   ├── fundamental_data.py  # P/E, ROE, etc. from TuShare
│   │   │   ├── hot_stock_detector.py  # Trend detection
│   │   │   ├── sentiment_fetcher.py  # Market sentiment
│   │   │   ├── announcement_crawler.py  # News/announcements
│   │   │   ├── knowledge_base.py  # Stock knowledge DB
│   │   │   ├── llm_ranker.py    # LLM-based ranking
│   │   │   ├── ml_trainer.py    # Model training
│   │   │   ├── cache_manager.py # Redis caching
│   │   │   ├── cache_optimizer.py  # Cache optimization
│   │   │   ├── performance_monitor.py  # Metrics
│   │   │   ├── real_market_fetcher.py  # Real-time data
│   │   │   ├── smart_prewarmer.py  # Cache prewarming
│   │   │   ├── backtester.py    # Backtest engine
│   │   │   └── openbb_provider.py  # OpenBB integration
│   │   ├── crawler/
│   │   │   └── tushare_crawler.py  # TuShare API client
│   │   ├── models.py            # SQLAlchemy ORM
│   │   ├── database.py          # DB connection
│   │   ├── database_pg.py       # PostgreSQL setup
│   │   ├── config.py            # Settings management
│   │   └── __init__.py
│   ├── services/
│   │   ├── claude_service.py    # Claude AI integration (OpenRouter)
│   │   ├── enhanced_data_service.py  # Real market data service
│   │   └── (service instances)
│   ├── api/
│   │   └── ai_recommendations.py  # AI API layer
│   ├── main.py                  # FastAPI app entry
│   ├── requirements.txt         # Python dependencies
│   ├── Dockerfile
│   ├── test_*.py                # Test files
│   └── (logs directory)
│
├── frontend/
│   ├── src/
│   │   ├── views/
│   │   │   ├── Dashboard.vue    # Dashboard v1
│   │   │   ├── DashboardV2.vue  # Dashboard v2 (enhanced)
│   │   │   ├── Analysis.vue     # Analysis view
│   │   │   ├── Backtest.vue     # Backtest interface
│   │   │   └── Settings.vue     # Settings page
│   │   ├── components/
│   │   │   ├── AIAssistant.vue  # AI chat widget
│   │   │   ├── AIDock.vue       # AI dock bar
│   │   │   ├── HeroSection.vue  # Landing section v1
│   │   │   ├── HeroSectionEnhanced.vue  # Landing v2 with animations
│   │   │   ├── MarketPulse.vue  # Market metrics v1
│   │   │   ├── MarketPulseEnhanced.vue  # Market metrics v2
│   │   │   ├── StockCard.vue    # Stock card component
│   │   │   └── RecommendCard.vue  # Recommendation card
│   │   ├── services/
│   │   │   └── api.js           # API client (fetch wrapper)
│   │   ├── assets/
│   │   │   └── styles/          # SCSS stylesheets
│   │   ├── App.vue              # Root component
│   │   ├── main.js              # Entry point
│   │   ├── router.js            # Vue Router setup
│   │   └── store.js             # State management
│   ├── public/                  # Static assets
│   ├── dist/                    # Build output
│   ├── package.json
│   ├── vite.config.js           # Vite configuration
│   ├── Dockerfile
│   └── node_modules/            # Dependencies
│
├── docker-compose.yml          # Multi-container orchestration
├── .env                         # Environment variables
├── .env.example                 # Example environment
├── .gitignore
└── [Documentation files]

---

3. BACKEND ARCHITECTURE (FastAPI + Python)

3.1 Technology Stack

Web Framework:

• FastAPI 0.104.1 - Modern async web framework
• Uvicorn 0.24.0 - ASGI server

Data Layer:

• PostgreSQL 16 - Primary database
• Redis 7 - Caching layer
• TuShare API - Real-time Chinese stock data
• yfinance - Alternative data source
• BeautifulSoup4 - Web scraping

ML/AI:

• LightGBM - Gradient boosting models
• XGBoost - Ensemble predictions
• scikit-learn - ML utilities
• pandas, numpy, scipy - Data processing
• Anthropic SDK - Claude API (via OpenRouter)

Architecture Layers:

Frontend (Vue 3) 
        ↓ HTTP/WebSocket
FastAPI Routes (api_assistant.py, ai_recommendations.py, etc.)
        ↓
Service Layer (ClaudeStockAnalyzer, EnhancedDataService)
        ↓
Business Logic (Modules: data_fetcher, feature_engineer, fundamental_data)
        ↓
Data Sources (PostgreSQL, Redis, TuShare, Claude API)

3.2 API Endpoints

Recommendation APIs:

• POST /api/recommendations - Get ML model recommendations
• GET /api/recommendations/{symbol} - Get stock details
• GET /api/ai/recommendations/explained - Get AI-explained recommendations

AI Assistant APIs:

• POST /api/ai/chat - Chat with Claude AI assistant
• POST /api/ai/ask - Ask questions with market context
• GET /api/ai/market/overview - AI market analysis
• GET /api/ai/stock/{symbol}/explain - Explain recommendation

Analysis APIs:

• GET /api/analysis/sectors - Sector analysis
• GET /api/analysis/signals/{symbol} - Technical signals
• GET /api/analysis/market - Market analysis

Monitoring/Cache APIs:

• GET /api/monitoring/performance - System performance
• GET /api/smart-cache/status - Cache status
• GET /health - Health check

3.3 Data Models (SQLAlchemy ORM)

Key Models in /backend/app/models.py:

StockFundamentals
├── symbol, ts_code (identifiers)
├── pe_ttm, pb, roe, debt_ratio (metrics)
├── revenue, net_income, total_assets (financials)
├── industry_name, industry_pe_avg (industry data)
└── created_at, updated_at (timestamps)

MarketSentiment
├── symbol (stock identifier)
├── volume, turnover_ratio, daily_change_pct (trading data)
├── main_net_inflow, retail_net_inflow (fund flow)
└── sentiment indicators

(More models exist for announcements, recommendations, etc.)

3.4 Configuration Management

Config File: /backend/app/config.py

Key settings:

• DATABASE_URL - PostgreSQL connection string
• REDIS_URL - Redis connection
• OPENROUTER_API_KEY - Claude API key (via OpenRouter)
• TUSHARE_TOKEN - TuShare API token
• CORS_ORIGINS - Frontend CORS whitelist
• CACHE_TTL_* - Cache expiration times
• MODEL_* - ML model paths and settings

Environment variables are loaded from .env file.

3.5 Key Modules

data_fetcher.py:

• Multi-source data acquisition (TuShare → yfinance fallback)
• Caching with Redis
• Real-time quotes, historical data

feature_engineer.py:

• Technical indicators: MA, RSI, MACD, Bollinger Bands
• Momentum indicators: ROC, Stochastic
• Volume indicators: OBV, ADL
• Output: NumPy arrays for ML models

fundamental_data.py:

• Fetches from TuShare: P/E, P/B, ROE, revenue, profit
• Industry comparison
• Data interpretation (undervalued, overvalued, etc.)
• Cache with database

sentiment_fetcher.py:

• Market sentiment analysis
• Investor sentiment indices
• News sentiment aggregation
• Market breadth calculation

announcement_crawler.py:

• Crawls announcement platforms
• Extracts title, content, date
• Importance scoring
• Sentiment classification

ai_assistant.py Route:

• Real-time data fetching (TuShare)
• Sentiment analysis integration
• Announcement context
• Claude-powered responses with injected data

---

4. CLAUDE AI INTEGRATION

4.1 Current Implementation

File: /backend/services/claude_service.py

Model Used: anthropic/claude-sonnet-4.5 (via OpenRouter)

Key Architecture:

ClaudeStockAnalyzer
├── __init__()
│   ├── Load API key from OPENROUTER_API_KEY env var
│   └── Load system prompt from /backend/prompts/claude_stock_analysis.md
├── _call_openrouter()
│   └── HTTP POST to https://openrouter.ai/api/v1/chat/completions
├── analyze_market_overview()
│   └── Generate market analysis + sentiment + risks
├── analyze_recommendations()
│   └── Explain recommendation reasons (fundamental, technical, fund flow)
├── answer_user_question()
│   └── Contextual Q&A with market/stock data
├── compare_strategies()
│   └── Compare investment strategies
└── explain_ai_score()
    └── Explain ML model confidence

System Prompt:
- Fixed role: Senior AI investment analyst
- Prohibits data fabrication
- Focuses on interpretation, synthesis, reasoning
- Outputs structured JSON

Data Flow for AI Responses:

1. Backend collects real data:
   - Market context (sentiment, trends, fund flow)
   - Stock data (fundamentals, technicals, signals)
   - Recommendations from ML models

2. Data injected into prompt:
   - System: Fixed role + instructions
   - User: Real data + task (explain, analyze, compare)

3. Claude processes with constraints:
   - Cannot fabricate numbers
   - Must cite input data
   - Structures output as JSON

4. Response cached in Redis (TTL: 5 min)

5. Frontend receives natural language explanation

4.2 Integration Points

Routes Using Claude:

1. /api/ai/chat (ai_assistant.py)

   • Real-time data integration
   • Fetches fundamentals, sentiment, announcements
   • Claude returns contextual responses

2. /api/ai/ask (ai_recommendations.py)

   • Extracts stock symbols from questions
   • Detects industry/sector keywords
   • Retrieves relevant data
   • Claude answers with evidence

3. /api/ai/market/overview

   • Collects market context
   • Claude analyzes sentiment, hot sectors, risks

4. /api/ai/recommendations/explained

   • Gets ML recommendations
   • Claude explains why each stock is recommended

4.3 Prompt Engineering

System Prompt Pattern:

你是一名资深 AI 投资分析师...
- 禁止编造数据
- 专注解释、综合、推理
- 输出结构化 JSON

Data Injection Pattern:

user_prompt = f"""
请根据以下数据分析...

市场数据：
{json.dumps(market_context)}

推荐股票：
{json.dumps(recommendations)}

要求：
1. 从基本面、技术面、资金面分析
2. 说明适合的策略
3. 输出 JSON 格式
"""

---

5. FRONTEND ARCHITECTURE (Vue 3 + Vite)

5.1 Technology Stack

Framework:

• Vue 3.3.4 - Progressive framework
• Vite 5.0.2 - Build tool
• Vue Router 4.2.5 - Client-side routing
• Axios 1.6.2 - HTTP client

State Management:

• Pinia 2.1.6 - State management (modern alternative to Vuex)
• Vuex 4.1.0 - Legacy state management

UI/Visualization:

• ECharts 5.4.3 - Data visualization
• SASS 1.69.5 - CSS preprocessor

Build & Dev:

• ESLint - Code linting
• Vite plugins - Hot module reload

5.2 API Integration

File: /frontend/src/services/api.js

Core API client using fetch API:

// Configuration
const API_BASE_URL = import.meta.env.VITE_API_URL || '/api'

// Core functions
fetchRecommendations()
fetchStockDetail(symbol)
fetchSectorAnalysis()
fetchSignals(symbol)
fetchMarketAnalysis()
runBacktest(params)

// AI Enhanced APIs
fetchAIMarketOverview()
fetchAIRecommendations(limit)
askAI(question, symbol)

Environment Variables:

• VITE_API_URL - Backend API URL (set in docker-compose.yml)
• VITE_WS_URL - WebSocket URL (optional)

5.3 Page Views

Dashboard Views:

1. DashboardV2.vue (Current Enhanced Version)

   • HeroSectionEnhanced: Header with animations + market overview
   • MarketPulseEnhanced: Market metrics dashboard
   • Stock recommendations list
   • AIDock: AI chat widget
   • Real-time data updates

2. Analysis.vue

   • Sector analysis
   • Technical signals
   • Market trends
   • Interactive charts (ECharts)

3. Backtest.vue

   • Strategy definition
   • Parameter configuration
   • Results visualization
   • Performance metrics

4. Settings.vue

   • User preferences
   • Display settings
   • Cache management

5.4 Key Components

AIAssistant.vue:

• Chat interface with Claude
• Message history
• Suggestion buttons
• Real-time responses
• Collapsible design

MarketPulseEnhanced.vue:

• Market metrics dashboard
• Sentiment indicators
• Trend charts
• Fund flow visualization

StockCard.vue:

• Individual stock display
• AI score visualization
• Technical signals
• Fundamental metrics
• Click-through to details

HeroSectionEnhanced.vue:

• Landing section with animations
• Market sentiment display
• Quick stats
• Call-to-action

---

6. DATA SOURCES & INTEGRATIONS

6.1 Real-Time Data Sources

TuShare API (Primary for Chinese A-stocks)

• Real-time quotes
• Historical OHLCV data
• Fundamental data (P/E, P/B, ROE)
• Industry benchmarks
• Market sentiment
• Announcements

yfinance (Fallback for global markets)

• Historical price data
• Volume data
• Dividend information

OpenRouter API (Claude AI via proxy)

• Claude Sonnet 4.5 model
• Chat completions endpoint
• Cost-optimized pricing

PostgreSQL (Historical & Processed Data)

• Stock fundamentals cache
• Market sentiment snapshots
• Announcement history
• User data

Redis (High-Speed Cache)

• Real quotes (TTL: 60s)
• Technical features (TTL: 5 min)
• ML predictions (TTL: 5 min)
• Claude responses (TTL: 5 min)
• Session data

6.2 Data Pipeline

Raw Data Sources (TuShare, yfinance)
        ↓
Data Fetcher Module (validate, clean)
        ↓
Feature Engineering (calculate indicators)
        ↓
Redis Cache (with TTLs)
        ↓
PostgreSQL (historical snapshots)
        ↓
ML Model Input (predictions)
        ↓
Claude Context (data injection)
        ↓
Frontend Rendering (DashboardV2)

---

7. DOCKER & DEPLOYMENT

7.1 Container Architecture

docker-compose.yml Defines:

1. PostgreSQL Container (postgres:16-alpine)

   • Port: 5433 → 5432 (container)
   • Database: stock_ai
   • User: stockai
   • Volume: postgres_data (persistent)
   • Healthcheck: pg_isready

2. Redis Container (redis:7-alpine)

   • Port: 6380 → 6379 (container)
   • Password: redis2025
   • AOF persistence enabled
   • Volume: redis_data (persistent)
   • Healthcheck: redis-cli ping

3. Backend Container (FastAPI)

   • Build: ./backend/Dockerfile
   • Port: 8001 → 8000 (container)
   • Depends on: PostgreSQL, Redis
   • Env vars: Database URL, Redis URL, API keys
   • Healthcheck: curl /health
   • Volumes: ./backend/logs

4. Frontend Container (Vue 3)

   • Build: ./frontend/Dockerfile
   • Port: 8090 → 80 (Nginx)
   • Depends on: Backend
   • Env var: VITE_API_URL (backend endpoint)

5. Adminer Container (Database UI)

   • Port: 8091 → 8080
   • Useful for development/debugging

7.2 Environment Configuration

docker-compose.yml Sets:

OPENROUTER_API_KEY: [sk-or-v1-...]  # Claude API key
OPENROUTER_BASE_URL: https://openrouter.ai/api/v1
TUSHARE_TOKEN: [token]              # Chinese stock data
DATABASE_URL: postgresql://stockai:stockai2025@postgres:5432/stock_ai
REDIS_URL: redis://:redis2025@redis:6379/0
ENVIRONMENT: production
LOG_LEVEL: info
VITE_API_URL: http://85.239.237.116:8001  # Frontend → Backend URL

7.3 Dockerfile Strategies

Backend (Python 3.11-slim):

• Multi-stage build (potential)
• System deps: gcc, g++, libpq-dev, curl
• Python deps installed via pip
• Healthcheck: requests.get('/health')
• 4 Uvicorn workers

Frontend (Node + Nginx):

• Build stage: npm install + npm run build
• Runtime: Nginx serving static files
• Nginx config for SPA routing
• Environment variable injection at build time

---

8. EXISTING CLAUDE/MODEL INTEGRATION CODE

8.1 Claude Service (Current)

File: /backend/services/claude_service.py (388 lines)

Key Methods:

1. async _call_openrouter() - HTTP client for OpenRouter API
2. async analyze_market_overview() - Market sentiment analysis
3. async analyze_recommendations() - Explain stock recommendations
4. async answer_user_question() - Contextual Q&A
5. async compare_strategies() - Strategy comparison
6. async explain_ai_score() - Model explanation

Usage Pattern:

analyzer = ClaudeStockAnalyzer()
response = await analyzer.analyze_recommendations(
    market_data=market_context,
    recommendations=stock_list
)

8.2 AI Routes (Current)

Files:

• /backend/app/routes/ai_assistant.py (544 lines)
• /backend/app/routes/ai_recommendations.py (117 lines)
• /backend/api/ai_recommendations.py (332 lines)

Current Features:

• Real-time data fetching (TuShare fundamentals, sentiment, announcements)
• Contextual responses based on user queries
• Industry/sector detection from questions
• Stock symbol extraction from questions
• Market breadth and sentiment analysis
• PE, ROE, growth rate explanations

8.3 Enhanced Data Service (Current)

File: /backend/services/enhanced_data_service.py (100+ lines)

Purpose:

• Aggregates market context from TuShare
• Calculates market sentiment
• Identifies sector trends
• Estimates fund flows
• Provides fallback data

---

9. ARCHITECTURE PATTERNS

9.1 Service Layer Pattern

All data access goes through services:

• ClaudeStockAnalyzer - AI/LLM operations
• EnhancedDataService - Market data aggregation
• DataFetcher - Multi-source data acquisition
• FeatureEngineer - Technical indicators
• FundamentalDataFetcher - Financial metrics

9.2 Caching Strategy

Multi-level caching:

Redis Cache (fast, TTL-based)
    ↓
PostgreSQL (persistent, historical)
    ↓
External APIs (TuShare, OpenRouter) - fallback

TTLs configured by data type:

• Quotes: 60 seconds
• Technical features: 300 seconds (5 min)
• Recommendations: 300 seconds
• Claude responses: 3600 seconds (1 hour)

9.3 Dependency Injection

FastAPI uses Depends() for:

• Database sessions
• Cache managers
• Service instances
• Configuration objects

Example:

@router.get("/recommendations/explained")
async def get_recommendations(
    claude: ClaudeStockAnalyzer = Depends(get_claude_analyzer),
    data_service: EnhancedDataService = Depends(get_enhanced_data_service)
):
    ...

9.4 Error Handling

• Try-catch blocks with logging
• Graceful fallbacks to mock data
• Health checks for all services
• HTTP exception with meaningful status codes

---

10. CURRENT LIMITATIONS & GAPS

1. Stock Code Extraction: Only basic regex in ai_recommendations.py
2. Industry Detection: Simple keyword matching in detect_industry()
3. Data Service Integration: Some TODOs in ai_recommendations.py for real DB lookups
4. Recommendation Endpoints: Some endpoints return mock data (see TODOs)
5. Claude Error Handling: Limited retry logic for API failures
6. WebSocket Support: Defined in frontend but not fully implemented

---

11. KEY FILES SUMMARY

File	Purpose	Lines	Key Class/Function
backend/main.py	FastAPI app entry	180	app (FastAPI instance)
backend/services/claude_service.py	Claude AI integration	388	ClaudeStockAnalyzer
backend/services/enhanced_data_service.py	Market data service	150+	EnhancedDataService
backend/app/routes/ai_assistant.py	Chat API	544	router, chat(), analyze_stock()
backend/app/routes/ai_recommendations.py	AI recommend API	117	router, get_explained_recommendations()
backend/app/config.py	Configuration	100	Settings (Pydantic)
backend/app/models.py	ORM Models	150+	StockFundamentals, MarketSentiment
frontend/src/services/api.js	API client	140	fetchAIRecommendations(), askAI()
frontend/src/components/AIAssistant.vue	Chat widget	200+	AIAssistant component
frontend/src/views/DashboardV2.vue	Main dashboard	300+	DashboardV2 component
docker-compose.yml	Deployment config	142	5 services (postgres, redis, backend, frontend, adminer)

---

12. RECOMMENDED NEXT STEPS

For Claude × DeepSeek system architecture integration:

1. Create unified AI orchestrator service that:

   • Routes simple queries to DeepSeek (faster, cheaper)
   • Routes complex analysis to Claude (higher reasoning)
   • Implements fallback logic

2. Extend prompt templates for:

   • DeepSeek-specific formatting
   • Multi-model response merging
   • Quality grading of responses

3. Add model selection logic based on:

   • Query complexity scoring
   • Response time requirements
   • Cost optimization targets
   • Confidence level thresholds

4. Implement response caching for:

   • Exact question matches
   • Semantic similarity matching
   • Cost attribution per model

5. Add monitoring/metrics for:

   • Model performance comparison
   • Cost per query type
   • Latency by model
   • Quality ratings by users