# CLAUDE.md

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

## Project Overview

This is a microservices-based Online Judge (OJ) system with AI integration called AIOJ (AI Online Judge). It's built with Spring Boot 3.5.7 and Spring Cloud 2025.0.0, following a modular Maven multi-module architecture.

## Common Development Commands

### Building the Project
```bash
# Build entire project
mvn clean install

# Build with specific environment profile
mvn clean install -P dev     # Development (default)
mvn clean install -P test    # Testing
mvn clean install -P prod    # Production

# Format code according to Spring standards
mvn spring-javaformat:apply

# Build Docker images using Jib
mvn clean package jib:build

# Or use Maven wrapper
./mvnw clean install
```

### Running Services
Each service runs on different ports:
- Gateway: 8085
- Other services: configured via Nacos

Run individual services from their respective directories:
```bash
cd aioj-backend-gateway
mvn spring-boot:run

# Or with specific profile
mvn spring-boot:run -Dspring.profiles.active=dev
```

### Database Setup
1. Create databases using the provided script:
```bash
mysql -u root -p < db/create_db.sql
```
This creates three databases: `aioj_dev`, `aioj_test`, and `aioj_prod`

## Architecture Overview

### Microservices Architecture
The system consists of seven main services:

1. **aioj-backend-gateway** (Port 8085)
   - API Gateway using Spring Cloud Gateway
   - Routes requests to appropriate services
   - Built with WebFlux for reactive programming

2. **aioj-backend-auth**
   - OAuth2 authentication and authorization service
   - Manages user credentials and tokens

3. **aioj-backend-user-service**
   - User management and profiles
   - Handles registration, login, profile updates
   - Integrates with Redis for session management

4. **aioj-backend-question-service**
   - Problem/question management
   - Handles problem storage and retrieval

5. **aioj-backend-judge-service**
   - Core OJ functionality for code execution
   - Supports multiple programming languages

6. **aioj-backend-ai-service**
   - AI integration for enhanced features
   - Code analysis and automated feedback

7. **aioj-backend-upms** (User Permission Management System)
   - Role-based access control
   - Permission management

### Common Modules
- **aioj-backend-common**: Shared utilities with sub-modules:
  - `core`: Core utilities and configurations
  - `log`: Custom logging implementation
  - `starter`: Auto-configuration starters
  - `mybatis`: Database access layer
  - `feign`: HTTP client for service communication
  - `bom`: Bill of Materials for dependency management

## Technology Stack

### Core Technologies
- **Java 17**
- **Spring Boot 3.5.7**
- **Spring Cloud 2025.0.0**
- **Spring Cloud Alibaba 2025.0.0.0**
- **Maven** for build management

### Database & Persistence
- **MySQL 9.4.0** as primary database
- **MyBatis-Plus 3.5.14** for ORM
- **Redis** for caching and session management

### Cloud & Infrastructure
- **Nacos** for service discovery and configuration (server: 10.0.0.10:8848)
- **Spring Cloud Gateway** for API routing
- **Docker** with Jib plugin for containerization
- **Sentinel** for circuit breaking

### Security
- **Spring Security 6.5.6** with OAuth2
- JWT token-based authentication
- Role-based access control

### API Documentation
- **Knife4j** (OpenAPI 3) integrated across services

## Configuration Management

### Environment-Specific Configuration
Three environments are supported:
- `dev` (development, default)
- `test` (testing)
- `prod` (production)

Configuration files:
- `bootstrap.yml` - Nacos service discovery configuration
- `application.yml` - Main application configuration
- `application-{env}.yml` - Environment-specific settings

### Nacos Integration
All services use Nacos for:
- Service discovery
- Configuration management
- Centralized properties management

Default Nacos configuration:
```yaml
spring:
  cloud:
    nacos:
      discovery:
        server-addr: 10.0.0.10:8848
        username: nacos
        password: nacos
```

## Database Schema

### Environment Databases
- Development: `aioj_dev`
- Testing: `aioj_test`
- Production: `aioj_prod`

All databases use UTF-8 character set with `utf8mb4_general_ci` collation.

## Development Guidelines

### Code Formatting
- Uses Spring JavaFormat plugin for consistent code style
- IDE plugin available: https://repo1.maven.org/maven2/io/spring/javaformat/spring-javaformat-intellij-idea-plugin
- Run `mvn spring-javaformat:apply` before commits

### Docker Integration
- Jib plugin configured for container builds
- Target registry: `10.0.0.3/aioj/{service-name}:{version}`
- JVM memory configured: -Xms512m -Xmx512m

### Service Communication
- Uses OpenFeign for inter-service communication
- Load balancing with Spring Cloud LoadBalancer
- Circuit breaking with Sentinel

### Logging
- Custom logging implementation in `aioj-backend-common-log`
- Integrates with Spring Security for context logging
- Uses Hutool utilities for enhanced logging

## Testing
- Spring Boot Test framework included
- Spring Security Test for authentication testing
- Test structure is evolving - check individual modules for test coverage

## Important Notes

1. **Service Dependencies**: Services depend on Nacos for discovery - ensure Nacos is running before starting services
2. **Database Setup**: Run the database creation script before first run
3. **Port Configuration**: Gateway runs on 8085, other services are dynamically registered
4. **Environment Profiles**: Default is `dev` - use appropriate profiles for different environments
5. **Configuration Management**: Most configuration is externalized to Nacos - check Nacos for service-specific settings