|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Project Structure & Module Organization |
| 4 | +- Root `pom.xml` defines the single Maven module built against Java 21 and Vert.x 5.0.x. |
| 5 | +- Gateway entry points live in `src/main/java/com/inqwise/opinion/gateway` (`ApiGatewayLauncher`, `ApiGatewayVerticle`, `GatewayConfig`). |
| 6 | +- Shared async stream adapters for bridging blocking I/O reside under `src/main/java/com/inqwise/async/stream`. |
| 7 | +- Tests mirror the main packages inside `src/test/java`, using the same package names for coverage and clarity. |
| 8 | +- Optional runtime configuration is read from `config/application.json` or environment variables during startup. |
| 9 | + |
| 10 | +## Build, Test, and Development Commands |
| 11 | +- `mvn clean package` — compiles sources, runs the full test suite, and produces the shaded JAR in `target/`. |
| 12 | +- `mvn test` — executes unit tests with JUnit 5 and Vert.x JUnit extensions without creating artifacts. |
| 13 | +- `java -cp target/inqwise-async-1.1.2-SNAPSHOT.jar com.inqwise.opinion.gateway.ApiGatewayLauncher` — launches the gateway locally after packaging; override ports with `HTTP_PORT=9090` or supply `config/application.json`. |
| 14 | + |
| 15 | +## Coding Style & Naming Conventions |
| 16 | +- Use four-space indentation, braces on the same line as declarations, and favor `final` for dependencies injected via constructors. |
| 17 | +- Follow standard Java naming (`PascalCase` classes, `camelCase` members, `UPPER_SNAKE_CASE` constants) and align imports per IntelliJ/Spotless defaults. |
| 18 | +- Maintain the existing pattern of small, focused verticles and prefer Vert.x `Future`/`Promise` APIs for async flows. |
| 19 | + |
| 20 | +## Testing Guidelines |
| 21 | +- Write tests with JUnit 5 (`@ExtendWith(VertxExtension.class)`) and Vert.x test utilities; name files with the `*Test` suffix. |
| 22 | +- Use `VertxTestContext` and `Async` helpers to avoid blocking the event loop. |
| 23 | +- The project tracks coverage via JaCoCo/Codecov; strive to keep or raise coverage when modifying gateway logic. |
| 24 | + |
| 25 | +## Commit & Pull Request Guidelines |
| 26 | +- Follow the existing Conventional Commit style (`fix:`, `chore:`, `deps(deps):`, `ci(deps):`, etc.) for clear history and automated release notes. |
| 27 | +- Reference issues in the body when applicable, describe functional changes, and list validation steps (e.g., commands run, configs used). |
| 28 | +- For gateway changes, include samples of affected endpoints or configuration knobs so reviewers can reproduce locally. |
| 29 | + |
| 30 | +## Security & Configuration Tips |
| 31 | +- Do not commit secrets; prefer environment variables for credentials and mark optional values in `config/application.json`. |
| 32 | +- Tighten upstream calls by keeping hop-by-hop headers filtered and reusing the shared `WebClient` options as shown in the verticle. |
| 33 | +- When adding new endpoints, ensure health probes (`/health/live`, `/health/ready`) remain lightweight and under existing timeout budgets. |
0 commit comments