MyAiConfiguration/shared/rules/java/references/architecture-and-apis.md

Java Architecture and APIs

Apply these rules when designing public APIs, service boundaries, or application structure.

• Give APIs explicit request, response, and error contracts. Validate external input at the boundary without scattering redundant checks through trusted internal code.
• Separate transport models, domain models, and persistence entities. Accept only fields callers may set and return only fields they may read.
• Authorize the specific resource and operation where data is accessed or changed. Preserve ownership and tenant scope across alternate paths and background work.
• Bound payloads, page sizes, query complexity, and operation cost. Use pagination or streaming for potentially large results.
• Keep domain decisions separate from transport, persistence, and framework wiring. Make dependencies explicit; use dependency injection for real lifecycle or substitution needs.
• Use small contracts at real boundaries. Avoid service locators.
• Preserve existing API and serialization behavior unless the task requires a change. Treat changes to nullability, ordering, exception types, and collection mutability as compatibility changes.