From 6d612948dbfcdc8bca7152c1ad4ab212efd4f1aa Mon Sep 17 00:00:00 2001
From: pavel <pavelflegr@gmail.com>
Date: Tue, 3 Feb 2026 01:20:32 +0100
Subject: [PATCH] init

---
 AGENTS.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3d81242
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,105 @@
+# 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