# benhendayoussef/idempotency-spring-boot-starter architecture

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

- Interactive diagram: https://gitdiagram.com/benhendayoussef/idempotency-spring-boot-starter
- Repository: https://github.com/benhendayoussef/idempotency-spring-boot-starter
- Video tour (about a minute): https://gitdiagram.com/benhendayoussef/idempotency-spring-boot-starter/video

## Overview

This is a Spring Boot idempotency library: it protects annotated or filter-mode HTTP handlers from duplicate execution, replaying a stored response for repeated keys. The principal flow claims a scoped, request-fingerprinted key, invokes the handler only for the claim winner, then stores its response or releases the claim according to the outcome. The graph also shows alternate persistence, reactive support, configuration, and operational inspection. Core aspect, store-selection, and reactive implementation details are inferred from documented capabilities and the file tree; their source was not sampled.

Main entry points: [`idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/IdempotencyAspect.java`](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/IdempotencyAspect.java) (Idempotency aspect), [`idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/api/IdempotencyStore.java`](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/api/IdempotencyStore.java) (Store interface), [`idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/filter/IdempotencyFilter.java`](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/filter/IdempotencyFilter.java) (Servlet filter mode), [`idempotency-spring-boot-starter/src/main/java/io/github/benhendayoussef/idempotency/autoconfigure/IdempotencyAutoConfiguration.java`](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-spring-boot-starter/src/main/java/io/github/benhendayoussef/idempotency/autoconfigure/IdempotencyAutoConfiguration.java) (Boot auto-configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request handling"]
  node_aspect["Idempotency aspect"]
  node_filter["Servlet filter mode"]
  node_capture["Response capture"]
  node_webfluxcontext["Exchange context filter"]
  node_reactive["Reactive aspect"]
end

subgraph group_core["Idempotency core"]
  node_fingerprint["Argument fingerprint"]
  node_key["Key composition"]
  node_scope["Scope resolution"]
  node_storeapi["Store interface"]
end

subgraph group_stores["Persistence"]
  node_memory[("Memory store")]
  node_caffeine[("Caffeine store")]
  node_jdbc[("JDBC store")]
  node_redis[("Redis store")]
end

subgraph group_integration["Spring integration"]
  node_properties["Idempotency settings"]
  node_autoconfig["Boot auto-configuration"]
  node_exception["Problem responses"]
end

subgraph group_operations["Operations"]
  node_endpoint["Management endpoint"]
  node_metrics["Metrics and tracing"]
  node_sweeper["JDBC record sweeper"]
end

node_client(("HTTP client"))
node_handler["Application handler"]
node_datastore[("Redis or SQL database")]

node_client -->|"sends request"| node_aspect
node_aspect -->|"fingerprints arguments"| node_fingerprint
node_aspect -->|"composes key"| node_key
node_aspect -->|"resolves namespace"| node_scope
node_aspect -->|"claims or reads"| node_storeapi
node_aspect -->|"invokes on claim"| node_handler
node_handler -->|"returns response"| node_aspect
node_aspect -->|"completes or releases"| node_storeapi
node_client -.->|"sends request"| node_filter
node_filter -.->|"composes key"| node_key
node_filter -.->|"claims or reads"| node_storeapi
node_filter -.->|"dispatches on claim"| node_handler
node_filter -.->|"captures response"| node_capture
node_filter -.->|"completes or releases"| node_storeapi
node_aspect -->|"reads settings"| node_properties
node_filter -.->|"reads settings"| node_properties
node_storeapi -.->|"implemented by"| node_memory
node_storeapi -.->|"implemented by"| node_caffeine
node_storeapi -.->|"implemented by"| node_jdbc
node_storeapi -.->|"implemented by"| node_redis
node_caffeine -->|"stores records"| node_datastore
node_jdbc -->|"stores records"| node_datastore
node_redis -->|"stores records"| node_datastore
node_webfluxcontext -->|"provides exchange context"| node_reactive
node_client -.->|"sends reactive request"| node_webfluxcontext
node_reactive -.->|"claims and replays"| node_storeapi
node_reactive -.->|"invokes on claim"| node_handler
node_autoconfig -->|"configures"| node_aspect
node_autoconfig -.->|"configures"| node_filter
node_autoconfig -->|"binds settings"| node_properties
node_exception -->|"returns problem response"| node_client
node_endpoint -->|"inspects or evicts"| node_storeapi
node_metrics -.->|"observes requests"| node_aspect
node_sweeper -->|"removes expired rows"| node_jdbc

click node_aspect "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/IdempotencyAspect.java"
click node_filter "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/filter/IdempotencyFilter.java"
click node_capture "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/filter/CapturedResponse.java"
click node_fingerprint "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/ArgumentFingerprinter.java"
click node_key "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/IdempotencyKeyComposer.java"
click node_scope "https://github.com/benhendayoussef/idempotency-spring-boot-starter/tree/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/scope"
click node_properties "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/config/IdempotencyProperties.java"
click node_storeapi "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/api/IdempotencyStore.java"
click node_memory "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/InMemoryIdempotencyStore.java"
click node_caffeine "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-store-caffeine/src/main/java/io/github/benhendayoussef/idempotency/store/caffeine/internal/CaffeineIdempotencyStore.java"
click node_jdbc "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-store-jdbc/src/main/java/io/github/benhendayoussef/idempotency/store/jdbc/internal/JdbcIdempotencyStore.java"
click node_redis "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-store-redis/src/main/java/io/github/benhendayoussef/idempotency/store/redis/internal/RedisIdempotencyStore.java"
click node_webfluxcontext "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-webflux/src/main/java/io/github/benhendayoussef/idempotency/webflux/internal/IdempotencyExchangeContextFilter.java"
click node_reactive "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-webflux/src/main/java/io/github/benhendayoussef/idempotency/webflux/internal/ReactiveIdempotencyAspect.java"
click node_autoconfig "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-spring-boot-starter/src/main/java/io/github/benhendayoussef/idempotency/autoconfigure/IdempotencyAutoConfiguration.java"
click node_exception "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/IdempotencyExceptionHandler.java"
click node_endpoint "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-spring-boot-starter/src/main/java/io/github/benhendayoussef/idempotency/autoconfigure/IdempotencyEndpoint.java"
click node_metrics "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-spring-boot-starter/src/main/java/io/github/benhendayoussef/idempotency/autoconfigure/IdempotencyMetricsAutoConfiguration.java"
click node_sweeper "https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-store-jdbc/src/main/java/io/github/benhendayoussef/idempotency/store/jdbc/internal/IdempotencyRecordSweeper.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_aspect,node_filter,node_capture,node_webfluxcontext,node_reactive,node_client toneBlue
class node_fingerprint,node_key,node_scope,node_storeapi,node_datastore toneAmber
class node_memory,node_caffeine,node_jdbc,node_redis,node_handler toneMint
class node_properties,node_autoconfig,node_exception toneRose
class node_endpoint,node_metrics,node_sweeper toneIndigo
```

## Components

### Request handling

- [Idempotency aspect](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/IdempotencyAspect.java): `idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/IdempotencyAspect.java`
- [Servlet filter mode](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/filter/IdempotencyFilter.java): `idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/filter/IdempotencyFilter.java`
- [Response capture](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/filter/CapturedResponse.java): `idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/filter/CapturedResponse.java`
- [Exchange context filter](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-webflux/src/main/java/io/github/benhendayoussef/idempotency/webflux/internal/IdempotencyExchangeContextFilter.java): `idempotency-webflux/src/main/java/io/github/benhendayoussef/idempotency/webflux/internal/IdempotencyExchangeContextFilter.java`
- [Reactive aspect](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-webflux/src/main/java/io/github/benhendayoussef/idempotency/webflux/internal/ReactiveIdempotencyAspect.java): `idempotency-webflux/src/main/java/io/github/benhendayoussef/idempotency/webflux/internal/ReactiveIdempotencyAspect.java`

### Idempotency core

- [Argument fingerprint](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/ArgumentFingerprinter.java): `idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/ArgumentFingerprinter.java`
- [Key composition](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/IdempotencyKeyComposer.java): `idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/IdempotencyKeyComposer.java`
- [Scope resolution](https://github.com/benhendayoussef/idempotency-spring-boot-starter/tree/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/scope): `idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/scope`
- [Store interface](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/api/IdempotencyStore.java): `idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/api/IdempotencyStore.java`

### Persistence

- [Memory store](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/InMemoryIdempotencyStore.java): `idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/InMemoryIdempotencyStore.java`
- [Caffeine store](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-store-caffeine/src/main/java/io/github/benhendayoussef/idempotency/store/caffeine/internal/CaffeineIdempotencyStore.java): `idempotency-store-caffeine/src/main/java/io/github/benhendayoussef/idempotency/store/caffeine/internal/CaffeineIdempotencyStore.java`
- [JDBC store](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-store-jdbc/src/main/java/io/github/benhendayoussef/idempotency/store/jdbc/internal/JdbcIdempotencyStore.java): `idempotency-store-jdbc/src/main/java/io/github/benhendayoussef/idempotency/store/jdbc/internal/JdbcIdempotencyStore.java`
- [Redis store](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-store-redis/src/main/java/io/github/benhendayoussef/idempotency/store/redis/internal/RedisIdempotencyStore.java): `idempotency-store-redis/src/main/java/io/github/benhendayoussef/idempotency/store/redis/internal/RedisIdempotencyStore.java`

### Spring integration

- [Idempotency settings](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/config/IdempotencyProperties.java): `idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/config/IdempotencyProperties.java`
- [Boot auto-configuration](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-spring-boot-starter/src/main/java/io/github/benhendayoussef/idempotency/autoconfigure/IdempotencyAutoConfiguration.java): `idempotency-spring-boot-starter/src/main/java/io/github/benhendayoussef/idempotency/autoconfigure/IdempotencyAutoConfiguration.java`
- [Problem responses](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/IdempotencyExceptionHandler.java): `idempotency-core/src/main/java/io/github/benhendayoussef/idempotency/internal/IdempotencyExceptionHandler.java`

### Operations

- [Management endpoint](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-spring-boot-starter/src/main/java/io/github/benhendayoussef/idempotency/autoconfigure/IdempotencyEndpoint.java): `idempotency-spring-boot-starter/src/main/java/io/github/benhendayoussef/idempotency/autoconfigure/IdempotencyEndpoint.java`
- [Metrics and tracing](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-spring-boot-starter/src/main/java/io/github/benhendayoussef/idempotency/autoconfigure/IdempotencyMetricsAutoConfiguration.java): `idempotency-spring-boot-starter/src/main/java/io/github/benhendayoussef/idempotency/autoconfigure/IdempotencyMetricsAutoConfiguration.java`
- [JDBC record sweeper](https://github.com/benhendayoussef/idempotency-spring-boot-starter/blob/main/idempotency-store-jdbc/src/main/java/io/github/benhendayoussef/idempotency/store/jdbc/internal/IdempotencyRecordSweeper.java): `idempotency-store-jdbc/src/main/java/io/github/benhendayoussef/idempotency/store/jdbc/internal/IdempotencyRecordSweeper.java`

### Other components

- **HTTP client**
- **Application handler**
- **Redis or SQL database**

## Connections

- HTTP client → Idempotency aspect: sends request
- Idempotency aspect → Argument fingerprint: fingerprints arguments
- Idempotency aspect → Key composition: composes key
- Idempotency aspect → Scope resolution: resolves namespace
- Idempotency aspect → Store interface: claims or reads
- Idempotency aspect → Application handler: invokes on claim
- Application handler → Idempotency aspect: returns response
- Idempotency aspect → Store interface: completes or releases
- HTTP client → Servlet filter mode: sends request
- Servlet filter mode → Key composition: composes key
- Servlet filter mode → Store interface: claims or reads
- Servlet filter mode → Application handler: dispatches on claim
- Servlet filter mode → Response capture: captures response
- Servlet filter mode → Store interface: completes or releases
- Idempotency aspect → Idempotency settings: reads settings
- Servlet filter mode → Idempotency settings: reads settings
- Store interface → Memory store: implemented by
- Store interface → Caffeine store: implemented by
- Store interface → JDBC store: implemented by
- Store interface → Redis store: implemented by
- Caffeine store → Redis or SQL database: stores records
- JDBC store → Redis or SQL database: stores records
- Redis store → Redis or SQL database: stores records
- Exchange context filter → Reactive aspect: provides exchange context
- HTTP client → Exchange context filter: sends reactive request
- Reactive aspect → Store interface: claims and replays
- Reactive aspect → Application handler: invokes on claim
- Boot auto-configuration → Idempotency aspect: configures
- Boot auto-configuration → Servlet filter mode: configures
- Boot auto-configuration → Idempotency settings: binds settings
- Problem responses → HTTP client: returns problem response
- Management endpoint → Store interface: inspects or evicts
- Metrics and tracing → Idempotency aspect: observes requests
- JDBC record sweeper → JDBC store: removes expired rows