# harut8/resilience_h8 architecture

> Architecture diagram of the GitHub repository harut8/resilience_h8, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harut8/resilience_h8
- Repository: https://github.com/harut8/resilience_h8

## Overview

##### Project Type and Purpose
- This is a Python library (packaged under `resilience_h8`) providing resilience patterns (bulkhead, circuit breaker, retry, timeout, rate limiter) and concurrency control for microservices.
- It offers a Decorator API and a `ResilienceService` façade to apply these patterns to user‐defined (async) functions.

##### File Structure
- Top‐level directories:
- `src/resilience_h8/concurrency/` – task manager implementations (sync + async)
- `src/resilience_h8/resilience/` – pattern implementations (bulkhead, circuit breaker, retry, rate limiter, decorators, etc.)
- `src/resilience_h8/interfaces/` – abstract interfaces for concurrency and resilience components
- `src/resilience_h8/custom_types/` – shared type definitions for stronger typing
- Config & build: `pyproject.toml`, `mypy.ini`, pre-commit, tests in `tests/`, usage examples in `examples/`.

##### README Insights
- Core façade: `ResilienceService(task_manager, logger)`
- Two usage modes: chain decorators individually or via `with_resilience(...)` combined decorator
- Patterns are composable; each pattern implements `.execute()` + decorator wrapper

##### Detailed Component Breakdown to Capture
- ResilienceService (Facade)
- with_retry / with_circuit_breaker / with_bulkhead / with_timeout decorators
- StandardRetryHandler, StandardCircuitBreaker, StandardBulkhead, RateLimiter
- AsyncTaskManager / StandardTaskManager
- Interfaces: IResiliencePattern, ITaskManager
- Custom Types: ResilienceConfig, TaskResult (to show type flow)
- External: Client Code, AsyncClient (httpx), Logger

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Code
    Client["Client Code<br/>(User Functions & Examples)"]:::external
    click Client "https://github.com/harut8/resilience_h8/blob/main/examples/resilience_async_manager_patterns_example.py"

    %% Decorator Layer & Facade
    subgraph "Decorator & Facade Layer"
        direction TB
        Decorators["Decorator Layer<br/>(with_retry, with_circuit_breaker,<br/>with_bulkhead, with_timeout, with_rate_limiter)"]:::facade
        click Decorators "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/resilience/decorators.py"
        Service["ResilienceService<br/>(Facade)"]:::facade
        click Service "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/resilience/decorators.py"
    end

    %% Patterns
    subgraph "Resilience Patterns"
        direction TB
        Retry["Retry Pattern"]:::patterns
        click Retry "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/resilience/retry.py"
        Circuit["CircuitBreaker Pattern"]:::patterns
        click Circuit "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/resilience/circuit_breaker.py"
        Bulkhead["Bulkhead Pattern"]:::patterns
        click Bulkhead "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/resilience/bulkhead.py"
        RateLimiter["RateLimiter Pattern"]:::patterns
        click RateLimiter "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/resilience/rate_limiter.py"
    end

    %% Concurrency Layer
    subgraph "Concurrency Layer"
        direction TB
        AsyncMgr["AsyncTaskManager"]:::concurrency
        click AsyncMgr "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/concurrency/async_task_manager.py"
        StdMgr["StandardTaskManager"]:::concurrency
        click StdMgr "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/concurrency/task_manager.py"
    end

    %% Interfaces
    subgraph "Interfaces"
        direction TB
        IResPattern["IResiliencePattern"]:::interfaces
        click IResPattern "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/interfaces/resilience.py"
        ITaskMgr["ITaskManager"]:::interfaces
        click ITaskMgr "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/interfaces/concurrency.py"
    end

    %% Custom Types
    subgraph "Custom Types"
        direction TB
        ResConfig["ResilienceConfig, TaskResult"]:::types
        click ResConfig "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/custom_types/resilience.py"
        CommonTypes["Common Types"]:::types
        click CommonTypes "https://github.com/harut8/resilience_h8/blob/main/src/resilience_h8/custom_types/common.py"
    end

    %% External Services & Logger
    AsyncClient["AsyncClient (httpx)"]:::external
    Logger["Logger (structlog)"]:::external

    %% Connections
    Client -->|"applies decorator"| Decorators
    Decorators -->|"calls"| Service
    Service -->|"delegates to patterns"| Retry
    Retry -->|"on success/fail"| Circuit
    Circuit -->|"on open/close"| Bulkhead
    Bulkhead -->|"enforces isolation"| RateLimiter
    RateLimiter -->|"invokes underlying function"| AsyncClient

    %% Patterns use Task Managers
    Retry -->|"uses"| AsyncMgr
    Circuit -->|"uses"| StdMgr
    Bulkhead -->|"uses"| StdMgr
    RateLimiter -->|"uses"| AsyncMgr

    %% Task Managers to Logger and AsyncClient
    AsyncMgr -->|"schedules task"| AsyncClient
    StdMgr -->|"executes task"| AsyncClient
    StdMgr -->|"logs via"| Logger
    AsyncMgr -->|"logs via"| Logger
    Retry -->|"logs via"| Logger
    Circuit -->|"logs via"| Logger
    Bulkhead -->|"logs via"| Logger
    RateLimiter -->|"logs via"| Logger

    %% Interfaces to Implementations
    IResPattern --> Retry
    IResPattern --> Circuit
    IResPattern --> Bulkhead
    IResPattern --> RateLimiter
    ITaskMgr --> AsyncMgr
    ITaskMgr --> StdMgr

    %% Facade & Decorators reference Types
    Service --> ResConfig
    Decorators --> ResConfig

    %% Styling
    classDef facade fill:#D0E6FA,stroke:#0366D6,color:#0366D6
    classDef patterns fill:#DFF5E0,stroke:#228B22,color:#228B22
    classDef concurrency fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00
    classDef external fill:#F0F0F0,stroke:#666,color:#333
    classDef interfaces fill:#EEEEEE,stroke:#999,color:#555
    classDef types fill:#F5F5FF,stroke:#667,color:#334
```
