SIFAP backend conventions - Java service boundaries
These instructions apply to the workshop Java 21 and Spring Boot 3.3 compatibility baseline. They are
authoritative for controller, service, transaction, DTO, and error boundaries; approved requirements,
ADRs, and target-code conventions win for feature behavior.
Service and API boundaries
- Keep controllers thin: validate, authorize, map, delegate, and form the HTTP response.
- Put business invariants and transaction boundaries in application services.
- Expose DTOs, not persistence entities, across API boundaries.
- Use constructor injection and explicit package/module boundaries.
- Return
Optional<T> for absence-oriented repository lookups when useful; do not require every public
method to return Optional, and never use it as a parameter type.
Validation and errors
- Validate inputs at system boundaries and enforce domain invariants in the owning domain/application code.
- Use RFC 7807
ProblemDetail without stack traces, secrets, CPF, amounts, or internal implementation data.
- Use
/api/v1/{resource} only when the approved contract defines that resource and version.
- Keep auth failures distinct from validation, not-found, conflict, and internal errors.
Conventions
| Rule |
Rationale |
| Transactions belong to services |
Business operations own atomicity. |
| DTOs define API boundaries |
Persistence changes do not leak into contracts. |
| Constructor injection is required |
Dependencies stay explicit and testable. |
| Absence semantics are contextual |
Optional remains useful without becoming a universal return type. |
Do / Do Not
| Do |
Do not |
| Follow approved REQ-IDs and contracts |
Generate CRUD behavior without requirements |
| Preserve exact financial precision |
Use float or double for money |
| Return safe machine-readable errors |
Expose stack traces or sensitive values |
| Use nearby module conventions |
Introduce a new dependency without an ADR |
Checklist Before Opening a PR
1---2name: sifap-backend3description: Defines SIFAP Java 21 and Spring Boot 3.3 backend boundaries, validation, transactions, errors, and data exposure. Use when editing backend Java source.4---56<!-- Generated from harness/github-copilot/plugins/mainframe-natural-adabas/instructions/sifap-backend.instructions.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->78# SIFAP backend conventions - Java service boundaries910These instructions apply to the workshop Java 21 and Spring Boot 3.3 compatibility baseline. They are11authoritative for controller, service, transaction, DTO, and error boundaries; approved requirements,12ADRs, and target-code conventions win for feature behavior.1314## Service and API boundaries1516- Keep controllers thin: validate, authorize, map, delegate, and form the HTTP response.17- Put business invariants and transaction boundaries in application services.18- Expose DTOs, not persistence entities, across API boundaries.19- Use constructor injection and explicit package/module boundaries.20- Return `Optional<T>` for absence-oriented repository lookups when useful; do not require every public21 method to return `Optional`, and never use it as a parameter type.2223## Validation and errors2425- Validate inputs at system boundaries and enforce domain invariants in the owning domain/application code.26- Use RFC 7807 `ProblemDetail` without stack traces, secrets, CPF, amounts, or internal implementation data.27- Use `/api/v1/{resource}` only when the approved contract defines that resource and version.28- Keep auth failures distinct from validation, not-found, conflict, and internal errors.2930## Conventions3132| Rule | Rationale |33| --- | --- |34| Transactions belong to services | Business operations own atomicity. |35| DTOs define API boundaries | Persistence changes do not leak into contracts. |36| Constructor injection is required | Dependencies stay explicit and testable. |37| Absence semantics are contextual | `Optional` remains useful without becoming a universal return type. |3839## Do / Do Not4041| Do | Do not |42| --- | --- |43| Follow approved REQ-IDs and contracts | Generate CRUD behavior without requirements |44| Preserve exact financial precision | Use `float` or `double` for money |45| Return safe machine-readable errors | Expose stack traces or sensitive values |46| Use nearby module conventions | Introduce a new dependency without an ADR |4748## Checklist Before Opening a PR4950- [ ] The change maps to approved requirements and stays inside the owning module.51- [ ] Controllers, services, repositories, DTOs, and transaction boundaries are correctly separated.52- [ ] Validation, authorization, and error behavior cover positive and negative paths.53- [ ] Financial values preserve explicit precision and rounding semantics.54- [ ] Focused tests and the applicable build pass.55- [ ] No sensitive data, placeholder behavior, or unrelated dependency was introduced.
paulasilvatech