# sartrebrasil/idempotency4j architecture
> Architecture diagram of the GitHub repository sartrebrasil/idempotency4j, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/sartrebrasil/idempotency4j
- Repository: https://github.com/sartrebrasil/idempotency4j
## Overview
idempotency4j is a Java engine and set of adapters for running keyed work once and replaying its stored outcome to duplicates. The core manages acquisition, leases, execution, completion and replay; Spring method interception and a Servlet filter provide entry points, while JDBC, Redis and in-memory providers implement persistence. The README documents the main capabilities; sampled source confirms core/store and method-interceptor relationships. Several adapter and starter internals were not sampled, so their detailed wiring is not asserted.
Main entry points: [`idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyEngine.java`](https://github.com/sartrebrasil/idempotency4j/blob/main/idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyEngine.java) (Execution engine), [`idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyStore.java`](https://github.com/sartrebrasil/idempotency4j/blob/main/idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyStore.java) (Store SPI), [`spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/IdempotentMethodInterceptor.java`](https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/IdempotentMethodInterceptor.java) (Method interceptor), [`spring/idempotency-spring-web/src/main/java/io/github/josipmusa/idempotency/spring/web/IdempotencyFilter.java`](https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring-web/src/main/java/io/github/josipmusa/idempotency/spring/web/IdempotencyFilter.java) (Servlet filter)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_entry["Spring entry points"]
node_method_annotation["@Idempotent methods
[Idempotent.java]"]
node_method_interceptor["Method interceptor"]
node_http_filter["Servlet filter"]
node_http_response["Response replay"]
end
subgraph group_engine["Idempotency engine"]
node_identity_context["Identity and context"]
node_engine_core["Execution engine"]
node_payload_codec["Payload codec SPI
[PayloadCodec.java]"]
node_store_spi["Store SPI"]
end
subgraph group_stores["Storage providers"]
node_inmemory[("In-memory store")]
node_jdbc[("JDBC store")]
node_redis[("Redis store")]
end
subgraph group_boot["Boot integration"]
node_boot_auto["Boot auto-configuration"]
node_boot_store["Store configuration"]
node_transaction["Transaction integration"]
end
node_caller(("Application caller"))
node_caller -->|"annotates work"| node_method_annotation
node_method_annotation -->|"intercepted by"| node_method_interceptor
node_method_interceptor -->|"executes through"| node_engine_core
node_caller -->|"sends keyed request"| node_http_filter
node_http_filter -->|"uses engine"| node_engine_core
node_http_filter -.->|"replays response"| node_http_response
node_method_interceptor -.->|"builds context"| node_identity_context
node_engine_core -->|"acquires and completes"| node_store_spi
node_engine_core -->|"encodes outcomes"| node_payload_codec
node_store_spi -->|"implemented by"| node_inmemory
node_store_spi -->|"implemented by"| node_jdbc
node_store_spi -->|"implemented by"| node_redis
node_boot_auto -.->|"configures stores"| node_boot_store
node_boot_store -->|"wires when available"| node_jdbc
node_engine_core -.->|"supports completion mode"| node_transaction
click node_method_annotation "https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/Idempotent.java"
click node_method_interceptor "https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/IdempotentMethodInterceptor.java"
click node_http_filter "https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring-web/src/main/java/io/github/josipmusa/idempotency/spring/web/IdempotencyFilter.java"
click node_http_response "https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring-web/src/main/java/io/github/josipmusa/idempotency/spring/web/StoredResponseCodec.java"
click node_identity_context "https://github.com/sartrebrasil/idempotency4j/blob/main/idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyContext.java"
click node_engine_core "https://github.com/sartrebrasil/idempotency4j/blob/main/idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyEngine.java"
click node_payload_codec "https://github.com/sartrebrasil/idempotency4j/blob/main/idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/PayloadCodec.java"
click node_store_spi "https://github.com/sartrebrasil/idempotency4j/blob/main/idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyStore.java"
click node_inmemory "https://github.com/sartrebrasil/idempotency4j/blob/main/providers/idempotency-inmemory/src/main/java/io/github/josipmusa/idempotency/inmemory/InMemoryIdempotencyStore.java"
click node_jdbc "https://github.com/sartrebrasil/idempotency4j/blob/main/providers/idempotency-jdbc/src/main/java/io/github/josipmusa/idempotency/jdbc/JdbcIdempotencyStore.java"
click node_redis "https://github.com/sartrebrasil/idempotency4j/blob/main/providers/idempotency-redis/src/main/java/io/github/josipmusa/idempotency/redis/RedisIdempotencyStore.java"
click node_boot_auto "https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring-boot-starter/src/main/java/io/github/josipmusa/idempotency/springboot/IdempotencyAutoConfiguration.java"
click node_boot_store "https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring-boot-starter/src/main/java/io/github/josipmusa/idempotency/springboot/IdempotencyStoreAutoConfiguration.java"
click node_transaction "https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/SpringTransactionParticipation.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_method_annotation,node_method_interceptor,node_http_filter,node_http_response toneBlue
class node_identity_context,node_engine_core,node_payload_codec,node_store_spi toneAmber
class node_inmemory,node_jdbc,node_redis toneMint
class node_boot_auto,node_boot_store,node_transaction toneRose
class node_caller toneIndigo
```
## Components
### Spring entry points
- [@Idempotent methods](https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/Idempotent.java): `spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/Idempotent.java`
- [Method interceptor](https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/IdempotentMethodInterceptor.java): `spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/IdempotentMethodInterceptor.java`
- [Servlet filter](https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring-web/src/main/java/io/github/josipmusa/idempotency/spring/web/IdempotencyFilter.java): `spring/idempotency-spring-web/src/main/java/io/github/josipmusa/idempotency/spring/web/IdempotencyFilter.java`
- [Response replay](https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring-web/src/main/java/io/github/josipmusa/idempotency/spring/web/StoredResponseCodec.java): `spring/idempotency-spring-web/src/main/java/io/github/josipmusa/idempotency/spring/web/StoredResponseCodec.java`
### Idempotency engine
- [Identity and context](https://github.com/sartrebrasil/idempotency4j/blob/main/idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyContext.java): `idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyContext.java`
- [Execution engine](https://github.com/sartrebrasil/idempotency4j/blob/main/idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyEngine.java): `idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyEngine.java`
- [Payload codec SPI](https://github.com/sartrebrasil/idempotency4j/blob/main/idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/PayloadCodec.java): `idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/PayloadCodec.java`
- [Store SPI](https://github.com/sartrebrasil/idempotency4j/blob/main/idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyStore.java): `idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyStore.java`
### Storage providers
- [In-memory store](https://github.com/sartrebrasil/idempotency4j/blob/main/providers/idempotency-inmemory/src/main/java/io/github/josipmusa/idempotency/inmemory/InMemoryIdempotencyStore.java): `providers/idempotency-inmemory/src/main/java/io/github/josipmusa/idempotency/inmemory/InMemoryIdempotencyStore.java`
- [JDBC store](https://github.com/sartrebrasil/idempotency4j/blob/main/providers/idempotency-jdbc/src/main/java/io/github/josipmusa/idempotency/jdbc/JdbcIdempotencyStore.java): `providers/idempotency-jdbc/src/main/java/io/github/josipmusa/idempotency/jdbc/JdbcIdempotencyStore.java`
- [Redis store](https://github.com/sartrebrasil/idempotency4j/blob/main/providers/idempotency-redis/src/main/java/io/github/josipmusa/idempotency/redis/RedisIdempotencyStore.java): `providers/idempotency-redis/src/main/java/io/github/josipmusa/idempotency/redis/RedisIdempotencyStore.java`
### Boot integration
- [Boot auto-configuration](https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring-boot-starter/src/main/java/io/github/josipmusa/idempotency/springboot/IdempotencyAutoConfiguration.java): `spring/idempotency-spring-boot-starter/src/main/java/io/github/josipmusa/idempotency/springboot/IdempotencyAutoConfiguration.java`
- [Store configuration](https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring-boot-starter/src/main/java/io/github/josipmusa/idempotency/springboot/IdempotencyStoreAutoConfiguration.java): `spring/idempotency-spring-boot-starter/src/main/java/io/github/josipmusa/idempotency/springboot/IdempotencyStoreAutoConfiguration.java`
- [Transaction integration](https://github.com/sartrebrasil/idempotency4j/blob/main/spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/SpringTransactionParticipation.java): `spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/SpringTransactionParticipation.java`
### Other components
- **Application caller**
## Connections
- Application caller → @Idempotent methods: annotates work (evidence: `README.md`)
- @Idempotent methods → Method interceptor: intercepted by (evidence: `spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/IdempotentMethodInterceptor.java`)
- Method interceptor → Execution engine: executes through (evidence: `spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/IdempotentMethodInterceptor.java`)
- Application caller → Servlet filter: sends keyed request (evidence: `README.md`)
- Servlet filter → Execution engine: uses engine (evidence: `README.md`)
- Servlet filter → Response replay: replays response
- Method interceptor → Identity and context: builds context (evidence: `spring/idempotency-spring/src/main/java/io/github/josipmusa/idempotency/spring/IdempotentMethodInterceptor.java`)
- Execution engine → Store SPI: acquires and completes (evidence: `idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyEngine.java`)
- Execution engine → Payload codec SPI: encodes outcomes (evidence: `idempotency-core/src/main/java/io/github/josipmusa/idempotency/core/IdempotencyEngine.java`)
- Store SPI → In-memory store: implemented by (evidence: `README.md`)
- Store SPI → JDBC store: implemented by (evidence: `README.md`)
- Store SPI → Redis store: implemented by (evidence: `README.md`)
- Boot auto-configuration → Store configuration: configures stores (evidence: `spring/idempotency-spring-boot-starter/src/main/java/io/github/josipmusa/idempotency/springboot/IdempotencyAutoConfiguration.java`)
- Store configuration → JDBC store: wires when available (evidence: `README.md`)
- Execution engine → Transaction integration: supports completion mode