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

Hybrid React dashboard for financial/trading analysis with Flask backend. Built on Argon Dashboard Chakra PRO template.

### Tech Stack

**Frontend**
- React 18.3.1 + Chakra UI 2.8.2 + Ant Design
- Redux Toolkit for state management
- React Router v6 with React.lazy() code splitting
- CRACO build system with aggressive webpack optimization
- Charts: ApexCharts, ECharts, Recharts, D3
- Additional: Three.js, FullCalendar, Leaflet maps

**Backend**
- Flask + SQLAlchemy ORM
- ClickHouse (analytics) + MySQL/PostgreSQL (transactional)
- Flask-SocketIO for WebSocket real-time updates
- Celery + Redis for background jobs
- 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
python simulation_background_processor.py  # Background task processor for trading simulations
pip install -r requirements.txt            # Install Python dependencies
```

### Deployment
```bash
npm run deploy        # Deploy from local (scripts/deploy-from-local.sh)
npm run rollback      # Rollback to previous version
```

## Architecture

### Application Entry Flow
```
src/index.js
└── src/App.js (root component)
    ├── AppProviders (src/providers/AppProviders.js)
    │   ├── ReduxProvider (store from src/store/)
    │   ├── ChakraProvider (theme from src/theme/)
    │   ├── NotificationProvider (src/contexts/NotificationContext.js)
    │   └── AuthProvider (src/contexts/AuthContext.js)
    ├── AppRoutes (src/routes/index.js)
    │   ├── MainLayout routes (with navbar/footer)
    │   └── Standalone routes (auth pages, fullscreen views)
    └── GlobalComponents (modal overlays, global UI)
```

### Routing Architecture (Modular Design)
Routing is **declarative** and split across multiple files in `src/routes/`:

- **index.js** - Main router (combines config + renders routes)
- **routeConfig.js** - Route definitions (path, component, protection, layout, children)
- **lazy-components.js** - React.lazy() imports for code splitting
- **homeRoutes.js** - Nested home page routes
- **constants/** - Protection modes, layout mappings
- **utils/** - Route rendering logic (wrapWithProtection, renderRoute)

Route protection modes (PROTECTION_MODES):
- `PUBLIC` - No authentication required
- `MODAL` - Shows auth modal if not logged in
- `REDIRECT` - Redirects to /auth/sign-in if not logged in

### Frontend Directory Structure
```
src/
├── App.js              - Root component (providers + routing)
├── providers/          - Provider composition (AppProviders.js)
├── routes/             - Modular routing system (see above)
├── layouts/            - Page layouts (MainLayout, Auth)
├── views/              - Page components (Community, TradingSimulation, etc.)
├── components/         - Reusable UI components
├── contexts/           - React contexts (Auth, Notification, Sidebar)
├── store/              - Redux store + slices (auth, posthog, stock, industry, etc.)
├── services/           - API layer (axios wrappers)
├── utils/              - Utility functions (apiConfig, priceFormatters, logger)
├── constants/          - App constants (animations, etc.)
├── hooks/              - Custom React hooks
├── theme/              - Chakra UI theme customization
└── mocks/              - MSW handlers for development
    ├── handlers/       - Request handlers by domain (auth, stock, company, etc.)
    ├── data/           - Mock data files
    └── browser.js      - MSW setup (starts when REACT_APP_ENABLE_MOCK=true)
```

### Backend Structure
```
app.py                               - Flask server (routes, auth, business logic)
simulation_background_processor.py   - Celery worker for trading simulations
concept_api.py                       - Concept/industry analysis API
wechat_pay.py / wechat_pay_config.py - WeChat payment integration
tdays.csv                            - Trading days calendar (loaded at startup)
requirements.txt                     - Python dependencies
```

### State Management Strategy
- **Redux Toolkit**: Global state (auth modal, posthog, stock data, industry data, subscriptions, community data)
- **React Context**: Cross-cutting concerns (AuthContext, NotificationContext, SidebarContext)
- **Component State**: Local UI state (forms, toggles, etc.)

### Real-time Updates
- Flask-SocketIO for WebSocket connections
- Example: Community event notifications push via WebSocket
- Client: `socket.io-client` library

## Configuration

### Environment Files
```
.env.mock        - Mock mode (default): MSW intercepts all API calls, no backend needed
.env.development - Dev mode: Connects to dev backend
.env.test        - Test mode: Used by 'npm run start:test' (backend + frontend together)
.env.production  - Production build config
```

**Key environment variables:**
- `REACT_APP_ENABLE_MOCK=true` - Enable MSW mocking
- `REACT_APP_API_URL` - Backend URL (empty string = use relative paths or MSW)

### MSW (Mock Service Worker) Setup
MSW is used for API mocking during development:

1. **Activation**: Set `REACT_APP_ENABLE_MOCK=true` in env file
2. **Worker file**: `public/mockServiceWorker.js` (auto-generated)
3. **Handlers**: `src/mocks/handlers/` (organized by domain: auth, stock, company, etc.)
4. **Mode**: `onUnhandledRequest: 'warn'` - unhandled requests pass through to backend

When MSW is active, the dev server proxy is disabled (MSW intercepts first).

### Path Aliases (craco.config.js)
All aliases resolve to `src/` subdirectories:
```
@/           → src/
@components/ → src/components/
@views/      → src/views/
@assets/     → src/assets/
@contexts/   → src/contexts/
@layouts/    → src/layouts/
@services/   → src/services/
@store/      → src/store/
@utils/      → src/utils/
@hooks/      → src/hooks/
@theme/      → src/theme/
@mocks/      → src/mocks/
@constants/  → src/constants/
```

### Webpack Optimizations (craco.config.js)
**Performance features:**
- Filesystem cache (50-80% rebuild speedup)
- Aggressive code splitting by library:
  - `react-vendor` - React core (priority 30)
  - `charts-lib` - echarts, d3, apexcharts, recharts (priority 25)
  - `chakra-ui` - Chakra UI + Emotion (priority 23)
  - `antd-lib` - Ant Design (priority 22)
  - `three-lib` - Three.js (priority 20)
  - `calendar-lib` - moment, date-fns, FullCalendar (priority 18)
- ESLint plugin removed from build (20-30% speedup)
- Babel caching enabled
- moment locale stripping (IgnorePlugin)
- Source maps: disabled in production, `eval-cheap-module-source-map` in dev

**Dev server:**
- Port 3000 (kills existing process on prestart)
- Proxy (when MSW disabled): `/api` → `http://49.232.185.254:5001`
- Bundle analyzer: `ANALYZE=true npm run build:analyze`

