# sxperfect/gunz-utils architecture

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

- Interactive diagram: https://gitdiagram.com/sxperfect/gunz-utils
- Repository: https://github.com/sxperfect/gunz-utils

## Overview

Gunz Utils is a dependency-free Python library of reusable primitives, not an application with one fixed user-to-result pipeline. Developers select individual utilities for configuration and data handling, concurrency and resilience, I/O and security, reproducible workflows, or experiments and statistics. The graph groups these capabilities and shows only documented or indexed module relationships. Benchmarking is a documented capability, but its package path is absent from the supplied tree; unsampled modules are included without speculative call edges.

Main entry points: [`src/gunz_utils/content_store.py`](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/content_store.py) (Content store), [`src/gunz_utils/provenance.py`](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/provenance.py) (Provenance), [`src/gunz_utils/collections.py`](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/collections.py) (Collections), [`src/gunz_utils/io.py`](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/io.py) (I/O and streaming)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and configuration"]
  node_collections["Collections<br/>[collections.py]"]
  node_configuration["Configuration and parsing<br/>[config.py]"]
  node_validation["Stdlib validation"]
end

subgraph group_reliability["Concurrency and resilience"]
  node_cache["Caching<br/>[cache.py]"]
  node_concurrency["Concurrency<br/>[concurrency.py]"]
  node_retry["Retry<br/>[retry.py]"]
  node_resilience["Resilience and limits<br/>[resilience.py]"]
  node_rate_leases["Rate limits and leases<br/>[rate_limit.py]"]
end

subgraph group_io["I/O and security"]
  node_io_helpers["I/O and streaming<br/>[io.py]"]
  node_serialization["Serialization<br/>[serialization.py]"]
  node_hashing["Hashing<br/>[hashing.py]"]
  node_content_store[("Content store<br/>[content_store.py]")]
  node_security["Security and redaction<br/>[security.py]"]
  node_secure_store[("Encrypted secure store<br/>[secure_store.py]")]
  node_subprocess["Process execution<br/>[subprocess.py]"]
  node_streaming["Streaming<br/>[streaming.py]"]
  node_redaction["Redaction<br/>[redaction.py]"]
end

subgraph group_workflow["Reproducibility and workflows"]
  node_dag["Workflow DAG<br/>[dag.py]"]
  node_provenance["Provenance<br/>[provenance.py]"]
  node_provenance_graph["Provenance graph"]
  node_versioning["Versioning and partitions<br/>[versioning.py]"]
end

subgraph group_experiments["Experiments and statistics"]
  node_experiments["Experiment utilities<br/>[experiments.py]"]
  node_sampling_stats["Sampling and statistics<br/>[sampling.py]"]
  node_structures["Data structures<br/>[structures.py]"]
end

node_developer(("Library developer"))

node_developer -->|"uses utilities"| node_collections
node_developer -->|"configures"| node_configuration
node_developer -->|"uses utilities"| node_cache
node_developer -->|"handles I/O"| node_io_helpers
node_developer -->|"uses utilities"| node_security
node_developer -->|"executes workflows"| node_dag
node_developer -->|"runs experiments"| node_experiments
node_cache -->|"uses"| node_collections
node_content_store -->|"hashes files"| node_hashing
node_content_store -->|"uses I/O"| node_io_helpers
node_content_store -->|"uses streaming"| node_streaming
node_streaming -->|"uses"| node_serialization
node_dag -->|"fingerprints stages"| node_hashing
node_provenance -->|"uses I/O"| node_io_helpers
node_provenance -->|"uses structures"| node_structures
node_provenance -->|"uses redaction"| node_redaction
node_structures -->|"uses"| node_collections

