msgexchange-v2/AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization

Application code lives under `src/main/kotlin/com/gzzn/omms/msgexchange/`. Keep changes within the established modules: `ingress` receives mailbox records, `processing` owns FIFO decisions, `delivery` handles outbound events, `jobs` runs maintenance work, and `infra` contains persistence, health, and retry adapters (Redis has exited runtime authority per ACM2-28). Runtime configuration and Flyway migrations are in `src/main/resources/`. Tests mirror production packages under `src/test/kotlin/`. Architecture and requirements live in `docs/`; treat `docs/legacy/` as reference material, not current design. Local middleware definitions are in `compose.yaml` and `deploy/dev/`.

## Build, Test, and Development Commands

- `./gradlew build` — compile, test, and package the application.
- `./gradlew test` — run the JUnit 5 test suite.
- `MICRONAUT_ENVIRONMENTS=dev ./gradlew run` — start the stub-backed development profile without external services.
- `cp .env.example .env && docker compose up -d` — start local PostgreSQL, MySQL, Valkey, and Kafka.
- `docker compose ps` — verify middleware health.

Use JDK 25. In restricted environments, point `GRADLE_USER_HOME` and `TMPDIR` to writable directories.

## Coding Style & Naming Conventions

Use Kotlin conventions with four-space indentation, trailing commas in multiline declarations, and immutable values by default. Types use `PascalCase`; functions and properties use `camelCase`; constants use `UPPER_SNAKE_CASE`. Name tests after behavior, for example `MessageProcessorTest` and `InboxPollerTest`. Keep handlers pure: return domain decisions rather than performing Kafka or database writes directly. Preserve the single-writer and strict message FIFO invariants documented in `docs/architecture.md`.

## Testing Guidelines

Tests use JUnit 5, Micronaut Test, and Kotlin Test. Add focused tests beside the affected package. Changes to ordering, retry, identity, snapshot, or delivery behavior must include invariant-level regression tests. Prefer injected clocks and in-memory adapters over sleeps or live infrastructure. Run `./gradlew test` before submitting.

## Commit & Pull Request Guidelines

History follows Conventional Commit-style subjects such as `feat(ref): ...`, `fix(processing): ...`, and `docs: ...`; include the relevant Plane identifier when applicable. Keep commits scoped and avoid mixing unrelated refactors. Pull requests should explain behavior changes, affected invariants, configuration or migration impact, linked Plane work items, and verification performed. Include request/response examples for API changes; screenshots are only needed for visual documentation changes.

## Security & Configuration

Never commit credentials or production endpoints. Use environment variables documented in `.env.example`. Shared MySQL is an external mailbox boundary: do not add schema migrations or unapproved tables there.