# Repository Guidelines

## Project Structure & Module Organization
- `src/main/java/de/tamse/imageconverter` contains production code with `ImageConverterApplication` as the entry point.
- `src/main/resources` stores configuration and static assets; defaults live in `application.properties`.
- `src/test/java` mirrors the production package tree for JUnit 5 coverage.
- `prd/` holds product-facing documentation; `target/` is disposable build output.

## Build, Test, and Development Commands
- `./mvnw clean package` compiles, runs tests, and produces an executable JAR under `target/`.
- `./mvnw test` executes the unit and integration test suite without packaging.
- `./mvnw spring-boot:run` starts the application for local development; stop with `Ctrl+C`.
- Ensure Java 17 is configured in your IDE and `$JAVA_HOME` before invoking the wrapper.

## Coding Style & Naming Conventions
- Adopt Spring conventions: classes in PascalCase, methods and fields in camelCase, constants in UPPER_SNAKE.
- Indent with four spaces, let your IDE organise imports, and avoid trailing whitespace.
- Group new components under `de.tamse.imageconverter.<feature>` with descriptive names (e.g., `PngToJpegConverter`).
- Prefer constructor injection for Spring beans and commit only formatted code.

## Testing Guidelines
- Use JUnit 5; name test classes with the `*Tests` suffix and match package paths.
- Limit `@SpringBootTest` to scenarios needing the full application context; favour slice or unit tests otherwise.
- Run `./mvnw test` before pushing to catch regressions locally.
- Expand coverage around new converters, validators, or data flows you introduce.

## Commit & Pull Request Guidelines
- Follow Conventional Commits (e.g., `feat: add png conversion pipeline`) to keep history searchable.
- Write imperative subject lines and mention affected modules when helpful.
- Pull requests should include a concise summary, linked issues, and manual verification notes.
- Attach screenshots or sample payloads when changes affect user-visible behaviour or external APIs.

## Configuration Tips
- Keep shared defaults in `application.properties`; never commit secrets or API keys.
- Add environment overrides via `application-<profile>.properties` and document activation (`--spring.profiles.active=dev`).
- Prefer environment variables or external vaults for sensitive values and note required secrets in PR checklists.