# amals367/credweave architecture

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

- Interactive diagram: https://gitdiagram.com/amals367/credweave
- Repository: https://github.com/amals367/credweave

## Overview

CredWeave is a provider-agnostic Python library for managing credential pools; it does not make upstream network requests. The main workflow is: an application acquires a lease, uses the credential with its own client, then reports an outcome so CredWeave can update lifecycle state and scheduling eligibility. The graph includes documented scheduling and failover capabilities. Some implementation relationships are supported by the SOURCE INDEX rather than full excerpts; unsampled details are not inferred.

Main entry points: [`src/credweave/application/services/pool.py`](https://github.com/amals367/credweave/blob/master/src/credweave/application/services/pool.py) (Credential pool), [`src/credweave/_internal/composition.py`](https://github.com/amals367/credweave/blob/master/src/credweave/_internal/composition.py) (Default composition), [`src/credweave/application/services/lifecycle.py`](https://github.com/amals367/credweave/blob/master/src/credweave/application/services/lifecycle.py) (Lifecycle engine), [`src/credweave/strategies/_eligibility.py`](https://github.com/amals367/credweave/blob/master/src/credweave/strategies/_eligibility.py) (Eligibility filtering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_public["CredWeave API<br/>[__init__.py]"]
end

subgraph group_app["Pool Orchestration"]
  node_pool["Credential pool<br/>[pool.py]"]
  node_strategy_port["Strategy port<br/>[strategy.py]"]
  node_source_port["Credential source port"]
  node_clock_port["Clock port<br/>[clock.py]"]
  node_composition["Default composition<br/>[composition.py]"]
end

subgraph group_domain["Credential Lifecycle"]
  node_credential["Credential model<br/>[models.py]"]
  node_outcome["Outcome model<br/>[outcomes.py]"]
  node_states["Lifecycle states<br/>[enums.py]"]
  node_errors["Domain errors<br/>[errors.py]"]
  node_backoff["Backoff policy<br/>[backoff.py]"]
  node_lifecycle["Lifecycle engine<br/>[lifecycle.py]"]
  node_store_port["State store port<br/>[state_store.py]"]
end

subgraph group_adapters["Strategies and Adapters"]
  node_round_robin["Round-robin<br/>[round_robin.py]"]
  node_weighted["Weighted selection<br/>[weighted.py]"]
  node_failover["Failover selection<br/>[failover.py]"]
  node_other_strategies["Other strategies"]
  node_eligibility["Eligibility filtering<br/>[_eligibility.py]"]
  node_static_source["Static source<br/>[static.py]"]
  node_memory_store[("Memory state store<br/>[memory.py]")]
  node_system_clock["System clock<br/>[system.py]"]
end

node_application(("Client application"))
node_upstream(("Provider API"))

node_application -->|"acquires lease"| node_public
node_public -->|"exposes pool"| node_pool
node_application -->|"makes request"| node_upstream
node_application -->|"reports outcome"| node_public
node_pool -->|"selects credential"| node_strategy_port
node_pool -->|"loads credentials"| node_source_port
node_pool -->|"reads and updates"| node_store_port
node_pool -->|"reads time"| node_clock_port
node_pool -->|"delegates transitions"| node_lifecycle
node_composition -->|"constructs default"| node_pool
node_composition -->|"configures store"| node_memory_store
node_composition -->|"configures source"| node_static_source
node_composition -->|"configures clock"| node_system_clock
node_composition -->|"configures strategy"| node_round_robin
node_pool -->|"leases credential"| node_credential
node_pool -->|"accepts report"| node_outcome
node_lifecycle -->|"computes cooldown"| node_backoff
node_lifecycle -->|"transitions state"| node_states
node_memory_store -->|"applies transitions"| node_lifecycle
node_memory_store -->|"implements port"| node_store_port
node_static_source -->|"implements port"| node_source_port
node_system_clock -->|"implements port"| node_clock_port
node_round_robin -->|"filters candidates"| node_eligibility
node_weighted -->|"filters candidates"| node_eligibility
node_failover -->|"filters candidates"| node_eligibility
node_other_strategies -.->|"shares filtering"| node_eligibility
node_outcome -->|"uses outcome types"| node_states
node_backoff -->|"raises configuration errors"| node_errors

click node_public "https://github.com/amals367/credweave/blob/master/src/credweave/__init__.py"
click node_pool "https://github.com/amals367/credweave/blob/master/src/credweave/application/services/pool.py"
click node_strategy_port "https://github.com/amals367/credweave/blob/master/src/credweave/application/ports/strategy.py"
click node_source_port "https://github.com/amals367/credweave/blob/master/src/credweave/application/ports/credential_source.py"
click node_clock_port "https://github.com/amals367/credweave/blob/master/src/credweave/application/ports/clock.py"
click node_composition "https://github.com/amals367/credweave/blob/master/src/credweave/_internal/composition.py"
click node_credential "https://github.com/amals367/credweave/blob/master/src/credweave/domain/models.py"
click node_outcome "https://github.com/amals367/credweave/blob/master/src/credweave/domain/outcomes.py"
click node_states "https://github.com/amals367/credweave/blob/master/src/credweave/domain/enums.py"
click node_errors "https://github.com/amals367/credweave/blob/master/src/credweave/domain/errors.py"
click node_backoff "https://github.com/amals367/credweave/blob/master/src/credweave/domain/backoff.py"
click node_lifecycle "https://github.com/amals367/credweave/blob/master/src/credweave/application/services/lifecycle.py"
click node_store_port "https://github.com/amals367/credweave/blob/master/src/credweave/application/ports/state_store.py"
click node_round_robin "https://github.com/amals367/credweave/blob/master/src/credweave/strategies/round_robin.py"
click node_weighted "https://github.com/amals367/credweave/blob/master/src/credweave/strategies/weighted.py"
click node_failover "https://github.com/amals367/credweave/blob/master/src/credweave/strategies/failover.py"
click node_other_strategies "https://github.com/amals367/credweave/tree/master/src/credweave/strategies"
click node_eligibility "https://github.com/amals367/credweave/blob/master/src/credweave/strategies/_eligibility.py"
click node_static_source "https://github.com/amals367/credweave/blob/master/src/credweave/infrastructure/sources/static.py"
click node_memory_store "https://github.com/amals367/credweave/blob/master/src/credweave/infrastructure/stores/memory.py"
click node_system_clock "https://github.com/amals367/credweave/blob/master/src/credweave/infrastructure/clocks/system.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_public,node_application toneBlue
class node_pool,node_strategy_port,node_source_port,node_clock_port,node_composition toneAmber
class node_credential,node_outcome,node_states,node_errors,node_backoff,node_lifecycle,node_store_port,node_upstream toneMint
class node_round_robin,node_weighted,node_failover,node_other_strategies,node_eligibility,node_static_source,node_memory_store,node_system_clock toneRose
```

## Components

### Public API

- [CredWeave API](https://github.com/amals367/credweave/blob/master/src/credweave/__init__.py): `src/credweave/__init__.py`

### Pool Orchestration

- [Credential pool](https://github.com/amals367/credweave/blob/master/src/credweave/application/services/pool.py): `src/credweave/application/services/pool.py`
- [Strategy port](https://github.com/amals367/credweave/blob/master/src/credweave/application/ports/strategy.py): `src/credweave/application/ports/strategy.py`
- [Credential source port](https://github.com/amals367/credweave/blob/master/src/credweave/application/ports/credential_source.py): `src/credweave/application/ports/credential_source.py`
- [Clock port](https://github.com/amals367/credweave/blob/master/src/credweave/application/ports/clock.py): `src/credweave/application/ports/clock.py`
- [Default composition](https://github.com/amals367/credweave/blob/master/src/credweave/_internal/composition.py): `src/credweave/_internal/composition.py`

### Credential Lifecycle

- [Credential model](https://github.com/amals367/credweave/blob/master/src/credweave/domain/models.py): `src/credweave/domain/models.py`
- [Outcome model](https://github.com/amals367/credweave/blob/master/src/credweave/domain/outcomes.py): `src/credweave/domain/outcomes.py`
- [Lifecycle states](https://github.com/amals367/credweave/blob/master/src/credweave/domain/enums.py): `src/credweave/domain/enums.py`
- [Domain errors](https://github.com/amals367/credweave/blob/master/src/credweave/domain/errors.py): `src/credweave/domain/errors.py`
- [Backoff policy](https://github.com/amals367/credweave/blob/master/src/credweave/domain/backoff.py): `src/credweave/domain/backoff.py`
- [Lifecycle engine](https://github.com/amals367/credweave/blob/master/src/credweave/application/services/lifecycle.py): `src/credweave/application/services/lifecycle.py`
- [State store port](https://github.com/amals367/credweave/blob/master/src/credweave/application/ports/state_store.py): `src/credweave/application/ports/state_store.py`

### Strategies and Adapters

- [Round-robin](https://github.com/amals367/credweave/blob/master/src/credweave/strategies/round_robin.py): `src/credweave/strategies/round_robin.py`
- [Weighted selection](https://github.com/amals367/credweave/blob/master/src/credweave/strategies/weighted.py): `src/credweave/strategies/weighted.py`
- [Failover selection](https://github.com/amals367/credweave/blob/master/src/credweave/strategies/failover.py): `src/credweave/strategies/failover.py`
- [Other strategies](https://github.com/amals367/credweave/tree/master/src/credweave/strategies): `src/credweave/strategies`
- [Eligibility filtering](https://github.com/amals367/credweave/blob/master/src/credweave/strategies/_eligibility.py): `src/credweave/strategies/_eligibility.py`
- [Static source](https://github.com/amals367/credweave/blob/master/src/credweave/infrastructure/sources/static.py): `src/credweave/infrastructure/sources/static.py`
- [Memory state store](https://github.com/amals367/credweave/blob/master/src/credweave/infrastructure/stores/memory.py): `src/credweave/infrastructure/stores/memory.py`
- [System clock](https://github.com/amals367/credweave/blob/master/src/credweave/infrastructure/clocks/system.py): `src/credweave/infrastructure/clocks/system.py`

### Other components

- **Client application**
- **Provider API**

## Connections

- Client application → CredWeave API: acquires lease (evidence: `README.md`)
- CredWeave API → Credential pool: exposes pool (evidence: `src/credweave/__init__.py`)
- Client application → Provider API: makes request (evidence: `README.md`)
- Client application → CredWeave API: reports outcome (evidence: `README.md`)
- Credential pool → Strategy port: selects credential (evidence: `src/credweave/application/services/pool.py`)
- Credential pool → Credential source port: loads credentials (evidence: `src/credweave/application/services/pool.py`)
- Credential pool → State store port: reads and updates (evidence: `src/credweave/application/services/pool.py`)
- Credential pool → Clock port: reads time (evidence: `src/credweave/application/services/pool.py`)
- Credential pool → Lifecycle engine: delegates transitions (evidence: `src/credweave/application/services/pool.py`)
- Default composition → Credential pool: constructs default (evidence: `src/credweave/_internal/composition.py`)
- Default composition → Memory state store: configures store (evidence: `src/credweave/_internal/composition.py`)
- Default composition → Static source: configures source (evidence: `src/credweave/_internal/composition.py`)
- Default composition → System clock: configures clock (evidence: `src/credweave/_internal/composition.py`)
- Default composition → Round-robin: configures strategy (evidence: `src/credweave/_internal/composition.py`)
- Credential pool → Credential model: leases credential (evidence: `README.md`)
- Credential pool → Outcome model: accepts report (evidence: `README.md`)
- Lifecycle engine → Backoff policy: computes cooldown (evidence: `src/credweave/application/services/lifecycle.py`)
- Lifecycle engine → Lifecycle states: transitions state (evidence: `src/credweave/application/services/lifecycle.py`)
- Memory state store → Lifecycle engine: applies transitions (evidence: `src/credweave/infrastructure/stores/memory.py`)
- Memory state store → State store port: implements port (evidence: `src/credweave/infrastructure/stores/memory.py`)
- Static source → Credential source port: implements port (evidence: `src/credweave/infrastructure/sources/static.py`)
- System clock → Clock port: implements port (evidence: `src/credweave/infrastructure/clocks/system.py`)
- Round-robin → Eligibility filtering: filters candidates (evidence: `src/credweave/strategies/round_robin.py`)
- Weighted selection → Eligibility filtering: filters candidates (evidence: `src/credweave/strategies/weighted.py`)
- Failover selection → Eligibility filtering: filters candidates (evidence: `src/credweave/strategies/failover.py`)
- Other strategies → Eligibility filtering: shares filtering (evidence: `src/credweave/strategies/failover.py`)
- Outcome model → Lifecycle states: uses outcome types (evidence: `src/credweave/domain/outcomes.py`)
- Backoff policy → Domain errors: raises configuration errors (evidence: `src/credweave/domain/backoff.py`)
