2.9 KiB
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, Redis, health, and retry adapters. Runtime configuration, Flyway migrations, and Lua scripts 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 Redis, 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.