# CLAUDE.md

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

## Development Commands

### Core Development
- `yarn start:dev` - Start development server with hot reload
- `yarn start:debug` - Start development server with debugging enabled
- `yarn build` - Build production bundle
- `yarn start:prod` - Start production server from built files

### Testing
- `yarn test` - Run unit tests
- `yarn test:watch` - Run tests in watch mode
- `yarn test:cov` - Run tests with coverage report
- `yarn test:e2e` - Run end-to-end tests
- `yarn test:debug` - Run tests with debugging

### Code Quality
- `yarn lint` - Run ESLint with auto-fix
- `yarn format` - Format code with Prettier

### Production Deployment
- `yarn pm2:start` - Start with PM2 in production mode
- `yarn pm2:start:dev` - Start with PM2 in development mode
- `yarn pm2:status` - Check PM2 process status
- `yarn pm2:logs` - View PM2 logs
- `yarn pm2:restart` - Restart PM2 processes

### Deployment Scripts
- `./deploy-optimized.sh` - Recommended deployment (builds on server)
- `./deploy.sh` - Full deployment with options (`--help` for usage)
- `./deploy-simple.sh` - Basic deployment script

## Architecture Overview

### Core Framework
This is a **NestJS-based fitness and health tracking API** using TypeScript, MySQL with Sequelize ORM, and JWT authentication. The architecture follows NestJS conventions with modular design.

### Module Structure
The application is organized into domain-specific modules:

**Health & Fitness Core:**
- `users/` - User management, authentication (Apple Sign-In, guest), payments, subscriptions
- `diet-records/` - Food logging and nutrition tracking integration
- `food-library/` - Food database with categories and nutritional information
- `exercises/` - Exercise library with categories and instructions
- `training-plans/` - Workout plan management and scheduling
- `workouts/` - Workout session tracking and history
- `goals/` - Goal setting with task management system
- `mood-checkins/` - Mental health and mood tracking

**AI & Intelligence:**
- `ai-coach/` - OpenAI-powered fitness coaching with diet analysis
- `recommendations/` - Personalized content recommendation engine

**Content & Social:**
- `articles/` - Health and fitness article management
- `checkins/` - User check-in and progress tracking
- `activity-logs/` - User activity and engagement tracking

### Key Architectural Patterns

**Database Layer:**
- Sequelize ORM with MySQL
- Models use `@Table` and `@Column` decorators from `sequelize-typescript`
- Database configuration in `database.module.ts` with async factory pattern
- Auto-loading models with `autoLoadModels: true`

**Authentication & Security:**
- JWT-based authentication with refresh tokens
- Apple Sign-In integration via `apple-auth.service.ts`
- AES-256-GCM encryption service for sensitive data
- Custom `@CurrentUser()` decorator and `JwtAuthGuard`

**API Design:**
- Controllers use Swagger decorators for API documentation
- DTOs for request/response validation using `class-validator`
- Base DTO pattern in `base.dto.ts` for consistent responses
- Encryption support for sensitive endpoints

**Logging & Monitoring:**
- Winston logging with daily rotation
- Separate log files: app, error, debug, exceptions, rejections
- PM2 clustering with memory limits (1GB)
- Structured logging with context and metadata

### Configuration Management
- Environment-based configuration using `@nestjs/config`
- Global configuration module
- Environment variables for database, JWT, Apple auth, encryption keys
- Production/development environment separation

### External Integrations
- **OpenAI**: AI coaching and diet analysis
- **Apple**: Sign-in and purchase verification
- **RevenueCat**: Subscription management webhooks
- **Tencent Cloud COS**: File storage service

### Testing Strategy
- Unit tests with Jest (`*.spec.ts` files)
- E2E tests in `test/` directory
- Test configuration in `package.json` jest section
- Encryption service has comprehensive test coverage

### Development Patterns
- Each module follows NestJS structure: controller → service → model
- Services are injected using `@Injectable()` decorator
- Models are Sequelize entities with TypeScript decorators
- DTOs handle validation and transformation
- Guards handle authentication and authorization

## Database Schema Patterns
SQL scripts in `sql-scripts/` directory contain table creation scripts organized by feature:
- `*-tables-create.sql` for table definitions
- `*-sample-data.sql` for seed data
- Migration scripts for database upgrades

## Production Environment
- **Server**: 129.204.155.94
- **Deployment Path**: `/usr/local/web/pilates-server`
- **Ports**: 3002 (production), 3001 (development)
- **Process Management**: PM2 with cluster mode
- **Logging**: Daily rotated logs in `logs/` directory