click node_collections "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/collections.py"
click node_configuration "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/config.py"
click node_validation "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/ext/validation_stdlib.py"
click node_cache "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/cache.py"
click node_concurrency "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/concurrency.py"
click node_retry "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/retry.py"
click node_resilience "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/resilience.py"
click node_rate_leases "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/rate_limit.py"
click node_io_helpers "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/io.py"
click node_serialization "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/serialization.py"
click node_hashing "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/hashing.py"
click node_content_store "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/content_store.py"
click node_security "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/security.py"
click node_secure_store "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/ext/secure_store.py"
click node_subprocess "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/subprocess.py"
click node_streaming "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/streaming.py"
click node_redaction "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/redaction.py"
click node_dag "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/dag.py"
click node_provenance "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/provenance.py"
click node_provenance_graph "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/provenance_graph.py"
click node_versioning "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/versioning.py"
click node_experiments "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/experiments.py"
click node_sampling_stats "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/sampling.py"
click node_structures "https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/structures.py"

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_collections,node_configuration,node_validation toneBlue
class node_cache,node_concurrency,node_retry,node_resilience,node_rate_leases toneAmber
class node_io_helpers,node_serialization,node_hashing,node_content_store,node_security,node_secure_store,node_subprocess,node_streaming,node_redaction toneMint
class node_dag,node_provenance,node_provenance_graph,node_versioning toneRose
class node_experiments,node_sampling_stats,node_structures,node_developer toneIndigo
```

## Components

### Data and configuration

- [Collections](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/collections.py): `src/gunz_utils/collections.py`
- [Configuration and parsing](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/config.py): `src/gunz_utils/config.py`
- [Stdlib validation](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/ext/validation_stdlib.py): `src/gunz_utils/ext/validation_stdlib.py`

### Concurrency and resilience

- [Caching](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/cache.py): `src/gunz_utils/cache.py`
- [Concurrency](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/concurrency.py): `src/gunz_utils/concurrency.py`
- [Retry](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/retry.py): `src/gunz_utils/retry.py`
- [Resilience and limits](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/resilience.py): `src/gunz_utils/resilience.py`
- [Rate limits and leases](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/rate_limit.py): `src/gunz_utils/rate_limit.py`

### I/O and security

- [I/O and streaming](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/io.py): `src/gunz_utils/io.py`
- [Serialization](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/serialization.py): `src/gunz_utils/serialization.py`
- [Hashing](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/hashing.py): `src/gunz_utils/hashing.py`
- [Content store](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/content_store.py): `src/gunz_utils/content_store.py`
- [Security and redaction](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/security.py): `src/gunz_utils/security.py`
- [Encrypted secure store](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/ext/secure_store.py): `src/gunz_utils/ext/secure_store.py`
- [Process execution](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/subprocess.py): `src/gunz_utils/subprocess.py`
- [Streaming](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/streaming.py): `src/gunz_utils/streaming.py`
- [Redaction](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/redaction.py): `src/gunz_utils/redaction.py`

### Reproducibility and workflows

- [Workflow DAG](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/dag.py): `src/gunz_utils/dag.py`
- [Provenance](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/provenance.py): `src/gunz_utils/provenance.py`
- [Provenance graph](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/provenance_graph.py): `src/gunz_utils/provenance_graph.py`
- [Versioning and partitions](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/versioning.py): `src/gunz_utils/versioning.py`

### Experiments and statistics

- [Experiment utilities](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/experiments.py): `src/gunz_utils/experiments.py`
- [Sampling and statistics](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/sampling.py): `src/gunz_utils/sampling.py`
- [Data structures](https://github.com/sxperfect/gunz-utils/blob/main/src/gunz_utils/structures.py): `src/gunz_utils/structures.py`

### Other components

- **Library developer**

## Connections

- Library developer → Collections: uses utilities (evidence: `README.md`)
- Library developer → Configuration and parsing: configures (evidence: `README.md`)
- Library developer → Caching: uses utilities (evidence: `README.md`)
- Library developer → I/O and streaming: handles I/O (evidence: `README.md`)
- Library developer → Security and redaction: uses utilities (evidence: `README.md`)
- Library developer → Workflow DAG: executes workflows (evidence: `README.md`)
- Library developer → Experiment utilities: runs experiments (evidence: `README.md`)
- Caching → Collections: uses (evidence: `src/gunz_utils/cache.py`)
- Content store → Hashing: hashes files (evidence: `src/gunz_utils/content_store.py`)
- Content store → I/O and streaming: uses I/O (evidence: `src/gunz_utils/content_store.py`)
- Content store → Streaming: uses streaming (evidence: `src/gunz_utils/content_store.py`)
- Streaming → Serialization: uses (evidence: `src/gunz_utils/streaming.py`)
- Workflow DAG → Hashing: fingerprints stages (evidence: `src/gunz_utils/dag.py`)
- Provenance → I/O and streaming: uses I/O (evidence: `src/gunz_utils/provenance.py`)
- Provenance → Data structures: uses structures (evidence: `src/gunz_utils/provenance.py`)
- Provenance → Redaction: uses redaction (evidence: `src/gunz_utils/provenance.py`)
- Data structures → Collections: uses (evidence: `src/gunz_utils/structures.py`)