### Build Process
1. `npm run build` compiles with CRACO + webpack optimizations
2. Gulp task (`gulp licenses`) adds Creative Tim license headers to JS/HTML
3. Output: `build/` directory

**Node compatibility:**
```bash
NODE_OPTIONS='--openssl-legacy-provider --max_old_space_size=4096'
```

## Development Workflow

### Working with Routes
To add a new route:

1. Add lazy import in `src/routes/lazy-components.js`
2. Add route config in `src/routes/routeConfig.js` with:
   - `path` - URL path
   - `component` - From lazyComponents
   - `protection` - MODAL/REDIRECT/PUBLIC
   - `layout` - 'main' (with nav) or 'none' (fullscreen)
3. Routes automatically render with Suspense + ErrorBoundary (handled by PageTransitionWrapper)

### Component Organization Patterns
Based on recent refactoring (see README.md for details):

**Atomic Design Pattern:**
- **Atoms** - Basic UI elements (buttons, badges, inputs)
- **Molecules** - Combinations of atoms (cards, forms)
- **Organisms** - Complex components (lists, panels)

**Example structure for large components (1000+ lines):**
```
src/views/Community/components/
├── EventCard/
│   ├── index.js                  - Smart wrapper (routes compact vs detailed)
│   ├── CompactEventCard.js       - Compact view
│   ├── DetailedEventCard.js      - Detailed view
│   ├── EventTimeline.js          - Atomic component
│   ├── EventImportanceBadge.js   - Atomic component
│   └── ...
```

**Utility extraction:**
- Extract reusable logic to `src/utils/` (e.g., `priceFormatters.js`)
- Extract shared constants to `src/constants/` (e.g., `animations.js`)

### API Integration
**Service layer** (`src/services/`):
- Use `getApiBase()` from `src/utils/apiConfig.js` for base URL
- Example: `${getApiBase()}/api/endpoint`
- In mock mode, MSW intercepts; in dev/prod, hits backend

**Adding new API endpoints:**
1. Add service function in `src/services/` (or inline in component)
2. If using MSW: Add handler in `src/mocks/handlers/{domain}.js`
3. Import handler in `src/mocks/handlers/index.js`

### Redux State Management
**Existing slices** (`src/store/slices/`):
- `authModalSlice` - Auth modal state
- `posthogSlice` - PostHog analytics
- `stockSlice` - Stock data
- `industrySlice` - Industry/concept data
- `subscriptionSlice` - User subscriptions
- `communityDataSlice` - Community content

**Adding new slice:**
1. Create `src/store/slices/yourSlice.js`
2. Import and add to `src/store/index.js`
3. Access via `useSelector`, dispatch via `useDispatch`

## Backend Architecture

### Flask Application (app.py)
- **Authentication**: Flask-Login + session management
- **Database**: SQLAlchemy models + ClickHouse client
- **Background jobs**: Celery tasks for async processing
- **Real-time**: Flask-SocketIO for WebSocket events
- **Trading days**: `tdays.csv` loaded into memory at startup (global `trading_days` variable)

### Key Backend Patterns
- **ClickHouse**: Used for high-volume analytics queries (stock data, time series)
- **MySQL/PostgreSQL**: Used for transactional data (users, orders, subscriptions)
- **Celery**: Background processor runs in separate process (`simulation_background_processor.py`)
- **CORS**: Enabled for frontend communication

### API Proxy Configuration
When not in mock mode, frontend proxies to backend:
- `/api` → `http://49.232.185.254:5001` (main API)
- `/concept-api` → `http://49.232.185.254:6801` (concept analysis API)

## Important Notes

### Code Splitting Strategy
Heavy pages are lazy-loaded to reduce initial bundle size:
- Community, TradingSimulation, Company pages use `React.lazy()`
- Webpack splits large libraries into separate chunks
- Check bundle size with `npm run build:analyze`

### Error Boundaries
- **Layout-level**: Each layout (MainLayout, Auth) has its own ErrorBoundary
- **Page-level**: PageTransitionWrapper wraps each route with ErrorBoundary
- **Strategy**: Errors are isolated to prevent entire app crashes

### PostHog Analytics
- Initialized in Redux (`posthogSlice`)
- Configured during app startup in `App.js`
- Used for user behavior tracking

### Performance Considerations
- **Large components**: If component exceeds ~500 lines, consider refactoring (see README.md)
- **Re-renders**: Use `React.memo`, `useMemo`, `useCallback` for expensive operations
- **Bundle size**: Monitor with webpack-bundle-analyzer
- **Caching**: Webpack filesystem cache speeds up rebuilds significantly