Skip to content

Commit 1b4db5e

Browse files
TrueNineTrueNine
committed
Add CODEBUDDY.md for project guidance and development workflow
- Provide an overview of the Compose Server project - Include essential development commands, architecture details, and testing standards - Outline build system configuration and module organization - Define key interfaces, abstractions, and service patterns - Detail Maven Central publishing and performance considerations - Offer IDE integration and setup instructions
1 parent 61d6a71 commit 1b4db5e

1 file changed

Lines changed: 232 additions & 0 deletions

File tree

‎CODEBUDDY.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# CODEBUDDY.md
2+
3+
This file provides guidance to CodeBuddy Code when working with the Compose Server repository.
4+
5+
## Project Overview
6+
7+
**Compose Server** is a modern enterprise-grade Kotlin server-side framework library featuring modular architecture design. It provides 30+ specialized modules covering AI integration, object storage, database operations, security, payments, messaging, data processing, and monitoring capabilities. All modules are published to Maven Central for selective integration.
8+
9+
**Technology Stack:** Kotlin 2.2.0, Spring Boot 3.5.4, Jimmer 0.9.105, Gradle 9.x, Java 24+, PostgreSQL, Redis, Caffeine, MinIO, LangChain4j
10+
11+
## Essential Development Commands
12+
13+
### Build and Development
14+
```bash
15+
# Build the entire project
16+
./gradlew build
17+
18+
# Clean build outputs
19+
./gradlew clean
20+
21+
# Run all tests and checks
22+
./gradlew check
23+
24+
# Build specific module
25+
./gradlew :{module}:build
26+
27+
# Run tests for specific module
28+
./gradlew :{module}:check
29+
30+
# Publish to local Maven repository
31+
./gradlew publishToMavenLocal
32+
33+
# Publish specific module locally
34+
./gradlew :{module}:publishToMavenLocal
35+
```
36+
37+
### Code Quality (REQUIRED before commits)
38+
```bash
39+
# Fix code formatting (MUST run before commit)
40+
./gradlew spotlessApply
41+
42+
# Format version catalog
43+
./gradlew versionCatalogFormat
44+
45+
# Check for dependency updates
46+
./gradlew versionCatalogUpdate
47+
```
48+
49+
### Testing Commands
50+
```bash
51+
# Run all tests with parallel execution
52+
./gradlew test
53+
54+
# Run tests with TestContainers (requires Docker)
55+
./gradlew integrationTest
56+
57+
# Run specific test class
58+
./gradlew test --tests "ClassName"
59+
60+
# Run tests with specific profile
61+
./gradlew test -Dspring.profiles.active=test
62+
```
63+
64+
## Architecture Overview
65+
66+
### Modular Structure
67+
The project follows a layered modular architecture with clear functional boundaries:
68+
69+
```
70+
🎯 Application Layer
71+
↓ (selective integration)
72+
🏢 Business Module Layer (30+ modules)
73+
├── 🤖 AI Services (ai-*)
74+
├── 📦 Object Storage (oss-*)
75+
├── 💳 Payment Services (pay-*)
76+
├── 📱 SMS Services (sms-*)
77+
├── 🔐 Security (security-*)
78+
├── 🗄️ Database (rds-*)
79+
└── 🔧 Dependencies (depend-*, ksp-*, psdk-*)
80+
↓ (all depend on)
81+
🏗️ Infrastructure Layer
82+
├── 🔧 Shared Foundation (shared)
83+
├── 📋 Dependency Management (bom)
84+
├── 🧪 Testing Toolkit (testtoolkit)
85+
└── ⚡ Caching Abstractions (cacheable)
86+
```
87+
88+
### Module Organization Pattern
89+
Each functional domain follows a consistent structure:
90+
- `{domain}-shared/`: Core interfaces and abstractions
91+
- `{domain}-{provider}/`: Provider-specific implementations (e.g., `oss-minio`, `pay-wechat`)
92+
- `autoconfig/`: Spring Boot auto-configuration classes
93+
- Package format: `io.github.truenine.composeserver.{module-name}`
94+
95+
### Key Architectural Patterns
96+
97+
#### Auto-Configuration Pattern
98+
Every module uses Spring Boot auto-configuration with:
99+
- `AutoConfigEntrance.kt` as entry point in `autoconfig` package
100+
- `@ComponentScan` for automatic discovery
101+
- `@EnableConfigurationProperties` for type-safe configuration
102+
- `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` for registration
103+
104+
#### Repository Pattern
105+
- `IRepo` interface extending Jimmer's `KRepository`
106+
- `IPersistentEntity` base interface for all entities
107+
- Jimmer ORM integration with strong type safety
108+
109+
#### Service Abstractions
110+
- Unified interfaces like `IObjectStorageService` for multi-provider support
111+
- Coroutines integration throughout async operations
112+
- Provider-swappable implementations
113+
114+
## Testing Architecture
115+
116+
### TestContainers Integration
117+
The project uses comprehensive TestContainers integration:
118+
- `ITestContainerBase`: Base interface for all containers
119+
- Specific container interfaces: `IDatabasePostgresqlContainer`, `ICacheRedisContainer`, etc.
120+
- Automatic container startup via `@DynamicPropertySource`
121+
- Container reuse enabled for performance
122+
- Extension functions for convenient testing (e.g., `mysql { }` blocks)
123+
124+
### Test Organization Standards
125+
- Test classes use `@Nested` inner classes for scenario organization
126+
- Chinese method names with backticks for test descriptions
127+
- Disable `@DisplayName` annotation
128+
- Test categories: normal cases, exception cases, boundary cases
129+
- Idempotency verification for database operations
130+
131+
### Test Configuration
132+
```yaml
133+
# application-test.yml
134+
compose:
135+
testtoolkit:
136+
enabled: true
137+
disable-condition-evaluation-report: true
138+
enable-virtual-threads: true
139+
ansi-output-mode: always
140+
```
141+
142+
## Build System
143+
144+
### Gradle Configuration
145+
- **Version Catalog**: `gradle/libs.versions.toml` for unified dependency management
146+
- **Convention Plugins**: `build-logic/` contains reusable build conventions
147+
- **Primary Convention**: `kotlinspring-conventions` for most modules
148+
- **Performance Optimized**: Parallel builds, caching, configuration cache enabled
149+
150+
### Convention Plugins Available
151+
- `buildlogic.kotlinspring-conventions`: Primary for Kotlin Spring modules
152+
- `buildlogic.publish-conventions`: Maven Central publishing
153+
- `buildlogic.spotless-conventions`: Code formatting
154+
- `buildlogic.jacoco-conventions`: Code coverage
155+
156+
### Key Build Files
157+
- Root: `build.gradle.kts`, `settings.gradle.kts`, `gradle.properties`
158+
- Module: `{module}/build.gradle.kts`
159+
- Version management: `gradle/libs.versions.toml`
160+
- Build logic: `build-logic/src/main/kotlin/`
161+
162+
## Development Workflow
163+
164+
### Before Every Commit
165+
1. **MANDATORY**: Run `./gradlew spotlessApply` to fix code formatting
166+
2. Run `./gradlew check` to ensure all tests pass
167+
3. Verify module builds independently if changes span multiple modules
168+
169+
### Adding New Modules
170+
1. Create module directory following naming convention
171+
2. Add to `settings.gradle.kts` include list
172+
3. Apply appropriate convention plugins in module's `build.gradle.kts`
173+
4. Implement auto-configuration in `autoconfig` package
174+
5. Add to version catalog if publishing to Maven Central
175+
176+
### Code Generation (KSP)
177+
- Annotation definitions in `ksp-meta/`
178+
- Processor implementation in `ksp-plugin/`
179+
- Generated code integration through Gradle KSP plugin
180+
181+
## Key Interfaces and Abstractions
182+
183+
### Core Domain Interfaces
184+
- `IAnyEnum`: Type-safe enum abstraction for serialization
185+
- `IPageParam`: Pagination parameter interface
186+
- `IPersistentEntity`: Base entity with audit fields
187+
188+
### Service Layer Interfaces
189+
- `IObjectStorageService`: Unified object storage with coroutines
190+
- `IRepo`: Repository pattern with Jimmer integration
191+
- `IKeysRepo`: Cryptographic key management
192+
193+
### Configuration Interfaces
194+
- Properties classes with `@ConfigurationProperties`
195+
- Environment-specific configuration overrides
196+
- TestContainer-specific properties
197+
198+
## Maven Central Publishing
199+
200+
All modules are published as `io.github.truenine:composeserver-{module-name}:${version}`
201+
- Current version managed in `gradle/libs.versions.toml`
202+
- BOM available for unified version management
203+
- Selective integration supported - choose only needed modules
204+
205+
## Performance Considerations
206+
207+
### JVM Configuration
208+
```properties
209+
# gradle.properties
210+
org.gradle.jvmargs=-Xmx5g -XX:MaxMetaspaceSize=1g -XX:+UseG1GC
211+
kotlin.daemon.jvmargs=-Xmx2g -XX:+UseG1GC
212+
```
213+
214+
### Build Optimizations
215+
- Parallel builds enabled
216+
- Gradle build cache enabled
217+
- Configuration cache enabled
218+
- Incremental Kotlin compilation
219+
- JUnit parallel test execution
220+
221+
## IDE Integration
222+
223+
### IntelliJ IDEA Plugin
224+
- MCP (Model Context Protocol) integration in `ide/ide-idea-mcp/`
225+
- Code analysis and cleanup tools
226+
- Terminal integration for development workflows
227+
228+
### Development Setup
229+
- Java 24+ required
230+
- Kotlin 2.2.0+ required
231+
- Docker required for TestContainers integration
232+
- IntelliJ IDEA recommended with Kotlin plugin

0 commit comments

Comments
 (0)