# sartrebrasil/idempotency-library architecture

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

- Interactive diagram: https://gitdiagram.com/sartrebrasil/idempotency-library
- Repository: https://github.com/sartrebrasil/idempotency-library

## Overview

A Java idempotency library that ensures an operation runs at most once per key and can replay its first result. The main workflow is a Spring-managed invocation intercepted by the starter, resolved to a key and scope, then handled by the core engine, which coordinates execution and persistence. The README documents HTTP, queue, job, and service use, replay and conflict behavior, and interchangeable in-memory, JDBC, Redis, and Mongo stores. No source excerpts were provided, so relationships below rely on README statements; implementation details not documented there are omitted.

Main entry points: [`idempotency-core/src/main/java/com/example/idempotency/core/IdempotencyEngine.java`](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/core/IdempotencyEngine.java) (Idempotency engine), [`idempotency-core/src/main/java/com/example/idempotency/spi/IdempotencyStore.java`](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/spi/IdempotencyStore.java) (Store interface), [`idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/IdempotencyInterceptor.java`](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/IdempotencyInterceptor.java) (Invocation interceptor), [`idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/IdempotencyAdvisor.java`](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/IdempotencyAdvisor.java) (Annotation advisor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Spring entry points"]
  node_annotations["Idempotency annotations<br/>[Idempotent.java]"]
  node_advisor["Annotation advisor"]
  node_interceptor["Invocation interceptor"]
  node_keyresolution["Key resolution"]
  node_fingerprinting["Payload fingerprinting"]
end

subgraph group_core["Idempotency core"]
  node_engine["Idempotency engine"]
  node_operation["Operation execution"]
  node_records["Operation records"]
  node_serialization["Result serialization"]
  node_storeapi["Store interface"]
end

subgraph group_persistence["Persistence backends"]
  node_memory[("In-memory store")]
  node_jdbc[("JDBC store")]
  node_redis[("Redis store")]
  node_mongo[("Mongo store")]
end

subgraph group_http["HTTP integration"]
  node_httpmapping["HTTP exception mapping"]
end

node_caller(("Application invocation"))
node_client(("HTTP or worker client"))

node_caller -->|"invokes bean"| node_advisor
node_advisor -->|"finds annotations"| node_annotations
node_advisor -.->|"intercepts invocation"| node_interceptor
node_interceptor -->|"resolves key"| node_keyresolution
node_interceptor -.->|"checks payload"| node_fingerprinting
node_interceptor -.->|"handles operation"| node_engine
node_engine -.->|"executes operation"| node_operation
node_engine -.->|"coordinates records"| node_storeapi
node_engine -.->|"replays result"| node_serialization
node_engine -.->|"tracks state"| node_records
node_memory -->|"implements"| node_storeapi
node_jdbc -->|"implements"| node_storeapi
node_redis -->|"implements"| node_storeapi
node_mongo -->|"implements"| node_storeapi
node_client -->|"receives HTTP errors"| node_httpmapping

click node_annotations "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/annotation/Idempotent.java"
click node_advisor "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/IdempotencyAdvisor.java"
click node_interceptor "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/IdempotencyInterceptor.java"
click node_keyresolution "https://github.com/sartrebrasil/idempotency-library/tree/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/key"
click node_fingerprinting "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/PayloadFingerprinter.java"
click node_engine "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/core/IdempotencyEngine.java"
click node_operation "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/core/IdempotentOperation.java"
click node_records "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/model/IdempotencyRecord.java"
click node_serialization "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/spi/ResultSerializer.java"
click node_storeapi "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/spi/IdempotencyStore.java"
click node_memory "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/store/InMemoryIdempotencyStore.java"
click node_jdbc "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-store-jdbc/src/main/java/com/example/idempotency/spring/store/jdbc/JdbcIdempotencyStore.java"
click node_redis "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-store-redis/src/main/java/com/example/idempotency/spring/store/redis/RedisIdempotencyStore.java"
click node_mongo "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-store-mongo/src/main/java/com/example/idempotency/spring/store/mongo/MongoIdempotencyStore.java"
click node_httpmapping "https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/web/IdempotencyExceptionHandler.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_annotations,node_advisor,node_interceptor,node_keyresolution,node_fingerprinting toneBlue
class node_engine,node_operation,node_records,node_serialization,node_storeapi toneAmber
class node_memory,node_jdbc,node_redis,node_mongo toneMint
class node_httpmapping,node_client toneRose
class node_caller toneIndigo
```

## Components

### Spring entry points

- [Idempotency annotations](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/annotation/Idempotent.java): `idempotency-core/src/main/java/com/example/idempotency/annotation/Idempotent.java`
- [Annotation advisor](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/IdempotencyAdvisor.java): `idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/IdempotencyAdvisor.java`
- [Invocation interceptor](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/IdempotencyInterceptor.java): `idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/IdempotencyInterceptor.java`
- [Key resolution](https://github.com/sartrebrasil/idempotency-library/tree/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/key): `idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/key`
- [Payload fingerprinting](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/PayloadFingerprinter.java): `idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/aspect/PayloadFingerprinter.java`

### Idempotency core

- [Idempotency engine](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/core/IdempotencyEngine.java): `idempotency-core/src/main/java/com/example/idempotency/core/IdempotencyEngine.java`
- [Operation execution](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/core/IdempotentOperation.java): `idempotency-core/src/main/java/com/example/idempotency/core/IdempotentOperation.java`
- [Operation records](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/model/IdempotencyRecord.java): `idempotency-core/src/main/java/com/example/idempotency/model/IdempotencyRecord.java`
- [Result serialization](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/spi/ResultSerializer.java): `idempotency-core/src/main/java/com/example/idempotency/spi/ResultSerializer.java`
- [Store interface](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/spi/IdempotencyStore.java): `idempotency-core/src/main/java/com/example/idempotency/spi/IdempotencyStore.java`

### Persistence backends

- [In-memory store](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-core/src/main/java/com/example/idempotency/store/InMemoryIdempotencyStore.java): `idempotency-core/src/main/java/com/example/idempotency/store/InMemoryIdempotencyStore.java`
- [JDBC store](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-store-jdbc/src/main/java/com/example/idempotency/spring/store/jdbc/JdbcIdempotencyStore.java): `idempotency-store-jdbc/src/main/java/com/example/idempotency/spring/store/jdbc/JdbcIdempotencyStore.java`
- [Redis store](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-store-redis/src/main/java/com/example/idempotency/spring/store/redis/RedisIdempotencyStore.java): `idempotency-store-redis/src/main/java/com/example/idempotency/spring/store/redis/RedisIdempotencyStore.java`
- [Mongo store](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-store-mongo/src/main/java/com/example/idempotency/spring/store/mongo/MongoIdempotencyStore.java): `idempotency-store-mongo/src/main/java/com/example/idempotency/spring/store/mongo/MongoIdempotencyStore.java`

### HTTP integration

- [HTTP exception mapping](https://github.com/sartrebrasil/idempotency-library/blob/main/idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/web/IdempotencyExceptionHandler.java): `idempotency-spring-boot-starter/src/main/java/com/example/idempotency/spring/web/IdempotencyExceptionHandler.java`

### Other components

- **Application invocation**
- **HTTP or worker client**

## Connections

- Application invocation → Annotation advisor: invokes bean (evidence: `README.md`)
- Annotation advisor → Idempotency annotations: finds annotations (evidence: `README.md`)
- Annotation advisor → Invocation interceptor: intercepts invocation
- Invocation interceptor → Key resolution: resolves key (evidence: `README.md`)
- Invocation interceptor → Payload fingerprinting: checks payload
- Invocation interceptor → Idempotency engine: handles operation
- Idempotency engine → Operation execution: executes operation
- Idempotency engine → Store interface: coordinates records
- Idempotency engine → Result serialization: replays result
- Idempotency engine → Operation records: tracks state
- In-memory store → Store interface: implements (evidence: `README.md`)
- JDBC store → Store interface: implements (evidence: `README.md`)
- Redis store → Store interface: implements (evidence: `README.md`)
- Mongo store → Store interface: implements (evidence: `README.md`)
- HTTP or worker client → HTTP exception mapping: receives HTTP errors (evidence: `README.md`)