MANOHAR.

PROJECT / 003

IncidentHub

Enterprise incident lifecycle REST API.

JavaSpring BootSpring Data JPAPostgreSQLFlywayJUnitMockitoMockMvc

TYPE

Backend application

STATUS

Functional

01 / THE PROBLEM

The engineering problem

Enterprise APIs frequently suffer from fragmented error handling, resulting in inconsistent HTTP response structures that break client integrations, complicate debugging, and leak internal stack traces. Incident management requires strict, predictable state transitions and layered architectural separation.

CONSTRAINTS

Fragmented error responses

Arbitrary state mutations

Uncontrolled schema drift

ENGINEERING FOCUS

Centralized @ControllerAdvice handler

Enforced lifecycle state transitions

Versioned Flyway database migrations

02 / ARCHITECTURE

How the system works

INCIDENTHUB / ARCHITECTURE & STATE MACHINE — CURRENT STATE: NEW

REST ClientJSON / HTTPHTTPIncidentController@RestController@Valid validation@ControllerAdviceRFC 7807 ErrorsDTOIncidentServiceState Machine RulesState: NEWEntityIncidentRepositorySpring Data JPAHibernate ORMPostgreSQL+ Flyway migrationsLIFECYCLE PIPELINE:[NEW]→[INVESTIGATING]→[RESOLVED]→[CLOSED]

Current lifecycle status: NEW. Controller validates inputs, service layer checks transition legality, and Spring Data JPA persists state with automated Flyway versioned migrations.

03 / IMPLEMENTATION

What was built

  • 01Engineered an incident lifecycle REST API using Java 17 and Spring Boot 3.
  • 02Enforced strict architectural boundaries: decoupled web controllers from service-layer business rules.
  • 03Implemented deterministic status transition logic (NEW → INVESTIGATING → RESOLVED → CLOSED).
  • 04Created centralized global exception handling via @ControllerAdvice producing uniform RFC 7807 error responses.
  • 05Managed PostgreSQL schema evolution using versioned, auditable Flyway migrations.
  • 06Built automated testing suites combining unit tests with Mockito and web-layer integration tests with MockMvc.

04 / DECISIONS

Technical decisions

DECISIONREASONING
Spring Boot ecosystemStandard enterprise backend platform; demonstrates proficiency with Java dependency injection and ORM.
Centralized @ControllerAdviceStandardizes error response schemas across the entire API and sanitizes internal exception messages.
Explicit state transition machinePrevents illegal mutations (e.g. CLOSED back to NEW without re-opening workflow).
Flyway versioned migrationsEliminates manual database schema changes and provides automated verification on application boot.

05 / RELIABILITY

Reliability and failure handling

SCENARIOEXPECTED BEHAVIOURVERIFICATION
Client requests invalid status transitionService rejects transition; returns 422 Unprocessable Entity with allowed target states.Service unit test with Mockito
Resource ID does not existReturns uniform 404 Not Found JSON object matching the standard API error contract.MockMvc integration test
Request body fails validation constraintsMethodArgumentNotValidException caught; returns 400 with specific field-level error messages.Controller validation test

06 / LIMITATIONS

Known limitations and future work

—Role-Based Access Control (RBAC) via Spring Security is currently in planning.
—Audit event publishing via Kafka or Spring ApplicationEvent is not yet integrated.
—Cursor-based pagination for large incident catalogs is planned for next iteration.

Java backend architecture, Spring Boot conventions, REST API design, exception sanitization, and automated test-driven verification.

← PREVIOUS

FlowForge

All projects

NEXT →

KAGE