# phaneesh/revolver architecture

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

- Interactive diagram: https://gitdiagram.com/phaneesh/revolver
- Repository: https://github.com/phaneesh/revolver

## Overview

##### Project type and purpose
- This is an open-source Dropwizard bundle (“dropwizard-revolver”) that lets you build downstream HTTP/HTTPS proxies with:
- Transparent callbacks (async workflows)
- A durable mailbox (polling for request/response status)
- Pluggable persistence (in-memory or Aerospike)
- Runtime features (circuit breakers via Hystrix, service discovery, dynamic config, request splitting, retries, tracing, metrics optimization)
- It also ships a small dashboard UI (static HTML/CSS/JS under src/main/resources/revolver/dashboard) for monitoring.

##### File structure
- Top‐level: pom.xml, README, Travis config.
- src/main/java/io/dropwizard/revolver: core code organized into packages:
- bundle (RevolverBundle)
- base, core (command infrastructure, models, context, exception helpers)
- discovery (service resolver, EndpointSpec)
- http (HTTP command, client factory, auth, API/service config)
- persistence (AeroSpikePersistenceProvider, InMemoryPersistenceProvider)
- callback (CallbackHandler, InlineCallbackHandler)
- resource (JAX-RS endpoints for mailbox, requests, callbacks, config, metadata)
- filters (RevolverRequestFilter)
- retry, splitting (strategy-based retry and request splitting)
- optimizer (metrics collection, config updater)
- util, tracing
- src/main/resources/revolver/dashboard: static UI assets.
- Tests mirror main packages.

##### Key insights from README
- You plug this bundle into any Dropwizard app by calling bootstrap.addBundle(new RevolverBundle<>() { … })
- You supply RevolverConfig (via YAML) and a PersistenceProvider implementation
- Bundle registers: commands + Hystrix circuit-breakers, mailbox polling endpoints, callback endpoints, dashboard resource

