Platform contracts
Runtime, identifiers, time, errors, OpenAPI, observability, scheduling, and delivery gates.
Runtime
SmartGare ships one Spring Boot application. The root container build compiles
product/apps/server and its dependencies on Java 25, extracts Spring Boot
layers, and runs as a non-root user.
| Contract | Guarantee |
|---|---|
| Module detection | Explicit Spring Modulith modules; cycles rejected |
| Database configuration | Spring datasource properties or portable DATABASE_URL |
| Migrations | One schema and Flyway location per module |
| Scheduling | Every scheduled method carries a named distributed lock |
| API discovery | OpenAPI at /v3/api-docs; Swagger UI at /swagger-ui.html |
| Readiness | Includes whether this deployment manages a station |
Identifiers and time
- Aggregate IDs are typed records implementing
Identifier. - IDs serialize as flat text and are minted centrally in sortable order.
- Business modules never handle
UUIDdirectly. - Domain timestamps use PostgreSQL-compatible microsecond precision.
- A LIKE-escaping helper requires an explicit SQL escape character.
Error model
| Status | Contract |
|---|---|
400 | Malformed request or unreadable input |
401 | Missing or invalid authentication |
403 | Authenticated but unauthorized |
404 | Aggregate or referenced catalog record does not exist |
409 | Duplicate, wrong state, stale write, overlap, or lost race |
422 | Field or domain constraint is invalid |
500 | Unexpected failure without internal-type disclosure |
Validation and conflict responses may carry a structured errors map.
Framework exception messages and stack traces never reach callers.
OpenAPI
The web platform derives shared responses from runtime facts, carries controlled values from the validator into schemas and query parameters, and hides argument-resolver supplied types. Controller integration tests assert the generated document.
Observability and scheduling
Request correlation propagates through logs and event envelopes. @Traced
records execution duration and outcome while values remain silent unless they
explicitly opt into safe logging.
Scheduled work uses PostgreSQL time through ShedLock. Domain-level durable dedup still protects irreversible announcements if a job outlives its lock.
Delivery gates
- Spotless formats Java, POM, YAML, JSON, and Markdown.
- JSpecify and NullAway make nullness build-failing.
- Testcontainers exercises PostgreSQL, Kafka, and Redis-compatible services.
- Conventional Commits drive semantic release.
- Production changes move living shipped/backlog documentation.