AI_OJ/CLAUDE.md

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

# 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:

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:

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:

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