# afghaleek/problem-mapper-spring-boot-starter architecture

> Architecture diagram of the GitHub repository afghaleek/problem-mapper-spring-boot-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/afghaleek/problem-mapper-spring-boot-starter
- Repository: https://github.com/afghaleek/problem-mapper-spring-boot-starter

## Overview

#### Purpose and Integration

This repository is a Java 17 / Spring Boot 3.x starter that converts application exceptions into RFC-style Spring `ProblemDetail` HTTP responses. It is a library, not a standalone application: Spring Boot discovers and activates it through `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`.

The consumer-facing entry point is the `@ResponseError` annotation at `src/main/java/io/github/daoud/problemapper/annotation/ResponseError.java`, applied to exception classes.

#### Auto-Configuration Boundary

`src/main/java/io/github/daoud/problemapper/autoconfigure/ProblemMapperAutoConfiguration.java` is the composition root. It registers the starter’s runtime beans when present on a consuming Spring Boot application's classpath and binds configurable behavior through `src/main/java/io/github/daoud/problemapper/properties/ProblemMapperProperties.java`.

This is the principal boundary between consumer application code and the starter: applications supply exceptions, configuration properties, and HTTP requests; the starter supplies exception translation.

#### Exception Metadata Stage

`src/main/java/io/github/daoud/problemapper/annotation/ResponseError.java` declares static response metadata on exception types: HTTP status, application error code, and default message.

At runtime, the mapper inspects the thrown exception’s class for this annotation. The exception instance message can provide dynamic detail, while the annotation provides a stable API-level error classification.

#### Global HTTP Exception Interception

`src/main/java/io/github/daoud/problemapper/handler/ResponseErrorExceptionHandler.java` is the global Spring MVC exception-handling layer. It receives exceptions escaping REST controller execution, determines whether they carry `@ResponseError`, and delegates response construction.

It also provides the fallback path for unannotated or otherwise unmapped exceptions, preventing callers from needing their own repetitive `@ControllerAdvice` mappings.

#### ProblemDetail Construction

`src/main/java/io/github/daoud/problemapper/factory/ProblemDetailFactory.java` centralizes creation of Spring’s `ProblemDetail` response body. It combines exception metadata, request context, and configured options into a consistent payload.

Expected output includes standard `ProblemDetail` fields such as status, title/detail, and instance/path, plus an application-specific `code` extension. This factory is the main response-shape boundary and should remain the sole owner of field-selection rules.

#### Configuration and Fallback Policy

`src/main/java/io/github/daoud/problemapper/properties/ProblemMapperProperties.java` represents the `problem-mapper.*` configuration surface. It controls enablement, inclusion of path, timestamp, and exception-class information, plus fallback code and message behavior.

The fallback policy is significant: annotated exceptions produce intentional client-facing errors; all others become a configured internal-error response rather than leaking implementation details by default.

#### Runtime, Packaging, and External Dependencies

The artifact is Maven-built via `pom.xml` and packaged as a Spring Boot starter JAR. Its material runtime dependency is Spring Boot/Spring MVC, especially Spring’s `ProblemDetail` API and auto-configuration mechanism. There are no databases, queues, remote APIs, or standalone infrastructure components in the repository.

The build output `target/problem-mapper-spring-boot-starter-0.0.1-SNAPSHOT.jar` confirms this is distributable library packaging; JitPack is the documented external distribution channel.

