2.9 KiB
Repository Guidelines
Project Structure & Module Organization
The server is a Kotlin/Ktor app. Bootstrap code (Application.kt, Routing.kt, Security.kt, Serialization.kt) lives in src/main/kotlin/app. Business features sit inside src/main/kotlin/modules/<domain> and follow the repeating Controller → Service → Repository → Entity flow, reusing utilities from src/main/kotlin/shared. Configuration (application.yaml, logback.xml) and OpenAPI specs (resources/openapi) live in src/main/resources. Tests mirror the production tree under src/test/kotlin (see ApplicationTest.kt for the pattern). Generated artifacts stay inside build/.
Build, Test, and Development Commands
./gradlew run— start the server for local iteration../gradlew test— run the full unit/integration suite; required before every push../gradlew build— compile sources, execute tests, and assemble deployable jars../gradlew buildFatJar— emitbuild/libs/*-all.jarfor standalone deployment../gradlew buildImage/publishImageToLocalRegistry/runDocker— build, publish, and exercise the Docker image for parity checks.
Coding Style & Naming Conventions
Stick to Kotlin defaults: four-space indentation, braces on the same line, camelCase members, PascalCase types, lowercase packages. Keep controllers focused on HTTP + validation, services on business rules, and repositories on persistence. Prefer immutable DTOs/data classes, throw the shared exceptions instead of string literals, and wire routes declaratively inside app/Routing.kt. Name files after the primary type (NewsController, LeadService) for clarity.
Testing Guidelines
Tests rely on the Ktor test engine and should shadow the production package path (e.g., modules/news/ControllerTest). Name tests with behavior phrases such as shouldReturn401WhenTokenMissing, covering success, validation, and authorization branches. Every feature or bug fix must ship with tests plus a local ./gradlew test run; target coverage on every public service method.
Commit & Pull Request Guidelines
Use short, imperative commit subjects consistent with history (Init commit, Diploma-1 Main CRUD operations). Reference tickets when relevant (Diploma-42 Add news search) and keep each commit scoped to one concern. Pull requests need a summary, linked issues, API evidence (screenshots or curl output), and confirmation that ./gradlew test succeeded. Request review only after CI is green and OpenAPI docs reflect any contract changes.
Security & Configuration Tips
Secrets such as JWT keys or database URIs must come from environment variables or an untracked overlay—never hard-code them in application.yaml. When touching authentication, revisit Security.kt so routes opt into the correct provider. Update resources/openapi/documentation.yaml whenever request/response schemas evolve so downstream clients stay synchronized.