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 with Spring Cloud 2025.0.0 and Spring Cloud Alibaba 2025.0.0.0. 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-security Security components for JWT authentication and Spring Security:

   • JwtAuthenticationFilter: JWT token validation filter
   • JwtUtil: JWT token generation and parsing utilities
   • SecurityConfiguration: Spring Security configuration with JWT support
   • SecurityAutoConfiguration: Auto-configuration for security features
   • JWT properties configuration with customizable secret and expiration

4. 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
   • Integrated with Sentinel for circuit breaking

5. 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

6. aioj-backend-common-mybatis MyBatis ORM framework extensions:

   • Auto-fill functionality for createTime and updateTime fields
   • Pagination interceptor implementation
   • MyBatis configuration auto-configuration classes

7. 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 based on path patterns
   • Authentication token validation before forwarding requests
   • Sentinel integration for rate limiting and circuit breaking
   • Load balancing and service discovery via Nacos

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 with advanced validation and flow control:

   • Programming problem management with CRUD operations
   • Chain of Responsibility pattern for request validation:
     • QuestionTitleVerifyChain, QuestionContentVerifyChain, etc. for create operations
     • QuestionUpdateExistVerifyChain, QuestionUpdateTitleVerifyChain, etc. for update operations
     • QuestionExistVerifyChain, QuestionStatusVerifyChain, CodeVerifyChain, LanguageVerifyChain for submission validation
   • Sentinel flow control with Nacos datasource for dynamic rule management
   • Redis integration for caching and session management
   • Support for problem difficulty levels, tags, and judge configuration
   • Integration with judge service for code 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 (modular structure):

   • aioj-backend-upms-api: API definitions and DTOs for UPMS functionality
   • aioj-backend-upms-biz: Business logic implementation
   • Low-level user and permission management
   • Menu and resource access control
   • Integration with other services for authorization

8. aioj-backend-file-service File storage and management service:

   • Tencent Cloud COS integration for object storage
   • File upload, download, and management APIs
   • Support for various file types
   • Nacos service discovery integration

9. aioj-backend-blog-service Blog and content sharing service:

   • User article creation and publishing
   • Markdown support with Flexmark parser
   • Redis caching for improved performance
   • Spring Session for distributed session management
   • Technical experience sharing and discussion platform

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
• Skip tests: mvn clean install -DskipTests

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

Docker Image Build (using JIB)

• Build and push Docker image: mvn package jib:build -pl <module-name>
• Build Docker image to tar file: mvn package jib:buildTar -pl <module-name>
• Example: mvn package jib:build -pl aioj-backend-gateway

Technology Stack

Core Framework

• Spring Boot: 3.5.7
• Spring Cloud: 2025.0.0
• Spring Cloud Alibaba: 2025.0.0.0
• Java Version: 17

Infrastructure Components

• Service Discovery: Alibaba Nacos
• Flow Control: Alibaba Sentinel
• API Gateway: Spring Cloud Gateway
• Load Balancing: Spring Cloud LoadBalancer

Data & Persistence

• ORM Framework: MyBatis
• Database: MySQL
• Cache: Redis (Spring Data Redis)
• Session: Spring Session with Redis

Security & Authentication

• Security Framework: Spring Security
• Authentication: JWT (JSON Web Tokens)
• JWT Library: JJWT (io.jsonwebtoken)

Service Communication

• HTTP Client: OpenFeign
• Circuit Breaker: Sentinel

Storage & Content

• Object Storage: Tencent Cloud COS
• Markdown Parser: Flexmark 0.64.8

Documentation

• API Documentation: SpringDoc OpenAPI 3
• API UI: Knife4j

Utilities

• Java Utilities: Hutool (hutool-core, hutool-extra, hutool-crypto)
• Logging: SLF4J with Logback (via Spring Boot)
• JSON Processing: Jackson (via Spring Boot)

Build & Deploy

• Build Tool: Maven
• Code Formatting: Spring Java Format Maven Plugin 0.0.47
• Docker Build: JIB Maven Plugin 3.4.5
• Git Info: Git Commit ID Plugin 9.0.2
• Version Management: Flatten Maven Plugin 1.6.0

Architecture Highlights

• Authentication & Security:

  • JWT-based authentication with JwtAuthenticationFilter in common-security
  • Centralized security configuration shared across services
  • Token generation, parsing, and validation utilities in JwtUtil

• Flow Control & Rate Limiting:

  • Alibaba Sentinel integration for flow control and circuit breaking
  • Dynamic rule management with Nacos datasource
  • Applied in question-service for submission rate limiting
  • Gateway-level traffic control and service protection

• Request Validation:

  • Chain of Responsibility pattern in question-service for complex validation logic
  • Modular and extensible validation chains for different operations
  • Context-based validation with clear separation of concerns

• Logging:

  • Aspect-oriented logging with SysLogAspect in common-log
  • Event-driven logging mechanism with SysLogEvent and SysLogListener

• Database:

  • MyBatis with auto-fill for create/update times in common-mybatis
  • Pagination support with interceptor implementation

• Caching & Session:

  • Redis integration for distributed caching
  • Spring Session for distributed session management
  • Applied in question-service and blog-service

• Inter-service communication:

  • Feign clients with auto-configuration from common-feign
  • Integrated with Sentinel for circuit breaking
  • Nacos service discovery for dynamic service routing

• File Storage:

  • Tencent Cloud COS integration in file-service
  • Support for object storage and CDN acceleration

• Content Processing:

  • Markdown parsing with Flexmark in blog-service
  • Rich text content support for technical articles

