# 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
```bash
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
```bash
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
```bash
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
```bash
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