# CLAUDE.md

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

## Codebase Overview

This is a microservices architecture for an Online Judge (OJ) system, built on **Spring Boot 3.5.7**. The project uses Maven as the build tool and follows a modular monorepo structure, with clearly separated core modules and service modules.

### Core Modules

The `aioj-backend-common` directory contains shared components and utilities used across all service modules:

1. **aioj-backend-common-bom**
   Bill of materials for centralized dependency management. This ensures consistent versions of all external libraries across all modules.

2. **aioj-backend-common-core**
   Core utilities and Spring framework extensions:
   - `BannerApplicationRunner`: Custom application banner display during startup
   - `SpringContextHolder`: Spring context accessor for non-Spring-managed classes
   - `JavaTimeModule`: Jackson module for Java 8+ time API support
   - Common constants and enumerations
   - Application-level configurations and auto-configuration classes

3. **aioj-backend-common-feign**
   Feign client configurations for seamless inter-service communication:
   - Auto-configuration for Feign clients with default settings
   - `@EnableAIOJFeignClients` annotation for enabling Feign clients with predefined base packages
   - Feign interceptors and error handling mechanisms

4. **aioj-backend-common-log**
   Aspect-oriented programming (AOP) based logging framework:
   - `SysLogAspect`: Aspect for logging system operations (controller methods, service calls)
   - `SysLogEvent` and `SysLogListener`: Event-driven logging mechanism
   - `SysLogUtils`: Utility class for creating and managing log entries
   - Configuration properties for logging behavior

5. **aioj-backend-common-mybatis**
   MyBatis ORM framework extensions:
   - Auto-fill functionality for `createTime` and `updateTime` fields
   - Pagination interceptor implementation
   - MyBatis configuration auto-configuration classes

6. **aioj-backend-common-starter**
   Auto-configuration starters for easily enabling common features in service modules.


### Service Modules

The service modules represent the individual microservices that make up the system:

1. **aioj-backend-auth**
   Authentication and authorization service:
   - JWT-based authentication with `JwtAuthenticationFilter`
   - Security configuration with Spring Security
   - User login, token generation, and validation
   - Permission verification and access control

2. **aioj-backend-gateway**
   API gateway for request routing and filtering:
   - Request routing to appropriate service modules
   - Authentication token validation before forwarding requests
   - Rate limiting and request filtering mechanisms

3. **aioj-backend-judge-service**
   Code judge service (under development):
   - Will handle code submission, compilation, and execution
   - Support for multiple programming languages
   - Test case validation and result return

4. **aioj-backend-user-service**
   User management service:
   - User registration, profile management, and information retrieval
   - User role and permission assignment
   - Integration with the auth service for authentication

5. **aioj-backend-question-service**
   Question bank service (under development):
   - Will manage programming problems, test cases, and problem categories
   - Support for problem difficulty levels and tags
   - Integration with the judge service for problem submission

6. **aioj-backend-ai-service**
   AI-related functionality service (under development):
   - Will provide AI-assisted features like problem recommendation, code analysis, etc.

7. **aioj-backend-upms**
   User, permission, and menu management service:
   - Low-level user and permission management
   - Menu and resource access control
   - Integration with other services for authorization

## Commonly Used Commands

### Build
- **Build the entire project**: `mvn clean compile`
- **Build with tests**: `mvn clean install`
- **Build a single module**: `mvn clean compile -pl aioj-backend-auth`

### Code Formatting
- **Format code**: `mvn spring-javaformat:apply`
- **Check code format**: `mvn spring-javaformat:check`

### Testing
- **Run all tests**: `mvn test`
- **Run tests for a single module**: `mvn test -pl aioj-backend-user-service`

### Running Services
- **Run a service locally**: Use Spring Boot's `Application` class directly in IDE or use `mvn spring-boot:run -pl <module-name>`
- **Example**: `mvn spring-boot:run -pl aioj-backend-auth`

## Architecture Highlights

- **Authentication**: JWT-based authentication implemented in `aioj-backend-auth` with `JwtAuthenticationFilter`
- **Logging**: Aspect-oriented logging with `SysLogAspect` in `aioj-backend-common-log`
- **Database**: MyBatis with auto-fill for create/update times implemented in `common-mybatis`
- **Inter-service communication**: Feign clients with auto-configuration from `common-feign`
- **Banner**: Custom application banner system in `common-core`

## Key Entry Points

- **Gateway Application**: `aioj-backend-gateway/src/main/java/cn/meowrain/aioj/backend/gateway/AIOJGatewayApplication.java`
- **Auth Application**: `aioj-backend-auth/src/main/java/cn/meowrain/aioj/backend/auth/AIOJAuthApplication.java`
- **User Service Application**: `aioj-backend-user-service/src/main/java/cn/meowrain/aioj/backend/userservice/UserServiceApplication.java`