vf_react/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a hybrid React dashboard application with a Flask/Python backend for financial/trading analysis. Built on the Argon Dashboard Chakra PRO template with extensive customization.

Frontend (React + Chakra UI)

• Framework: React 18.3.1 with Chakra UI 2.8.2
• State Management: Redux Toolkit (@reduxjs/toolkit)
• Routing: React Router DOM v6 with lazy loading for code splitting
• Styling: Tailwind CSS + custom Chakra theme
• Build Tool: CRACO (Create React App Configuration Override) with custom webpack optimizations
• Charts: ApexCharts, ECharts, Recharts, D3
• UI Components: Ant Design (antd) alongside Chakra UI
• Other Libraries: Three.js (@react-three), FullCalendar, Leaflet maps

Backend (Flask/Python)

• Framework: Flask with SQLAlchemy ORM
• Database: ClickHouse for analytics queries + MySQL/PostgreSQL
• Real-time: Flask-SocketIO for WebSocket connections
• Task Queue: Celery with Redis for background processing
• External APIs: Tencent Cloud SMS, WeChat Pay integration

Development Commands

Frontend Development

npm start                    # Start with mock data (.env.mock), proxies to localhost:5001
npm run start:real           # Start with real backend (.env.local)
npm run start:dev            # Start with development config (.env.development)
npm run start:test           # Starts both backend (app_2.py) and frontend (.env.test) concurrently
npm run dev                  # Alias for 'npm start'
npm run backend              # Start Flask server only (python app_2.py)

npm run build                # Production build with Gulp license headers
npm run build:analyze        # Build with webpack bundle analyzer
npm test                     # Run React test suite with CRACO

npm run lint:check           # Check ESLint rules (exits 0)
npm run lint:fix             # Auto-fix ESLint issues
npm run clean                # Remove node_modules and package-lock.json
npm run reinstall            # Clean install (runs clean + install)

Backend Development

python app.py              # Main Flask server (newer version)
python app_2.py            # Flask server (appears to be current main)
python simulation_background_processor.py  # Background data processor for simulations

Deployment

npm run deploy               # Executes scripts/deploy-from-local.sh
npm run deploy:setup         # Setup deployment (scripts/setup-deployment.sh)
npm run rollback             # Rollback deployment (scripts/rollback-from-local.sh)

Python Dependencies

pip install -r requirements.txt

Architecture

Frontend Structure

• src/App.js - Main application entry with route definitions (routing moved from src/routes.js)
• src/layouts/ - Layout wrappers (Auth, Home, MainLayout)
• src/views/ - Page components (Community, Company, TradingSimulation, etc.)
• src/components/ - Reusable UI components
• src/contexts/ - React contexts (AuthContext, NotificationContext, IndustryContext)
• src/store/ - Redux store with slices (posthogSlice, etc.)
• src/services/ - API service layer
• src/theme/ - Chakra UI theme customization
• src/mocks/ - MSW (Mock Service Worker) handlers for development
  • src/mocks/handlers/ - Request handlers by domain
  • src/mocks/data/ - Mock data files
  • src/mocks/browser.js - MSW browser setup

Backend Structure

• app.py / app_2.py - Main Flask application with routes, authentication, and business logic
• simulation_background_processor.py - Background processor for trading simulations
• wechat_pay.py / wechat_pay_config.py - WeChat payment integration
• concept_api.py - API for concept/industry analysis
• tdays.csv - Trading days calendar data (loaded into memory at startup)

Key Integrations

• ClickHouse - High-performance analytics queries
• Celery + Redis - Background task processing
• Flask-SocketIO - Real-time data updates via WebSocket
• Tencent Cloud - SMS services
• WeChat Pay - Payment processing
• PostHog - Analytics (initialized in Redux)
• MSW - API mocking for development/testing

Routing & Code Splitting

• Routing is defined in src/App.js (not src/routes.js - that file is deprecated)
• Heavy components use React.lazy() for code splitting (Community, TradingSimulation, etc.)
• Protected routes use ProtectedRoute and ProtectedRouteRedirect components

Configuration

Environment Files

Multiple environment configurations available:

• .env.mock - Mock data mode (default for npm start)
• .env.local - Real backend connection
• .env.development - Development environment
• .env.test - Test environment

Build Configuration (craco.config.js)

• Webpack caching: Filesystem cache for faster rebuilds (50-80% improvement)
• Code splitting: Aggressive chunk splitting by library (react-vendor, charts-lib, chakra-ui, antd-lib, three-lib, etc.)
• Path aliases: @ → src/, @components → src/components/, @views → src/views/, @assets → src/assets/, @contexts → src/contexts/
• Optimizations: ESLint plugin removed from build for speed, Babel caching enabled, moment locale stripping
• Source maps: Disabled in production, eval-cheap-module-source-map in development
• Dev server proxy: /api requests proxy to http://49.232.185.254:5001

Important Build Notes

• Uses NODE_OPTIONS='--openssl-legacy-provider --max_old_space_size=4096' for Node compatibility
• Gulp task adds Creative Tim license headers post-build
• Bundle analyzer available via ANALYZE=true npm run build:analyze
• Pre-build: kills any process on port 3000

Testing

• React Testing Library for component tests
• MSW (Mock Service Worker) for API mocking during tests
• Run tests: npm test

Deployment

• Deployment scripts in scripts/ directory
• Build output processed by Gulp for licensing
• Supports rollback via scripts/rollback-from-local.sh