chpr2011/incident-service

1. This repository is a single Spring Boot service, not a distributed system. The core runtime is Java 21 + Spring Boot 3.3.x, with Spring MVC, Spring Data JPA, Flyway, and H2 for local/test runs or PostgreSQL 16 in the Docker “prod” profile.

2. The architecture is intentionally layered around the com.everbridge.incident package:

- web exposes REST endpoints and DTOs

- application contains orchestration/business use cases

- domain holds the pure incident model and status rules

- infrastructure contains JPA repositories and event listeners

- common provides cross-cutting request/error handling

3. The main HTTP entrypoint is IncidentController. It handles:

- POST /incidents for intake with idempotency

- GET /incidents/{id} for an incident plus history

- GET /incidents for filtered/paginated search

- PATCH /incidents/{id}/status for lifecycle transitions

- GET /incidents/{id}/history for the audit trail

4. Request flow is conventional layered MVC: controller → IncidentService → domain rules → repositories. The controller only maps request/response shapes; it does not own business logic. Mapping between entity and API DTOs is isolated in web/mapper/IncidentMapper using MapStruct.

5. The domain layer is the main business boundary. Incident, IncidentStatus, Severity, IncidentHistory, and StatusTransitionRules model the lifecycle rules and immutable audit semantics. Invalid state changes are rejected in the domain/application flow, not in the controller.

6. Persistence is handled through Spring Data JPA repositories in infrastructure/repository. IncidentRepository supports id lookup and idempotent lookup by externalReferenceId; IncidentSpecifications provides composable filters for list queries. Hibernate optimistic locking via @Version is used to prevent lost updates and surface conflicts as 409s.

7. Audit recording is decoupled from the main write path using domain events. Status changes publish IncidentStatusChangedEvent, and IncidentHistoryListener persists append-only entries into incident_history. This keeps audit history authoritative and chronologically ordered without mixing it into controller code.

8. Cross-cutting request concerns live in common:

- CorrelationIdFilter propagates or creates X-Correlation-Id

- GlobalExceptionHandler converts errors into RFC 7807 ProblemDetail responses

- custom exceptions represent not-found, invalid transition, and related business failures

9. Schema management is migration-based, not entity-auto-generated. Flyway scripts under src/main/resources/db/migration create incidents and incident_history, and the application explicitly disables ddl-auto. That makes the schema an explicit deployment boundary.

10. Observability is first-class and split across logs, metrics, and dashboards:

- structured JSON logging via logback-spring.xml

- Micrometer + Prometheus at /actuator/prometheus

- Docker observability stack with Prometheus, Grafana, Loki, and Promtail

- correlation IDs appear in logs and API error responses for traceability

11. Environment configuration is profile-driven. application.yml, application-dev.yml, and application-docker.yml switch between H2/local settings and Docker/PostgreSQL settings. The repo includes separate compose files for dev and prod, plus provisioning for Grafana datasources and dashboards.

12. The project is test-heavy and mirrors the production layers:

- pure domain tests for transition rules

- service unit tests with Mockito

- repository tests with JPA/H2

- WebMvc slice tests for controller + error handling

- full integration tests with Spring Boot and real migrations

This maps well to the architecture because each boundary is tested in isolation before the full stack.

13. The important diagram boundaries are: external HTTP clients, the web/API layer, the application service layer, the domain model, the persistence/event infrastructure, and the database. Around that core sit cross-cutting concerns for correlation IDs, error translation, logging, metrics, and environment-specific deployment via Docker Compose.