# manuelmaslonka/error-utils architecture

> Architecture diagram of the GitHub repository manuelmaslonka/error-utils, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manuelmaslonka/error-utils
- Repository: https://github.com/manuelmaslonka/error-utils

## Overview

Error Utils is a reusable Java library for standardizing API errors across Spring Boot services, with a separate Spring-free validation pipeline. The main response flow maps request or domain failures through MVC handlers and a web factory into a shared error payload; validation can also produce results or business exceptions. The README documents starter auto-configuration and OpenAPI customization. The tree includes no separate OpenAPI module, so that capability is represented only by the starter customizer. Some links are omitted because the relevant implementations were not sampled.

Main entry points: [`error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/pipeline/ValidationChain.java`](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/pipeline/ValidationChain.java) (Validation chain), [`error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/ApiErrorFactory.java`](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/ApiErrorFactory.java) (API error factory), [`error-utils-spring-boot-starter/src/main/java/com/maslonka/reservation/errorutils/spring/boot/autoconfigure/ErrorUtilsAutoConfiguration.java`](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-boot-starter/src/main/java/com/maslonka/reservation/errorutils/spring/boot/autoconfigure/ErrorUtilsAutoConfiguration.java) (Auto-configuration), [`error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/advice/GlobalApiExceptionHandler.java`](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/advice/GlobalApiExceptionHandler.java) (MVC exception handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core error contract"]
  node_business["Business exceptions"]
  node_contract["Error contract<br/>[ApiError.java]"]
  node_assembler["Error assembler"]
end

subgraph group_validation["Validation pipeline"]
  node_validator["Validation API<br/>[Validator.java]"]
  node_steps["Validation steps"]
  node_chain["Validation chain"]
  node_failures["Failure model"]
  node_result["Validation result"]
end

subgraph group_web["Web response handling"]
  node_mvc["MVC exception handler"]
  node_factory["API error factory"]
  node_webfactory["Web error factory"]
  node_trace["Trace resolver"]
  node_securityhandlers["Security handlers"]
  node_jsonhandlers["JSON security handlers"]
end

subgraph group_integration["Spring integration"]
  node_starter["Auto-configuration"]
  node_openapi["OpenAPI customizer"]
end

node_service(("Service code"))
node_http(("HTTP request"))
node_security(("Spring Security"))
node_springdoc(("springdoc"))

node_service -->|"starts validation"| node_validator
node_validator -->|"creates chain"| node_chain
node_chain -->|"runs checks"| node_steps
node_steps -->|"records failures"| node_chain
node_chain -->|"collects"| node_failures
node_chain -->|"builds result"| node_result
node_chain -->|"throws on failure"| node_business
node_business -->|"raised to"| node_service
node_http -->|"raises request errors"| node_mvc
node_business -->|"handled by"| node_mvc
node_mvc -->|"builds response via"| node_factory
node_security -.->|"raises security errors"| node_securityhandlers
node_security -.->|"dispatches failures"| node_jsonhandlers
node_securityhandlers -.->|"builds response via"| node_factory
node_jsonhandlers -.->|"builds response via"| node_factory
node_factory -->|"delegates to"| node_webfactory
node_webfactory -->|"resolves identifiers"| node_trace
node_webfactory -->|"assembles payload"| node_assembler
node_assembler -->|"creates"| node_contract
node_starter -->|"registers"| node_factory
node_starter -->|"registers"| node_mvc
node_starter -->|"registers"| node_trace
node_starter -.->|"registers optionally"| node_openapi
node_openapi -.->|"customizes schema"| node_springdoc

click node_business "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-core/src/main/java/com/maslonka/reservation/errorutils/core/exception/BusinessException.java"
click node_contract "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-core/src/main/java/com/maslonka/reservation/errorutils/core/api/ApiError.java"
click node_assembler "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-core/src/main/java/com/maslonka/reservation/errorutils/core/api/ApiErrorAssembler.java"
click node_validator "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/api/Validator.java"
click node_steps "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/api/ValidationStep.java"
click node_chain "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/pipeline/ValidationChain.java"
click node_failures "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/model/ValidationFailure.java"
click node_result "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/model/ValidationResult.java"
click node_mvc "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/advice/GlobalApiExceptionHandler.java"
click node_factory "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/ApiErrorFactory.java"
click node_webfactory "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/factory/WebApiErrorFactory.java"
click node_trace "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/trace/DefaultTraceContextResolver.java"
click node_securityhandlers "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/security/GlobalSecurityExceptionHandler.java"
click node_jsonhandlers "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/security/JsonAuthenticationEntryPoint.java"
click node_starter "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-boot-starter/src/main/java/com/maslonka/reservation/errorutils/spring/boot/autoconfigure/ErrorUtilsAutoConfiguration.java"
click node_openapi "https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-boot-starter/src/main/java/com/maslonka/reservation/errorutils/spring/boot/autoconfigure/ErrorUtilsOpenApiCustomizer.java"

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_business,node_contract,node_assembler toneBlue
class node_validator,node_steps,node_chain,node_failures,node_result toneAmber
class node_mvc,node_factory,node_webfactory,node_trace,node_securityhandlers,node_jsonhandlers,node_http toneMint
class node_starter,node_openapi toneRose
class node_service,node_security,node_springdoc toneIndigo
```

## Components

### Core error contract

- [Business exceptions](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-core/src/main/java/com/maslonka/reservation/errorutils/core/exception/BusinessException.java): `error-utils-core/src/main/java/com/maslonka/reservation/errorutils/core/exception/BusinessException.java`
- [Error contract](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-core/src/main/java/com/maslonka/reservation/errorutils/core/api/ApiError.java): `error-utils-core/src/main/java/com/maslonka/reservation/errorutils/core/api/ApiError.java`
- [Error assembler](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-core/src/main/java/com/maslonka/reservation/errorutils/core/api/ApiErrorAssembler.java): `error-utils-core/src/main/java/com/maslonka/reservation/errorutils/core/api/ApiErrorAssembler.java`

### Validation pipeline

- [Validation API](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/api/Validator.java): `error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/api/Validator.java`
- [Validation steps](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/api/ValidationStep.java): `error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/api/ValidationStep.java`
- [Validation chain](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/pipeline/ValidationChain.java): `error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/pipeline/ValidationChain.java`
- [Failure model](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/model/ValidationFailure.java): `error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/model/ValidationFailure.java`
- [Validation result](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/model/ValidationResult.java): `error-utils-validation/src/main/java/com/maslonka/reservation/errorutils/validation/model/ValidationResult.java`

### Web response handling

- [MVC exception handler](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/advice/GlobalApiExceptionHandler.java): `error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/advice/GlobalApiExceptionHandler.java`
- [API error factory](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/ApiErrorFactory.java): `error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/ApiErrorFactory.java`
- [Web error factory](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/factory/WebApiErrorFactory.java): `error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/factory/WebApiErrorFactory.java`
- [Trace resolver](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/trace/DefaultTraceContextResolver.java): `error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/trace/DefaultTraceContextResolver.java`
- [Security handlers](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/security/GlobalSecurityExceptionHandler.java): `error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/security/GlobalSecurityExceptionHandler.java`
- [JSON security handlers](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/security/JsonAuthenticationEntryPoint.java): `error-utils-spring-webmvc/src/main/java/com/maslonka/reservation/errorutils/spring/web/security/JsonAuthenticationEntryPoint.java`

### Spring integration

- [Auto-configuration](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-boot-starter/src/main/java/com/maslonka/reservation/errorutils/spring/boot/autoconfigure/ErrorUtilsAutoConfiguration.java): `error-utils-spring-boot-starter/src/main/java/com/maslonka/reservation/errorutils/spring/boot/autoconfigure/ErrorUtilsAutoConfiguration.java`
- [OpenAPI customizer](https://github.com/manuelmaslonka/error-utils/blob/master/error-utils-spring-boot-starter/src/main/java/com/maslonka/reservation/errorutils/spring/boot/autoconfigure/ErrorUtilsOpenApiCustomizer.java): `error-utils-spring-boot-starter/src/main/java/com/maslonka/reservation/errorutils/spring/boot/autoconfigure/ErrorUtilsOpenApiCustomizer.java`

### Other components

- **Service code**
- **HTTP request**
- **Spring Security**
- **springdoc**

## Connections

- Service code → Validation API: starts validation
- Validation API → Validation chain: creates chain
- Validation chain → Validation steps: runs checks
- Validation steps → Validation chain: records failures
- Validation chain → Failure model: collects
- Validation chain → Validation result: builds result
- Validation chain → Business exceptions: throws on failure
- Business exceptions → Service code: raised to
- HTTP request → MVC exception handler: raises request errors
- Business exceptions → MVC exception handler: handled by
- MVC exception handler → API error factory: builds response via
- Spring Security → Security handlers: raises security errors
- Spring Security → JSON security handlers: dispatches failures
- Security handlers → API error factory: builds response via
- JSON security handlers → API error factory: builds response via
- API error factory → Web error factory: delegates to
- Web error factory → Trace resolver: resolves identifiers
- Web error factory → Error assembler: assembles payload
- Error assembler → Error contract: creates
- Auto-configuration → API error factory: registers
- Auto-configuration → MVC exception handler: registers
- Auto-configuration → Trace resolver: registers
- Auto-configuration → OpenAPI customizer: registers optionally
- OpenAPI customizer → springdoc: customizes schema