AGENTS.md

1# Backend Application Guidelines
2 
3`application/` is the WebFlux + R2DBC backend: services, routers, security, migrations, and packaging. Everything here is reactive — never block threads.
4 
5## Structure
6 
7- `application/src/main/java/` — services, routers, endpoints, and configuration.
8- `application/src/main/resources/application*.yaml` — environment configuration.
9- `application/src/main/resources/db/migration/{h2,mariadb,mysql,postgresql}/` — per-dialect migrations.
10- `application/src/main/resources/extensions/` — extension schemas and role templates.
11- `application/src/test/` — backend tests.
12 
13## Commands
14 
15- `./gradlew :application:test` — run backend tests.
16- `./gradlew :application:bootRun` — start the backend dev server.
17- `./gradlew :application:copyUiDist` — embed the built UI into the JAR.
18- `./gradlew generateOpenApiDocs` — emit the OpenAPI spec used to regenerate the UI client.
19 
20## Conventions
21 
22- Keep reactive flows non-blocking; no blocking I/O in request paths.
23- Database migrations are versioned per dialect — never auto-generate them, and review them with the `application/` guide in mind.
24- Tests: JUnit 5 with Spring Boot test support; name unit tests `XxxTest` and integration tests `XxxIntegrationTest`.
25- After DTO, route, or schema changes, regenerate the UI client (`./gradlew generateOpenApiDocs && pnpm -C ui api-client:gen`) and update `ui/` usage.
26 
27## Boundaries
28 
29- Ask before adding database migrations, changing security configuration, or introducing new dependencies.
30 
31