# Sifap Backend

> Defines SIFAP Java 21 and Spring Boot 3.3 backend boundaries, validation, transactions, errors, and data exposure. Use when editing backend Java source.

- Skill: `paulasilvatech/sifap-backend` (Agent Skill)
- Install (CLI): `npx skillmds@latest add paulasilvatech/sifap-backend`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paulasilvatech/sifap-backend/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: paulasilvatech (https://skillmd.com/u/paulasilvatech)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/paulasilvatech/sifap-backend

---


<!-- 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. -->

# 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

- [ ] The change maps to approved requirements and stays inside the owning module.
- [ ] Controllers, services, repositories, DTOs, and transaction boundaries are correctly separated.
- [ ] Validation, authorization, and error behavior cover positive and negative paths.
- [ ] Financial values preserve explicit precision and rounding semantics.
- [ ] Focused tests and the applicable build pass.
- [ ] No sensitive data, placeholder behavior, or unrelated dependency was introduced.