# mikemoore63/gcp-secretmanager-cache architecture

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

- Interactive diagram: https://gitdiagram.com/mikemoore63/gcp-secretmanager-cache
- Repository: https://github.com/mikemoore63/gcp-secretmanager-cache

## Overview

This package caches Google Secret Manager values for concurrent callers, returns the latest enabled secret version, and refreshes cached values after a TTL while retaining the old value on retryable service failures. Callers can invalidate entries or use decorators to inject secrets into functions. A separate documented capability handles rotation: Pub/Sub-triggered orchestration selects a secret mechanic, reads its configuration, and manages secret versions. Rotation implementation files were not sampled, so those nodes use the existing package directory and only documented relationships are shown.

Main entry points: [`gcp_secretmanager_cache/cache_secret.py`](https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/cache_secret.py) (Cached secret), [`gcp_secretmanager_cache`](https://github.com/mikemoore63/gcp-secretmanager-cache/tree/main/gcp_secretmanager_cache) (Rotation orchestrator), [`gcp_secretmanager_cache/decorators.py`](https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/decorators.py) (Secret decorators), [`gcp_secretmanager_cache/exceptions.py`](https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/exceptions.py) (Cache exceptions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cache["Secret cache"]
  node_cache_api["Cached secret<br/>[cache_secret.py]"]
  node_refresh["TTL refresh<br/>[cache_secret.py]"]
  node_version_lookup["Enabled version lookup<br/>[cache_secret.py]"]
  node_cache_errors["Cache exceptions<br/>[exceptions.py]"]
end

subgraph group_injection["Secret injection"]
  node_decorators["Secret decorators<br/>[decorators.py]"]
end

subgraph group_rotation["Secret rotation"]
  node_rotator["Rotation orchestrator"]
  node_mechanic["Secret mechanic"]
  node_rotation_config["Rotation configuration"]
end

node_caller(("Application caller"))
node_secret_manager[("Google Secret Manager")]
node_rotation_event["Rotation event"]
node_cloud_storage[("Google Cloud Storage")]

node_caller -->|"gets or invalidates"| node_cache_api
node_cache_api -->|"resolves version"| node_version_lookup
node_version_lookup -->|"lists versions and fetches"| node_secret_manager
node_cache_api -->|"schedules refresh"| node_refresh
node_refresh -->|"refreshes value"| node_version_lookup
node_cache_api -->|"raises cache errors"| node_cache_errors
node_caller -->|"wraps function"| node_decorators
node_decorators -->|"looks up secret"| node_cache_api
node_rotation_event -->|"triggers rotation"| node_rotator
node_rotator -->|"manages versions"| node_secret_manager
node_rotator -->|"delegates secret work"| node_mechanic
node_rotator -->|"reads configuration"| node_rotation_config
node_rotation_config -.->|"may load GCS JSON"| node_cloud_storage

click node_cache_api "https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/cache_secret.py"
click node_refresh "https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/cache_secret.py"
click node_version_lookup "https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/cache_secret.py"
click node_cache_errors "https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/exceptions.py"
click node_decorators "https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/decorators.py"
click node_rotator "https://github.com/mikemoore63/gcp-secretmanager-cache/tree/main/gcp_secretmanager_cache"
click node_mechanic "https://github.com/mikemoore63/gcp-secretmanager-cache/tree/main/gcp_secretmanager_cache"
click node_rotation_config "https://github.com/mikemoore63/gcp-secretmanager-cache/tree/main/gcp_secretmanager_cache"

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_cache_api,node_refresh,node_version_lookup,node_cache_errors toneBlue
class node_decorators,node_secret_manager,node_cloud_storage toneAmber
class node_rotator,node_mechanic,node_rotation_config toneMint
class node_caller,node_rotation_event toneIndigo
```

## Components

### Secret cache

- [Cached secret](https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/cache_secret.py): `gcp_secretmanager_cache/cache_secret.py`
- [TTL refresh](https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/cache_secret.py): `gcp_secretmanager_cache/cache_secret.py`
- [Enabled version lookup](https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/cache_secret.py): `gcp_secretmanager_cache/cache_secret.py`
- [Cache exceptions](https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/exceptions.py): `gcp_secretmanager_cache/exceptions.py`

### Secret injection

- [Secret decorators](https://github.com/mikemoore63/gcp-secretmanager-cache/blob/main/gcp_secretmanager_cache/decorators.py): `gcp_secretmanager_cache/decorators.py`

### Secret rotation

- [Rotation orchestrator](https://github.com/mikemoore63/gcp-secretmanager-cache/tree/main/gcp_secretmanager_cache): `gcp_secretmanager_cache`
- [Secret mechanic](https://github.com/mikemoore63/gcp-secretmanager-cache/tree/main/gcp_secretmanager_cache): `gcp_secretmanager_cache`
- [Rotation configuration](https://github.com/mikemoore63/gcp-secretmanager-cache/tree/main/gcp_secretmanager_cache): `gcp_secretmanager_cache`

### Other components

- **Application caller**
- **Google Secret Manager**
- **Rotation event**
- **Google Cloud Storage**

## Connections

- Application caller → Cached secret: gets or invalidates (evidence: `README.md`)
- Cached secret → Enabled version lookup: resolves version (evidence: `README.md`)
- Enabled version lookup → Google Secret Manager: lists versions and fetches (evidence: `README.md`)
- Cached secret → TTL refresh: schedules refresh (evidence: `README.md`)
- TTL refresh → Enabled version lookup: refreshes value (evidence: `README.md`)
- Cached secret → Cache exceptions: raises cache errors (evidence: `README.md`)
- Application caller → Secret decorators: wraps function (evidence: `README.md`)
- Secret decorators → Cached secret: looks up secret (evidence: `README.md`)
- Rotation event → Rotation orchestrator: triggers rotation (evidence: `README.md`)
- Rotation orchestrator → Google Secret Manager: manages versions (evidence: `README.md`)
- Rotation orchestrator → Secret mechanic: delegates secret work (evidence: `README.md`)
- Rotation orchestrator → Rotation configuration: reads configuration (evidence: `README.md`)
- Rotation configuration → Google Cloud Storage: may load GCS JSON (evidence: `README.md`)