# nodeshift/opossum architecture

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

- Interactive diagram: https://gitdiagram.com/nodeshift/opossum
- Repository: https://github.com/nodeshift/opossum

## Overview

##### Main Components

a. Core Circuit Breaker Components:
- Circuit State Manager (from lib/circuit.js)
- Cache Manager (from lib/cache.js)
- Status Monitor (from lib/status.js)
- Semaphore Controller (from lib/semaphore.js)

b. External Integration Points:
- Promise-based Function Wrapper
- Event System
- Metrics Export Interface (for Prometheus/Hystrix)

**[Client Application]**
- ↓
**[Circuit Breaker Interface]**
- ↓
**[State Management Layer]**
- ↙     ↓     ↘
**[Cache] [Circuit] [Semaphore]**
- ↓
**[Status Monitor]**
- ↙     ↓     ↘
**[Events] [Metrics] [Health Checks]**

##### Key Flows

a. Main Execution Flow:
**Client Request → Circuit Check → Function Execution → Response**

b. Failure Handling Flow:
**Error Detection → State Transition → Fallback Execution**

c. Recovery Flow:
**Timeout → Half-Open State → Health Check → State Reset**

##### Important Details

- State Transitions:
- Closed → Open (on failure threshold)
- Open → Half-Open (on reset timeout)
- Half-Open → Closed/Open (on success/failure)

- Configuration Options:
- Timeout settings
- Error thresholds
- Reset timeouts
- Volume thresholds

- Event System:
- Success/Failure events
- State change events
- Fallback triggers
- Health check events

##### Integration Points

- AbortController integration
- Promise-based interface
- Prometheus/Hystrix metric export points
- Browser/Node.js compatibility

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        CA[Client Application]
    end

    subgraph Interface
        CBI[Circuit Breaker Interface]:::interface
        BIL[Browser Integration Layer]:::interface
    end

    subgraph Core
        SM[State Management]:::core
        CSM[Circuit State Manager]:::core
        CM[Cache Manager]:::core
        SC[Semaphore Controller]:::core
    end

    subgraph Monitoring
        StatusM[Status Monitor]:::monitor
        HC[Health Check System]:::monitor
        VT[Volume Threshold]:::monitor
    end

    subgraph Events
        ES[Event System]:::event
        ME[Metrics Export]:::event
    end

    subgraph Configuration
        Config[Configuration Management]:::config
        CL[Circuit Lifecycle]:::config
    end

    %% Main Flow
    CA --> CBI
    CBI --> SM
    SM --> CSM
    CSM --> CM
    CSM --> SC
    
    %% Monitoring Flow
    CSM --> StatusM
    StatusM --> HC
    StatusM --> VT
    
    %% Event System
    StatusM --> ES
    StatusM --> ME
    
    %% Browser Integration
    CBI --> BIL
    
    %% Configuration
    Config --> CBI
    Config --> CSM
    CL --> CSM

    %% Click Events
    click CSM "https://github.com/nodeshift/opossum/blob/main/lib/circuit.js"
    click CM "https://github.com/nodeshift/opossum/blob/main/lib/cache.js"
    click StatusM "https://github.com/nodeshift/opossum/blob/main/lib/status.js"
    click SC "https://github.com/nodeshift/opossum/blob/main/lib/semaphore.js"
    click CBI "https://github.com/nodeshift/opossum/blob/main/index.js"
    click BIL "https://github.com/nodeshift/opossum/blob/main/test/browser/index.js"
    click SM "https://github.com/nodeshift/opossum/blob/main/test/state-test.js"
    click HC "https://github.com/nodeshift/opossum/blob/main/test/health-check-test.js"
    click VT "https://github.com/nodeshift/opossum/blob/main/test/volume-threshold-test.js"
    click CL "https://github.com/nodeshift/opossum/blob/main/test/circuit-shutdown-test.js"
    click Config "https://github.com/nodeshift/opossum/blob/main/config/webpack.config.js"

    %% Styles
    classDef interface fill:#f9f,stroke:#333,stroke-width:2px
    classDef core fill:#9cf,stroke:#333,stroke-width:2px
    classDef monitor fill:#ff9,stroke:#333,stroke-width:2px
    classDef event fill:#9f9,stroke:#333,stroke-width:2px
    classDef config fill:#f99,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        L1[Interface Components]:::interface
        L2[Core Components]:::core
        L3[Monitoring Components]:::monitor
        L4[Event Components]:::event
        L5[Configuration Components]:::config
    end
```
