# department-of-veterans-affairs/breakers architecture

> Architecture diagram of the GitHub repository department-of-veterans-affairs/breakers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/department-of-veterans-affairs/breakers
- Repository: https://github.com/department-of-veterans-affairs/breakers

## Overview

##### Main Components
a. Application (Ruby code using Faraday)
b. Faraday HTTP Client
c. Breakers Middleware (the gem itself)
- Breakers::Client
- Breakers::Service
- Breakers::Outage / OutageException
- Breakers::UptimeMiddleware
- Plugins & Logger (optional extension points)
d. Redis (data store for metrics & outages)
e. Downstream Backend Service (the actual HTTP service being called)

##### Relationships and Data Flows
- Request Flow (HTTP request path):
Application → Faraday → Breakers Middleware → (If service up) → Backend Service → Breakers → Application
- Metrics Flow (to Redis):
Breakers Middleware intercepts response or error → records success or error counters in Redis
- Outage Detection & Storage:
Breakers::Client periodically examines counts in Redis → if error rate > threshold → creates Outage record → writes to Redis sorted set → may raise Breakers::OutageException
- Recovery Probes:
While in outage, Breakers allows a “probe” request every N seconds → if success → clears outage in Redis → resumes normal flow
- Plugins & Logging Events:
On each error, success, outage begin/end → Breakers invokes plugin hooks & optional Logger

##### Architectural Patterns and Principles
- Circuit-Breaker Pattern via pluggable Faraday Middleware
- Separation of concerns: request handling vs. metrics store vs. outage logic vs. plugin interface
- Redis used as a time-series store (per-minute keys) and sorted set for outages
- Dependency injection: Services (with request_matcher), Client (with redis_connection, plugins, logger)

##### Technologies & Frameworks
- Ruby, Faraday (HTTP client library)
- Redis (in-memory key-value store)
- RSpec for tests, Rake, Bundler, RuboCop for linting
- GitHub Actions / Travis CI for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    Application["Application Code"]:::application
    Application -->|HTTP request| Faraday["Faraday HTTP Client"]:::external

    %% Breakers Middleware Layer
    subgraph "Breakers Middleware"
        direction TB
        BrkEntry["Breakers (lib/breakers.rb)"]:::middleware
        BrkVersion["Version Constant (lib/breakers/version.rb)"]:::middleware
        BrkClient["Breakers::Client"]:::middleware
        BrkService["Breakers::Service"]:::middleware
        BrkOutage["Breakers::Outage"]:::middleware
        BrkException["Breakers::OutageException"]:::middleware
        BrkUptime["Breakers::UptimeMiddleware"]:::middleware
        Plugin["Example Plugin"]:::component
    end

    Faraday -->|invoke middleware| BrkEntry
    BrkEntry --> BrkClient
    BrkClient --> BrkService
    BrkService --> BrkUptime
    BrkUptime --> BrkOutage
    BrkOutage --> BrkException
    BrkUptime --> Plugin

    %% Backend Service
    BrkService -->|if service up| Backend["Backend HTTP API"]:::external
    Backend -->|response/error| BrkService

    %% Redis Metrics Store
    BrkOutage -->|write outage| Redis["Redis Metrics Store"]:::datastore
    BrkService -->|record success/error| Redis

    %% Plugin callbacks
    BrkException -->|on outage| Plugin
    BrkService -->|on success/error| Plugin

    %% Click Events
    click BrkClient "https://github.com/department-of-veterans-affairs/breakers/blob/master/lib/breakers/client.rb"
    click BrkService "https://github.com/department-of-veterans-affairs/breakers/blob/master/lib/breakers/service.rb"
    click BrkOutage "https://github.com/department-of-veterans-affairs/breakers/blob/master/lib/breakers/outage.rb"
    click BrkException "https://github.com/department-of-veterans-affairs/breakers/blob/master/lib/breakers/outage_exception.rb"
    click BrkUptime "https://github.com/department-of-veterans-affairs/breakers/blob/master/lib/breakers/uptime_middleware.rb"
    click BrkEntry "https://github.com/department-of-veterans-affairs/breakers/blob/master/lib/breakers.rb"
    click BrkVersion "https://github.com/department-of-veterans-affairs/breakers/blob/master/lib/breakers/version.rb"
    click Plugin "https://github.com/department-of-veterans-affairs/breakers/blob/master/spec/example_plugin.rb"

    %% Styles
    classDef application fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1;
    classDef middleware fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef component fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef datastore fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
    classDef external fill:#FFEBEE,stroke:#E53935,color:#B71C1C;
```
