onedev/CLAUDE.md

# CLAUDE.md

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

## Build Commands

OneDev uses Maven as its build system with a multi-module structure.

### Essential Commands
- **Build the project**: `mvn clean compile`
- **Run tests**: `mvn test`
- **Package the application**: `mvn clean package`
- **Build without tests**: `mvn clean package -DskipTests`
- **Build specific module**: `mvn clean package -pl server-core`
- **Install to local repository**: `mvn clean install`

### Profiles
- **Community Edition**: `mvn clean package -Pce` (excludes enterprise features)
- **Default/Enterprise**: `mvn clean package` (includes all features)

### Testing
- **Run all tests**: `mvn test`
- **Run specific test class**: `mvn test -Dtest=ClassName`
- **Run tests for specific module**: `mvn test -pl server-core`

## Architecture Overview

OneDev is a comprehensive DevOps platform built with a sophisticated multi-module Maven architecture:

### Core Technology Stack
- **Web Framework**: Apache Wicket 7.18.0 (component-based UI)
- **REST API**: Jersey 2.38 (JAX-RS implementation)
- **Database/ORM**: Hibernate 5.4.24.Final with HikariCP connection pooling
- **Web Server**: Embedded Jetty 9.4.57
- **Dependency Injection**: Google Guice with custom plugin loading
- **Security**: Apache Shiro for authentication/authorization
- **Search**: Apache Lucene 8.7.0
- **Git**: JGit 5.13.3 for Git operations
- **Clustering**: Hazelcast 5.3.5 for distributed coordination

### Module Structure
- **server-core**: Core application logic, entities, and services
- **server-ee**: Enterprise edition features
- **server-plugin**: Plugin framework and all plugin implementations
- **server-product**: Final packaging and deployment artifacts

### Key Subsystems

#### 1. Application Bootstrap
- Main entry point: `server-core/src/main/java/io/onedev/server/OneDev.java`
- Module configuration: `server-core/src/main/java/io/onedev/server/CoreModule.java`
- Handles server lifecycle, clustering, and graceful shutdown

#### 2. Entity Management
Key domain entities and managers in `server-core/src/main/java/io/onedev/server/model/`:
- Project, User, Group, Role management
- Issue tracking with customizable workflows
- Pull request lifecycle and code review
- Build and CI/CD pipeline management
- Package registry operations

#### 3. Git Integration
- Full Git repository management via JGit
- Git hooks for policy enforcement in `server-core/src/main/java/io/onedev/server/git/`
- Code browsing, diff visualization, and blame tracking
- SSH server for Git operations

#### 4. Web Layer (Wicket)
- Component-based UI in `server-core/src/main/java/io/onedev/server/web/`
- AJAX-heavy interface with WebSocket support
- Project browsing, issue boards, pull request review interface

#### 5. REST API (Jersey)
- RESTful services in `server-core/src/main/java/io/onedev/server/rest/`
- Project, User, Build, Issue resources
- WebHook endpoints and package registry APIs

#### 6. CI/CD System
- YAML-based build specifications
- Multi-executor support (Kubernetes, Docker, Shell)
- Real-time log streaming and artifact management

#### 7. Plugin Architecture
- Extensible plugin system in `server-plugin/`
- Categories: build specs, executors, authenticators, importers, notifications, package registries, report processors
- Plugin contributions via Guice modules

## Development Patterns

### Code Organization
- **Package-by-feature**: Organized around business capabilities
- **Dependency Injection**: Guice-based DI throughout the application
- **Interface-based design**: For testability and modularity
- **Custom annotations**: Extensive use for validation and metadata

### Design Patterns Used
- Repository Pattern for data access
- Observer Pattern for event handling
- Command Pattern for Git operations
- Strategy Pattern for pluggable components
- Template Method for build processing

### Testing Strategy
- Unit tests in `src/test/java` directories
- Git operation tests with test repositories
- Component and integration tests
- Utility method tests
- Focus on testing business logic and Git operations

## Common Development Tasks

### Working with Entities
- Entities are in `server-core/src/main/java/io/onedev/server/model/`
- Use corresponding managers for database operations
- Follow JPA/Hibernate patterns for persistence

### Adding REST Endpoints
- Create resources in `server-core/src/main/java/io/onedev/server/rest/resource/`
- Follow Jersey/JAX-RS patterns
- Use existing security annotations for authentication

### Creating Plugins
- Extend `AbstractPlugin` class
- Implement appropriate interfaces for the plugin category
- Add Guice module configuration
- Place in appropriate `server-plugin/server-plugin-*` module

### Working with Git
- Use JGit APIs through OneDev's Git service layer
- Follow patterns in `server-core/src/main/java/io/onedev/server/git/`
- Handle Git operations asynchronously when possible

### Adding Web Components
- Create Wicket components in `server-core/src/main/java/io/onedev/server/web/`
- Follow existing component patterns and CSS frameworks
- Use AJAX for dynamic behavior

## Configuration and Deployment

### Key Configuration Files
- `server-product/system/conf/server.properties`: HTTP/SSH ports, clustering
- `server-product/system/conf/hibernate.properties`: Database configuration
- `server-product/system/conf/logback.xml`: Logging configuration

### Deployment Options
- Standalone JAR with embedded Jetty
- Docker containers (see `server-product/docker/`)
- Kubernetes via Helm charts (see `server-product/helm/`)

### Database Support
- PostgreSQL (recommended for production)
- MySQL/MariaDB
- HSQLDB (development/testing)

## Performance Considerations

### Caching
- Hibernate second-level cache with Hazelcast
- Build artifact caching
- Git object caching
- Web resource bundling

### Clustering
- Hazelcast-based clustering for high availability
- Distributed session management
- Leader election for coordinated operations

## Important Notes

- OneDev uses a custom plugin loading framework
- Git operations are central to the application architecture
- The system supports both community (CE) and enterprise (EE) editions
- Extensive use of Guice for dependency injection and plugin management
- Focus on performance and resource efficiency
- Battle-tested in production environments for 5+ years