1. Dropwizard Application
– Your app’s Bootstrap & Environment
– Registers RevolverBundle
2. RevolverBundle
– Initializes:
- Core Command Framework (RevolverCommand, SimpleRevolverCommand)
- Service Discovery Module
- HTTP/HTTPS Command Module (RevolverHttpCommand)
- Persistence Module (InMemory or Aerospike)
- Callback Module
- Retry & Splitting Modules
- Optimizer Module (metrics collection + config updater)
- JAX-RS Resources (Mailbox, Request, Callback, Config, Metadata, Dashboard)
- Filters (RevolverRequestFilter)
3. External Services
– Downstream HTTP/HTTPS endpoints (e.g., mocky.io)
– Service discovery backends (Zookeeper via Curator if used)
4. Persistence Store
– In-memory or Aerospike
5. Client & Dashboard UI
– End users or other services call API endpoints (sync/async)
– Dashboard (static assets) polls Metadata & Config endpoints
b. Relationships & data flow
1. Client → HTTP Request → Dropwizard JAX-RS → RevolverRequestResource
2. RevolverRequestResource → RevolverCommandFactory → SimpleRevolverCommand
3. Command executes:
- ServiceResolver locates an endpoint
- RevolverHttpClientFactory builds HTTP client → sends request to external service
- Hystrix wraps call (CircuitBreaker, ThreadPool)
4. Response → persisted via PersistenceProvider → mailbox queue
5. If callback configured: CallbackHandler picks up response → forwards to callback URL
6. Client polls mailbox via RevolverMailboxResource → reads status from PersistenceProvider
7. OptimizerMetricsCollector gathers runtime metrics → OptimizerConfigUpdater tweaks RuntimeConfig (thread-pool sizes, timeouts)
8. Dashboard UI fetches metadata & status via RevolverMetadataResource & RevolverConfigResource
c. Architectural patterns & principles
- Bundle pattern (Dropwizard extension)
- Command pattern (RevolverCommand)
- Strategy pattern (splitting, retry, persistence provider, auth, service discovery)
- Circuit breaker pattern (Hystrix integration)
- Plugin/extensibility (PersistenceProvider, ServiceDiscoveryConfig, AuthConfig)
- MVC-style separation: resources (controllers) → core (services) → persistence
d. Key technologies & frameworks
- Dropwizard (JAX-RS, Jackson, Metrics)
- Apache Curator (service discovery via Zookeeper)
- Hystrix (circuit breaker, thread-pools, metrics)
- Aerospike (optional persistence)
- MsgPack & XML bundles (content negotiation)
- Static dashboard: Materialize CSS, JS

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client & UI"
        Client["Client / External Service"]:::external
        DashboardUI["Dashboard UI"]:::ui
    end

    subgraph "Dropwizard Application"
        Boot["Bootstrap & Environment"]
        Bundle["RevolverBundle"]:::core
    end

    subgraph "RevolverBundle Modules"
        subgraph "Core Command Framework"
            RCC["RevolverCommand"]:::core
            SRC["SimpleRevolverCommand"]:::core
        end
        subgraph "Service Discovery"
            SD["RevolverServiceResolver"]:::core
            CF["RevolverCommandFactory"]:::core
        end
        subgraph "HTTP Module"
            HC["RevolverHttpCommand"]:::core
            HCF["RevolverHttpClientFactory"]:::core
        end
        subgraph "Persistence Module"
            P["PersistenceProvider"]:::persistence
            InMemStore["InMemoryPersistenceProvider"]:::persistence
            ASStore["AeroSpikePersistenceProvider"]:::persistence
        end
        subgraph "Callback Module"
            CBH["CallbackHandler"]:::core
        end
        subgraph "Retry Module"
            RM["RevolverApiRetryConfig"]:::core
        end
        subgraph "Splitting Module"
            SM["SplitStrategy"]:::core
        end
        subgraph "Optimizer Module"
            OM["OptimizerMetricsCollector"]:::core
            CU["RevolverConfigUpdater"]:::core
        end
        subgraph "JAX-RS Resources"
            Req["RevolverRequestResource"]:::core
            Mail["RevolverMailboxResource"]:::core
            CallRes["RevolverCallbackResource"]:::core
            ConfigRes["RevolverConfigResource"]:::core
            MetaRes["RevolverMetadataResource"]:::core
        end
        Filter["RevolverRequestFilter"]:::core
    end

    subgraph "External Systems"
        ExtSvc["Downstream HTTP Service"]:::external
        ZK["Zookeeper"]:::external
    end

    subgraph "Persistence Store"
        InMem["InMemory Store"]:::persistence
        AS["Aerospike Store"]:::persistence
    end

    Client -->|"HTTP Req"| Req
    Req -->|"create cmd"| CF
    CF -->|"uses command"| SRC
    SRC -->|"resolve endpoint"| SD
    SRC -->|"dispatch HTTP"| HC
    HC -->|"uses client"| HCF
    HCF -->|"calls"| ExtSvc
    HCF -->|"Hystrix CircuitBreaker"| ExtSvc
    ExtSvc -->|"response"| HCF
    HCF -->|"persist response"| P
    P -->|"store to"| InMemStore
    P -->|"store to"| ASStore
    P -->|"mailbox queue"| Mail
    Mail -->|"poll status"| Mail
    CBH -->|"handle callback"| CallRes
    OM -->|"collect metrics"| CU
    CU -->|"update config"| Bundle
    DashboardUI -->|"poll metadata & config"| MetaRes
    Boot --> Bundle
    Bundle --> RCC
    Bundle --> SD
    Bundle --> HC
    Bundle --> P
    Bundle --> CBH
    Bundle --> RM
    Bundle --> SM
    Bundle --> OM
    Bundle --> Req
    Bundle --> Filter

    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef persistence fill:#fff3cd,stroke:#856404,color:#856404
    classDef ui fill:#e2e3e5,stroke:#6c757d,color:#6c757d

    click Bundle "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/RevolverBundle.java"
    click RCC "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/core/RevolverCommand.java"
    click SRC "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/core/SimpleRevolverCommand.java"
    click SD "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/discovery/RevolverServiceResolver.java"
    click CF "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/discovery/RevolverCommandFactory.java"
    click HC "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/http/RevolverHttpCommand.java"
    click HCF "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/http/RevolverHttpClientFactory.java"
    click P "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/persistence/PersistenceProvider.java"
    click InMemStore "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/persistence/InMemoryPersistenceProvider.java"
    click ASStore "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/persistence/AeroSpikePersistenceProvider.java"
    click CBH "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/callback/CallbackHandler.java"
    click RM "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/retry/RevolverApiRetryConfig.java"
    click SM "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/splitting/SplitStrategy.java"
    click OM "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/optimizer/OptimizerMetricsCollector.java"
    click CU "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/optimizer/RevolverConfigUpdater.java"
    click Req "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/resource/RevolverRequestResource.java"
    click Mail "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/resource/RevolverMailboxResource.java"
    click CallRes "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/resource/RevolverCallbackResource.java"
    click ConfigRes "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/resource/RevolverConfigResource.java"
    click MetaRes "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/resource/RevolverMetadataResource.java"
    click Filter "https://github.com/phaneesh/revolver/blob/master/src/main/java/io/dropwizard/revolver/filters/RevolverRequestFilter.java"
    click ZK "https://github.com/phaneesh/revolver/tree/master/src/main/java/io/dropwizard/revolver/discovery"
    click DashboardUI "https://github.com/phaneesh/revolver/tree/master/src/main/resources/revolver/dashboard"
    click Boot "https://github.com/phaneesh/revolver/blob/master/pom.xml"
```