• 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
• Question Service Application: aioj-backend-question-service/src/main/java/cn/meowrain/aioj/backend/question/QuestionServiceApplication.java
• File Service Application: aioj-backend-file-service/src/main/java/cn/meowrain/aioj/backend/file/FileServiceApplication.java
• Blog Service Application: aioj-backend-blog-service/src/main/java/cn/meowrain/aioj/backend/blog/BlogServiceApplication.java
• UPMS Service Application: aioj-backend-upms/aioj-backend-upms-biz/src/main/java/cn/meowrain/aioj/backend/upms/UpmsApplication.java

Key Design Patterns

Chain of Responsibility Pattern (Question Service)

Located in aioj-backend-question-service/src/main/java/cn/meowrain/aioj/backend/question/dto/chains/:

• Create Question Validation: QuestionTitleVerifyChain, QuestionContentVerifyChain, QuestionDifficultyVerifyChain, QuestionTagsVerifyChain, QuestionJudgeConfigVerifyChain
• Update Question Validation: QuestionUpdateExistVerifyChain, QuestionUpdateTitleVerifyChain, QuestionUpdateContentVerifyChain, etc.
• Submit Question Validation: QuestionExistVerifyChain, QuestionStatusVerifyChain, LanguageVerifyChain, CodeVerifyChain
• Context Objects: QuestionCreateRequestParamVerifyContext, QuestionUpdateRequestParamVerifyContext, QuestionSubmitRequestParamVerifyContext

Security Filter Chain (Common Security)

Located in aioj-backend-common/aioj-backend-common-security/:

• JwtAuthenticationFilter: Pre-authentication filter for JWT token validation
• SecurityConfiguration: Spring Security filter chain configuration
• SecurityAutoConfiguration: Auto-configuration for security beans

Development Guidelines

Module Dependencies

• Service modules should depend on common modules, not other service modules
• Use Feign clients for inter-service communication
• Common modules should be lightweight and not depend on service-specific logic

Code Style

• Follow Spring Java Format conventions
• Run mvn spring-javaformat:apply before committing code
• Use Lombok annotations to reduce boilerplate code
• Keep classes and methods focused and single-purpose

Security Best Practices

• Use @PreAuthorize annotations for method-level security
• Never expose sensitive information in API responses
• Always validate and sanitize user input
• Use the chain of responsibility pattern for complex validation logic

API Design

• Follow RESTful conventions
• Use appropriate HTTP methods (GET, POST, PUT, DELETE)
• Return consistent response structures using common DTOs
• Document APIs using SpringDoc annotations

Error Handling

• Use custom exception classes for domain-specific errors
• Implement global exception handlers in controllers
• Return meaningful error messages to clients
• Log errors appropriately with context information

Testing

• Write unit tests for service layer logic
• Use integration tests for controller endpoints
• Mock external dependencies in tests
• Aim for high code coverage on critical paths

Configuration Management

• Use application.yml for service configuration
• Externalize environment-specific settings
• Use Nacos for centralized configuration management
• Never commit sensitive credentials to version control

Flow Control with Sentinel

• Configure Sentinel rules in Nacos for dynamic updates
• Use @SentinelResource annotations for method-level flow control
• Define fallback methods for degraded service behavior
• Monitor Sentinel dashboard for real-time metrics
• Apply flow rules at both gateway and service levels

Project Structure Best Practices

Package Organization

cn.meowrain.aioj.backend.<service-name>
├── controller/       # REST API endpoints
├── service/          # Business logic
│   └── impl/        # Service implementations
├── mapper/          # MyBatis mappers
├── entity/          # Database entities
├── dto/             # Data transfer objects
│   └── chains/      # Validation chains (if applicable)
├── config/          # Spring configuration classes
├── common/          # Service-specific common utilities
│   ├── enums/       # Enumerations
│   └── constants/   # Constants
└── <ServiceName>Application.java  # Main application class

Naming Conventions

• Controllers: <Resource>Controller (e.g., QuestionController)
• Services: <Resource>Service (interface) and <Resource>ServiceImpl (implementation)
• Mappers: <Resource>Mapper (e.g., QuestionMapper)
• Entities: Noun representing the domain object (e.g., Question, User)
• DTOs: <Operation><Resource>DTO (e.g., CreateQuestionDTO, UpdateQuestionDTO)
• Validation Chains: <Resource><Property>VerifyChain (e.g., QuestionTitleVerifyChain)

Infrastructure Setup

Required Services

Before running the microservices, ensure the following infrastructure components are running:

1. Nacos Server (Service Discovery & Configuration Center)

   • Default URL: http://localhost:8848/nacos
   • Required for service registration and configuration management

2. Sentinel Dashboard (Optional, for flow control monitoring)

   • Monitor real-time traffic and configure flow rules
   • Rules are persisted to Nacos

3. MySQL Database

   • Required for persistent data storage
   • Each service may have its own database schema

4. Redis Server

   • Required for caching and session management
   • Used by question-service and blog-service

5. Tencent Cloud COS (for file-service)

   • Configure credentials in application configuration
   • Required only if using file-service

Service Startup Order (Recommended)

1. Start infrastructure services (MySQL, Redis, Nacos)
2. Start auth service (authentication required by other services)
3. Start gateway service (API entry point)
4. Start business services (user-service, question-service, etc.) in any order

Configuration Files

Each service has application.yml with profiles:

• application.yml: Common configuration
• application-dev.yml: Development environment
• application-test.yml: Test environment
• application-prod.yml: Production environment

Activate profiles using: spring.profiles.active=dev or -Dspring.profiles.active=dev