AI_OJ/CLAUDE.md

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