# Repository Guidelines

## Project Structure & Module Organization
- Spring Boot 3 (Java 17) Maven app.
- Key paths:
  - `src/main/java` — root package `com.mosquito.project` (modules: `controller`, `service`, `domain`, `dto`, `job`, `exception`).
  - `src/main/resources` — app config (`application.properties`), Flyway migrations in `db/migration`.
  - `src/test/java` — JUnit 5 tests mirroring `main` packages.
  - `docs/`, `specs/` — documentation and specifications.
  - `target/` — build outputs (generated).

## Build, Test, and Development Commands
- Build: `mvn clean package` — compile, test, and create JAR in `target/`.
- Run (dev): `mvn spring-boot:run` — start app with live reload of resources.
- Run (JAR): `java -jar target/mosquito-0.0.1-SNAPSHOT.jar`.
- Test all: `mvn test`.
- Test one: `mvn -Dtest=ActivityServiceTest test`.
- Verify: `mvn verify` — full lifecycle checks.

## Coding Style & Naming Conventions
- Java 17; 4-space indentation; one class per file; braces on same line.
- Packages: lowercase under `com.mosquito.project`.
- Classes: `PascalCase`; methods/fields: `camelCase`; constants: `UPPER_SNAKE_CASE`.
- DTOs end with `Request`/`Response`; exceptions end with `Exception`.
- Use Lombok where present (e.g., `@Getter`, `@Builder`); avoid wildcard imports.
- Validate inputs with Bean Validation annotations (e.g., `@NotNull`, `@Size`).

## Testing Guidelines
- Frameworks: JUnit 5, Spring Boot Test, WebMvcTest/MockMvc; H2 and Embedded Redis for tests; Testcontainers available when needed.
- Location: `src/test/java` with names `*Test.java`; mirror package of code under test.
- Conventions: method names like `shouldDoX_whenY()`; prefer fast slice tests for controllers, `@SpringBootTest` for integration.
- Run: `mvn test` or a focused run via `-Dtest=...`.

## Commit & Pull Request Guidelines
- Use Conventional Commits: `feat|fix|docs|test|refactor|chore(scope): message`.
- Example: `feat(activity): add graph endpoint with validation`.
- PRs: include purpose, linked issues, API examples or reproduction steps, updated tests/docs, and ensure `mvn -q verify` passes.

## Security & Configuration Tips
- App config in `src/main/resources/application.properties` (e.g., `spring.redis.host/port`); DB via `SPRING_DATASOURCE_*` env vars.
- Never commit secrets; prefer environment variables or an untracked `application-local.properties`.
- Database schema changes go through Flyway migrations in `src/main/resources/db/migration`.

## Agent-Specific Notes
- Keep changes minimal and localized; match the existing package layout.
- Avoid introducing new dependencies without discussion; update tests and docs with behavior changes.