# CLAUDE.md

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

## Development Commands

The main application is located in the `front/` directory. All commands should be run from this directory:

```bash
cd front
```

### Core Commands
- `npm run dev` - Start development server
- `npm run build` - Production build with TypeScript compilation
- `npm run build:stg` - Staging environment build
- `npm run build:prod` - Production environment build  
- `npm run lint` - Run ESLint with TypeScript support
- `npm run preview` - Preview production build
- `npm run generate` - Generate GraphQL types

## Project Architecture

This is a React TypeScript application following Feature-Sliced Design (FSD) architecture patterns with Zustand for state management.

### Directory Structure

- **`src/api/`** - API layer with service modules for external communication
- **`src/entities/`** - Domain entities with global state management (Zustand stores)
- **`src/features/`** - Business features with hooks and UI components
- **`src/layouts/`** - Application layouts (BasicLayout, AuthLayout, AlimTalkLayout)
- **`src/pages/`** - Route pages organized by domain
- **`src/shared/`** - Shared utilities, components, and helpers
- **`src/widget/`** - Reusable composite components

### State Management

The application uses Zustand for state management with domain-specific stores in `entities/*/model/store.ts`:
- Global app state (`_global`)
- User authentication (`user`)
- Analysis data (`analysis`)
- Payment subscriptions (`subscribe`)
- Board/notifications (`board`, `alarm`)
- And other domain-specific stores

### Key Technologies

- **React 18** with TypeScript
- **Vite** for bundling and development
- **React Router v6** for navigation
- **Zustand** for state management
- **React Hook Form** for form handling
- **PDF generation** with pdf-lib and pdfmake
- **Payment integration** with TossPayments
- **Chart visualization** with Nivo

### Code Conventions

From the README.md:
- Folder names: lowerCamelCase
- Components: UpperCamelCase  
- Page components: suffix with "Page" (e.g., `LoginPage.tsx`)

### Branch and Commit Conventions

**Commit format**: `{type}: description`

Types: feat, fix, docs, refactor, test, perf, style, build, ci, WIP, chore

**Branch prefixes**: feature/, enhancement/, refactor/, chore/, update/, bugfix/, hotfix/, release/, test/, docs/, experiment/

## Important Notes

- This is an insurance analysis platform ("보험유니버스") with user subscription management
- The app includes mobile bridge functionality for native app integration
- Multi-environment support (development, staging, production)
- Korean language support with moment.js localization
- PDF generation capabilities for analysis reports
- Payment processing integration
- Educational content with video streaming capabilities

## Common Issues and Solutions

### Modal Navigation Issues
- **Problem**: `/main` redirect when navigating from modals
- **Cause**: Modal callbacks executing after navigation, AuthGuard re-evaluation
- **Solution**: Always close modal before navigation with proper delay
- **Files**: `src/features/subscribe/hooks/useCheckSubscription.ts`, `src/features/products/hooks/useProducts.tsx`

### Advertisement Loading Race Conditions
- **Problem**: Advertisement logic executing before API data is fetched
- **Cause**: useEffect running on initial render with undefined data
- **Solution**: Always check `isAdFetched` before processing advertisement logic
- **Pattern**: Combine related useEffects to avoid duplicate logic
- **Files**: `src/features/analyze/ui/AnalyzeAd.tsx`, `src/features/alimtalk/ui/AlimtalkAd.tsx`

### Code Review Checklist
When reviewing code changes, always check for:
1. **useEffect dependencies**: Ensure all necessary dependencies are included
2. **Race conditions**: Check for async operations that might complete out of order
3. **Modal management**: Verify modals are closed before navigation
4. **Duplicate logic**: Look for opportunities to combine related useEffects
5. **Loading states**: Ensure data fetching completion is properly checked

## Development Environment Setup

1. Navigate to `front/` directory
2. Install dependencies: `npm install`
3. Set up environment variables based on the mode (development/staging/production)
4. Run development server: `npm run dev`