# namastack/namastack-once architecture

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

- Interactive diagram: https://gitdiagram.com/namastack/namastack-once
- Repository: https://github.com/namastack/namastack-once

## Overview

Namastack Once is a Spring Boot library for transactional idempotency. An application can invoke protected work through the programmatic API or an annotation; Once reserves a scope-and-key marker, skips duplicates, and commits successful work with the marker or rolls back failures. Retention and cleanup control when markers can be removed. JDBC and MongoDB provide persistence options, while optional Micrometer instrumentation covers execution and cleanup. The README documents Modulith listeners and named instances; their internal wiring is not established by the sampled source.

Main entry points: [`namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt`](https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt) (Execution operations), [`namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt`](https://github.com/namastack/namastack-once/blob/main/namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt) (JDBC repository), [`namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyMarkerRepository.kt`](https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyMarkerRepository.kt) (Repository contract), [`namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt`](https://github.com/namastack/namastack-once/blob/main/namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt) (Mongo repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_annotation["Idempotent annotation<br/>[Idempotent.kt]"]
  node_annotation_resolver["Method resolver"]
  node_interceptor["Method interception"]
  node_operations_api["Operations API"]
  node_request["Request and result"]
  node_modulith["Modulith listeners"]
end

subgraph group_engine["Idempotency engine"]
  node_engine["Execution operations"]
  node_key["Key normalization"]
  node_marker["Marker model"]
  node_retention["Retention policies"]
end

subgraph group_persistence["Marker persistence"]
  node_repository_api["Repository contract"]
  node_jdbc_repository["JDBC repository"]
  node_jdbc_queries["SQL dialect queries"]
  node_jdbc_factory["Dialect selection"]
  node_mongo_repository["Mongo repository"]
end

subgraph group_operations["Operations and telemetry"]
  node_cleanup["Cleanup scheduler"]
  node_instrumentation["Instrumentation contract"]
  node_micrometer["Micrometer integration"]
  node_observability_config["Observability setup"]
  node_spring_config["Spring infrastructure"]
  node_named_instances["Named instances"]
end

node_application(("Spring application"))
node_database[("Configured database")]

node_application -->|"annotates methods"| node_annotation
node_application -->|"calls execute"| node_operations_api
node_annotation_resolver -->|"resolves metadata"| node_annotation
node_interceptor -.->|"delegates execution"| node_engine
node_operations_api -.->|"implements API"| node_engine
node_engine -->|"reserves marker"| node_repository_api
node_engine -.->|"normalizes identity"| node_key
node_engine -.->|"calculates expiry"| node_retention
node_engine -.->|"builds marker"| node_marker
node_engine -->|"runs protected work"| node_application
node_cleanup -.->|"cleans markers"| node_repository_api
node_jdbc_repository -->|"implements contract"| node_repository_api
node_mongo_repository -->|"implements contract"| node_repository_api
node_jdbc_repository -->|"uses statements"| node_jdbc_queries
node_jdbc_factory -->|"selects dialect"| node_jdbc_queries
node_jdbc_repository -->|"reads and writes"| node_database
node_mongo_repository -->|"reads and writes"| node_database
node_jdbc_repository -->|"records cleanup"| node_instrumentation
node_mongo_repository -->|"records cleanup"| node_instrumentation
node_observability_config -->|"configures"| node_micrometer
node_micrometer -.->|"implements contract"| node_instrumentation
node_application -->|"protects listeners"| node_modulith
node_application -->|"configures beans"| node_named_instances
node_engine -.->|"uses infrastructure"| node_spring_config

click node_annotation "https://github.com/namastack/namastack-once/blob/main/namastack-once-api/src/main/kotlin/io/namastack/once/annotation/Idempotent.kt"
click node_annotation_resolver "https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/annotation/IdempotentMethodResolver.kt"
click node_interceptor "https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/annotation/IdempotentMethodInterceptor.kt"
click node_operations_api "https://github.com/namastack/namastack-once/blob/main/namastack-once-api/src/main/kotlin/io/namastack/once/IdempotencyOperations.kt"
click node_request "https://github.com/namastack/namastack-once/blob/main/namastack-once-api/src/main/kotlin/io/namastack/once/IdempotencyRequest.kt"
click node_engine "https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt"
click node_key "https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyKeyNormalizer.kt"
click node_marker "https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyMarker.kt"
click node_retention "https://github.com/namastack/namastack-once/blob/main/namastack-once-api/src/main/kotlin/io/namastack/once/retention/IdempotencyRetentionPolicy.kt"
click node_cleanup "https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/OnceCleanupScheduler.kt"
click node_repository_api "https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyMarkerRepository.kt"
click node_jdbc_repository "https://github.com/namastack/namastack-once/blob/main/namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt"
click node_jdbc_queries "https://github.com/namastack/namastack-once/blob/main/namastack-once-jdbc/src/main/kotlin/io/namastack/once/query/JdbcOnceMarkerQueries.kt"
click node_jdbc_factory "https://github.com/namastack/namastack-once/blob/main/namastack-once-jdbc/src/main/kotlin/io/namastack/once/query/JdbcOnceMarkerQueriesFactory.kt"
click node_mongo_repository "https://github.com/namastack/namastack-once/blob/main/namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt"
click node_instrumentation "https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/instrumentation/OnceInstrumentation.kt"
click node_micrometer "https://github.com/namastack/namastack-once/blob/main/namastack-once-observability/src/main/kotlin/io/namastack/once/observability/MicrometerOnceInstrumentation.kt"
click node_observability_config "https://github.com/namastack/namastack-once/blob/main/namastack-once-observability/src/main/kotlin/io/namastack/once/observability/OnceObservabilityAutoConfiguration.kt"
click node_spring_config "https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/config/OnceCoreInfrastructureAutoConfiguration.kt"
click node_modulith "https://github.com/namastack/namastack-once/tree/main/namastack-once-core/src/main/kotlin/io/namastack/once/annotation"
click node_named_instances "https://github.com/namastack/namastack-once/tree/main/namastack-once-core/src/main/kotlin/io/namastack/once/config"

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_annotation,node_annotation_resolver,node_interceptor,node_operations_api,node_request,node_modulith toneBlue
class node_engine,node_key,node_marker,node_retention,node_database toneAmber
class node_repository_api,node_jdbc_repository,node_jdbc_queries,node_jdbc_factory,node_mongo_repository toneMint
class node_cleanup,node_instrumentation,node_micrometer,node_observability_config,node_spring_config,node_named_instances toneRose
class node_application toneIndigo
```

## Components

### Application entry

- [Idempotent annotation](https://github.com/namastack/namastack-once/blob/main/namastack-once-api/src/main/kotlin/io/namastack/once/annotation/Idempotent.kt): `namastack-once-api/src/main/kotlin/io/namastack/once/annotation/Idempotent.kt`
- [Method resolver](https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/annotation/IdempotentMethodResolver.kt): `namastack-once-core/src/main/kotlin/io/namastack/once/annotation/IdempotentMethodResolver.kt`
- [Method interception](https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/annotation/IdempotentMethodInterceptor.kt): `namastack-once-core/src/main/kotlin/io/namastack/once/annotation/IdempotentMethodInterceptor.kt`
- [Operations API](https://github.com/namastack/namastack-once/blob/main/namastack-once-api/src/main/kotlin/io/namastack/once/IdempotencyOperations.kt): `namastack-once-api/src/main/kotlin/io/namastack/once/IdempotencyOperations.kt`
- [Request and result](https://github.com/namastack/namastack-once/blob/main/namastack-once-api/src/main/kotlin/io/namastack/once/IdempotencyRequest.kt): `namastack-once-api/src/main/kotlin/io/namastack/once/IdempotencyRequest.kt`
- [Modulith listeners](https://github.com/namastack/namastack-once/tree/main/namastack-once-core/src/main/kotlin/io/namastack/once/annotation): `namastack-once-core/src/main/kotlin/io/namastack/once/annotation`

### Idempotency engine

- [Execution operations](https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt): `namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt`
- [Key normalization](https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyKeyNormalizer.kt): `namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyKeyNormalizer.kt`
- [Marker model](https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyMarker.kt): `namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyMarker.kt`
- [Retention policies](https://github.com/namastack/namastack-once/blob/main/namastack-once-api/src/main/kotlin/io/namastack/once/retention/IdempotencyRetentionPolicy.kt): `namastack-once-api/src/main/kotlin/io/namastack/once/retention/IdempotencyRetentionPolicy.kt`

### Marker persistence

- [Repository contract](https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyMarkerRepository.kt): `namastack-once-core/src/main/kotlin/io/namastack/once/IdempotencyMarkerRepository.kt`
- [JDBC repository](https://github.com/namastack/namastack-once/blob/main/namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt): `namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt`
- [SQL dialect queries](https://github.com/namastack/namastack-once/blob/main/namastack-once-jdbc/src/main/kotlin/io/namastack/once/query/JdbcOnceMarkerQueries.kt): `namastack-once-jdbc/src/main/kotlin/io/namastack/once/query/JdbcOnceMarkerQueries.kt`
- [Dialect selection](https://github.com/namastack/namastack-once/blob/main/namastack-once-jdbc/src/main/kotlin/io/namastack/once/query/JdbcOnceMarkerQueriesFactory.kt): `namastack-once-jdbc/src/main/kotlin/io/namastack/once/query/JdbcOnceMarkerQueriesFactory.kt`
- [Mongo repository](https://github.com/namastack/namastack-once/blob/main/namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt): `namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt`

### Operations and telemetry

- [Cleanup scheduler](https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/OnceCleanupScheduler.kt): `namastack-once-core/src/main/kotlin/io/namastack/once/OnceCleanupScheduler.kt`
- [Instrumentation contract](https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/instrumentation/OnceInstrumentation.kt): `namastack-once-core/src/main/kotlin/io/namastack/once/instrumentation/OnceInstrumentation.kt`
- [Micrometer integration](https://github.com/namastack/namastack-once/blob/main/namastack-once-observability/src/main/kotlin/io/namastack/once/observability/MicrometerOnceInstrumentation.kt): `namastack-once-observability/src/main/kotlin/io/namastack/once/observability/MicrometerOnceInstrumentation.kt`
- [Observability setup](https://github.com/namastack/namastack-once/blob/main/namastack-once-observability/src/main/kotlin/io/namastack/once/observability/OnceObservabilityAutoConfiguration.kt): `namastack-once-observability/src/main/kotlin/io/namastack/once/observability/OnceObservabilityAutoConfiguration.kt`
- [Spring infrastructure](https://github.com/namastack/namastack-once/blob/main/namastack-once-core/src/main/kotlin/io/namastack/once/config/OnceCoreInfrastructureAutoConfiguration.kt): `namastack-once-core/src/main/kotlin/io/namastack/once/config/OnceCoreInfrastructureAutoConfiguration.kt`
- [Named instances](https://github.com/namastack/namastack-once/tree/main/namastack-once-core/src/main/kotlin/io/namastack/once/config): `namastack-once-core/src/main/kotlin/io/namastack/once/config`

### Other components

- **Spring application**
- **Configured database**

## Connections

- Spring application → Idempotent annotation: annotates methods
- Spring application → Operations API: calls execute
- Method resolver → Idempotent annotation: resolves metadata (evidence: `namastack-once-core/src/main/kotlin/io/namastack/once/annotation/IdempotentMethodResolver.kt`)
- Method interception → Execution operations: delegates execution
- Operations API → Execution operations: implements API (evidence: `namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt`)
- Execution operations → Repository contract: reserves marker (evidence: `namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt`)
- Execution operations → Key normalization: normalizes identity (evidence: `namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt`)
- Execution operations → Retention policies: calculates expiry
- Execution operations → Marker model: builds marker (evidence: `namastack-once-core/src/main/kotlin/io/namastack/once/DefaultIdempotencyOperations.kt`)
- Execution operations → Spring application: runs protected work
- Cleanup scheduler → Repository contract: cleans markers
- JDBC repository → Repository contract: implements contract (evidence: `namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt`)
- Mongo repository → Repository contract: implements contract (evidence: `namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt`)
- JDBC repository → SQL dialect queries: uses statements (evidence: `namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt`)
- Dialect selection → SQL dialect queries: selects dialect (evidence: `namastack-once-jdbc/src/main/kotlin/io/namastack/once/query/JdbcOnceMarkerQueriesFactory.kt`)
- JDBC repository → Configured database: reads and writes (evidence: `namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt`)
- Mongo repository → Configured database: reads and writes (evidence: `namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt`)
- JDBC repository → Instrumentation contract: records cleanup (evidence: `namastack-once-jdbc/src/main/kotlin/io/namastack/once/JdbcIdempotencyMarkerRepository.kt`)
- Mongo repository → Instrumentation contract: records cleanup (evidence: `namastack-once-mongodb/src/main/kotlin/io/namastack/once/MongoIdempotencyMarkerRepository.kt`)
- Observability setup → Micrometer integration: configures (evidence: `namastack-once-observability/src/main/kotlin/io/namastack/once/observability/OnceObservabilityAutoConfiguration.kt`)
- Micrometer integration → Instrumentation contract: implements contract
- Spring application → Modulith listeners: protects listeners
- Spring application → Named instances: configures beans
- Execution operations → Spring infrastructure: uses infrastructure
