plates-server/CLAUDE.md

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