Main entry points: [`src/main/java/io/github/daoud/problemapper/handler/ResponseErrorExceptionHandler.java`](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/handler/ResponseErrorExceptionHandler.java) (ResponseErrorExceptionHandler), [`src/main/java/io/github/daoud/problemapper/properties/ProblemMapperProperties.java`](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/properties/ProblemMapperProperties.java) (ProblemMapperProperties), [`src/main/java/io/github/daoud/problemapper/factory/ProblemDetailFactory.java`](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/factory/ProblemDetailFactory.java) (ProblemDetailFactory), [`src/main/java/io/github/daoud/problemapper/autoconfigure/ProblemMapperAutoConfiguration.java`](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/autoconfigure/ProblemMapperAutoConfiguration.java) (ProblemMapperAutoConfiguration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_consumer["Consumer Application"]
  node_http_request["HTTP Request<br/>runtime input"]
  node_consumer_exceptions["Application Exceptions<br/>consumer code"]
  node_consumer_properties["problem-mapper.*<br/>configuration"]
end

subgraph group_starter["Problem Mapper Starter"]
  node_response_error["@ResponseError<br/>exception annotation<br/>[ResponseError.java]"]
  node_auto_imports["Auto-Configuration Imports<br/>Spring Boot metadata"]
  node_auto_configuration["ProblemMapperAutoConfiguration<br/>composition root"]
  node_properties["ProblemMapperProperties<br/>configuration model"]
  node_exception_handler["ResponseErrorExceptionHandler<br/>global MVC handler"]
  node_problem_factory["ProblemDetailFactory<br/>response factory"]
  node_problem_detail["ProblemDetail Response<br/>HTTP error payload"]
end

subgraph group_spring["Spring Boot / MVC"]
  node_spring_boot_mvc["Spring Boot / Spring MVC<br/>framework runtime"]
end

node_maven_build["Maven Build<br/>build system<br/>[pom.xml]"]
node_starter_jar["Starter JAR<br/>distributable artifact"]

node_consumer_exceptions -->|"annotate"| node_response_error
node_auto_imports -->|"discovers"| node_auto_configuration
node_spring_boot_mvc -->|"loads"| node_auto_imports
node_auto_configuration -->|"registers"| node_exception_handler
node_auto_configuration -->|"binds"| node_properties
node_consumer_properties -->|"configures"| node_properties
node_http_request -->|"handled by"| node_spring_boot_mvc
node_spring_boot_mvc -->|"routes escaped exceptions"| node_exception_handler
node_exception_handler -->|"inspects exception type"| node_response_error
node_exception_handler -->|"uses fallback policy"| node_properties
node_exception_handler -->|"delegates construction"| node_problem_factory
node_response_error -->|"supplies metadata"| node_problem_factory
node_properties -->|"supplies options"| node_problem_factory
node_problem_factory -->|"creates"| node_problem_detail
node_maven_build -->|"packages"| node_starter_jar
node_starter_jar -.->|"runs within"| node_spring_boot_mvc

click node_response_error "https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/annotation/ResponseError.java"
click node_auto_imports "https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports"
click node_auto_configuration "https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/autoconfigure/ProblemMapperAutoConfiguration.java"
click node_properties "https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/properties/ProblemMapperProperties.java"
click node_exception_handler "https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/handler/ResponseErrorExceptionHandler.java"
click node_problem_factory "https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/factory/ProblemDetailFactory.java"
click node_maven_build "https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/pom.xml"
click node_starter_jar "https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/target/problem-mapper-spring-boot-starter-0.0.1-SNAPSHOT.jar"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_http_request,node_consumer_exceptions,node_consumer_properties toneBlue
class node_response_error,node_auto_imports,node_auto_configuration,node_properties,node_exception_handler,node_problem_factory,node_problem_detail toneAmber
class node_spring_boot_mvc toneMint
class node_maven_build,node_starter_jar toneNeutral
```

## Components

### Consumer Application

Supplies requests, exceptions, and starter configuration.

- **HTTP Request**: runtime input
- **Application Exceptions**: consumer code · Exception classes may declare response metadata.
- **problem-mapper.***: configuration

### Problem Mapper Starter

Library runtime and response-construction pipeline.

- [@ResponseError](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/annotation/ResponseError.java): exception annotation · Declares status, error code, and default message. · `src/main/java/io/github/daoud/problemapper/annotation/ResponseError.java`
- [Auto-Configuration Imports](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports): Spring Boot metadata · Makes the starter discoverable by Spring Boot. · `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`
- [ProblemMapperAutoConfiguration](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/autoconfigure/ProblemMapperAutoConfiguration.java): composition root · Registers starter runtime beans in the consuming application. · `src/main/java/io/github/daoud/problemapper/autoconfigure/ProblemMapperAutoConfiguration.java`
- [ProblemMapperProperties](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/properties/ProblemMapperProperties.java): configuration model · Controls payload options and fallback policy. · `src/main/java/io/github/daoud/problemapper/properties/ProblemMapperProperties.java`
- [ResponseErrorExceptionHandler](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/handler/ResponseErrorExceptionHandler.java): global MVC handler · Intercepts escaping controller exceptions and selects annotated or fallback handling. · `src/main/java/io/github/daoud/problemapper/handler/ResponseErrorExceptionHandler.java`
- [ProblemDetailFactory](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/src/main/java/io/github/daoud/problemapper/factory/ProblemDetailFactory.java): response factory · Owns ProblemDetail field selection and code extension construction. · `src/main/java/io/github/daoud/problemapper/factory/ProblemDetailFactory.java`
- **ProblemDetail Response**: HTTP error payload · RFC-style response with standard fields and an application code.

### Spring Boot / MVC

Host framework APIs and startup discovery.

- **Spring Boot / Spring MVC**: framework runtime · Provides auto-configuration, MVC exception handling, and ProblemDetail.

### Other components

- [Maven Build](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/pom.xml): build system · `pom.xml`
- [Starter JAR](https://github.com/afghaleek/problem-mapper-spring-boot-starter/blob/main/target/problem-mapper-spring-boot-starter-0.0.1-SNAPSHOT.jar): distributable artifact · Packaged Spring Boot starter library. · `target/problem-mapper-spring-boot-starter-0.0.1-SNAPSHOT.jar`

## Connections

- Application Exceptions → @ResponseError: annotate
- Auto-Configuration Imports → ProblemMapperAutoConfiguration: discovers
- Spring Boot / Spring MVC → Auto-Configuration Imports: loads
- ProblemMapperAutoConfiguration → ResponseErrorExceptionHandler: registers
- ProblemMapperAutoConfiguration → ProblemMapperProperties: binds
- problem-mapper.* → ProblemMapperProperties: configures
- HTTP Request → Spring Boot / Spring MVC: handled by
- Spring Boot / Spring MVC → ResponseErrorExceptionHandler: routes escaped exceptions
- ResponseErrorExceptionHandler → @ResponseError: inspects exception type
- ResponseErrorExceptionHandler → ProblemMapperProperties: uses fallback policy
- ResponseErrorExceptionHandler → ProblemDetailFactory: delegates construction
- @ResponseError → ProblemDetailFactory: supplies metadata
- ProblemMapperProperties → ProblemDetailFactory: supplies options
- ProblemDetailFactory → ProblemDetail Response: creates
- Maven Build → Starter JAR: packages
- Starter JAR → Spring Boot / Spring MVC: runs within