template/AGENTS.md

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

# 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