105 lines
2.9 KiB
Markdown
105 lines
2.9 KiB
Markdown
# AGENTS.md - Project Guidelines
|
|
|
|
## Project Overview
|
|
|
|
A Kotlin Spring Boot web application template using modern JVM stack with database access layer.
|
|
|
|
**Type**: Backend web service
|
|
**Language**: Kotlin 2.2.21
|
|
**Build Tool**: Gradle (Kotlin DSL)
|
|
**JDK**: Java 21
|
|
|
|
## Tech Stack
|
|
|
|
- **Framework**: Spring Boot 4.0.2
|
|
- **Web**: Spring Web MVC
|
|
- **Security**: Spring Security (permissive local profile)
|
|
- **Database**: PostgreSQL + jOOQ (typesafe SQL) + Liquibase (migrations)
|
|
- **Build Features**: GraalVM Native Image support
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── main/kotlin/com/example/demo/
|
|
│ ├── App.kt # Application entry point
|
|
│ ├── Config.kt # Security configuration (local profile)
|
|
│ ├── api/ # REST controllers
|
|
│ │ └── HelloController.kt
|
|
│ └── service/ # Business logic
|
|
│ └── HelloService.kt
|
|
├── main/resources/
|
|
│ ├── application.yaml # App config (port 8081, postgres)
|
|
│ └── db/changelog/ # Liquibase migrations
|
|
│ └── db.changelog-master.yaml
|
|
└── test/kotlin/com/example/demo/
|
|
└── AppTests.kt # Basic context load test
|
|
```
|
|
|
|
## Key Conventions
|
|
|
|
### Code Style
|
|
- Kotlin with strict JSR-305 annotations (`-Xjsr305=strict`)
|
|
- Constructor injection for dependencies
|
|
- Use `private val` for injected services
|
|
|
|
### Architecture Patterns
|
|
- **Controller Layer**: Handle HTTP, delegate to services
|
|
- **Service Layer**: Business logic, use jOOQ DSLContext for DB
|
|
- **Database**: jOOQ-generated typesafe code in `build/generated-src/jooq/`
|
|
|
|
### Database Access
|
|
- Use jOOQ generated tables: `Tables.HELLO`, `Tables.TASK`
|
|
- Access records via `dslContext.select().from(Tables.X).fetch...`
|
|
- Migrations via Liquibase YAML in `src/main/resources/db/changelog/`
|
|
|
|
## Testing
|
|
|
|
- Framework: JUnit 5 with Spring Boot Test
|
|
- Run: `./gradlew test`
|
|
- Native test: `./gradlew nativeTest`
|
|
|
|
## Database Setup
|
|
|
|
Requires PostgreSQL running locally:
|
|
- Database: `postgres`
|
|
- User/Password: `postgres`/`postgres`
|
|
- URL: `jdbc:postgresql://localhost:5432/postgres`
|
|
- Port: 5432
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Run application
|
|
./gradlew bootRun
|
|
|
|
# Build
|
|
./gradlew build
|
|
|
|
# Run tests
|
|
./gradlew test
|
|
|
|
# Generate jOOQ classes (requires DB to be running)
|
|
./gradlew generateJooq
|
|
|
|
# Create native image
|
|
./gradlew nativeCompile
|
|
|
|
# Build Docker image
|
|
./gradlew bootBuildImage
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
- **jOOQ code generation**: Requires PostgreSQL to be running
|
|
- **Security**: Local profile (`local`) disables all auth for development
|
|
- **Port**: Application runs on port 8081 (not 8080)
|
|
- **Virtual threads**: Enabled in `application.yaml`
|
|
|
|
## Adding New Features
|
|
|
|
1. Create Liquibase migration in `db.changelog-master.yaml`
|
|
2. Run `./gradlew generateJooq` to update generated classes
|
|
3. Create service class in `service/` package
|
|
4. Create controller in `api/` package
|
|
5. Write tests following existing patterns
|