# spectolabs/hoverfly architecture

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

- Interactive diagram: https://gitdiagram.com/spectolabs/hoverfly
- Repository: https://github.com/spectolabs/hoverfly

## Overview

##### Project Type and Purpose
- This is an open-source API simulation tool (Hoverfly) written in Go. It comprises two primary deliverables:
a. A long-running “core” service that acts as an HTTP proxy and exposes a REST-style admin API.
b. A CLI client (hoverctl) that invokes the core’s admin API to configure, control and query simulations.
- Use cases include capturing live HTTP traffic, simulating API endpoints with delays/matchers/middleware, and exporting/importing simulation definitions.

##### High-Level File Structure & Architectural Clues
- Directories:
- core/ – the headless proxy + REST API server
- hoverctl/ – the CLI front-end
- docs/, examples/, functional-tests/ – documentation, usage examples and end-to-end tests
- core/ is organized by feature layers: HTTP handlers (core/handlers), business logic (core/modes, core/matching, core/cache, core/templating, core/postserveactions), persistence (core/cache, core/journal), authentication (core/authentication), metrics and middleware.
- hoverctl/ contains command definitions (cobra-style), client wrappers (hoverctl/wrapper) that talk to the core via HTTP, and config management.

##### Main Components
A. CLI Client (hoverctl)
- hoverctl commands → HTTP calls → Core Admin API
- Configuration loader → selects target hoverfly instance
B. Core Service
1. HTTP Layer
- Proxy Listener (captures/forwards client traffic)
- Admin API Listener (CRUD on simulations, modes, cache, journal, metrics)
2. Business Logic
- Modes Engine (capture/simulate/diff/modify/spy/synthesize)
- Matching Engine (match incoming requests to simulation pairs)
- Delay Generator (static, log-normal, random)
- Templating & DataSources
- Post-Serve Actions (callbacks to arbitrary HTTP endpoints)
- Middleware Module (local binaries or remote services)
3. Persistence & State
- In-memory & BoltDB caches
- Journal store & indexing
- Simulation definitions (in memory, exportable as JSON)
4. Cross-cutting Services
- Authentication & Authorization (JWT or custom storage backend)
- CORS handling
- Metrics collection & exposition (Prometheus style)
- TLS/Certificates management
C. External Integrations
- Upstream real APIs (in capture mode)
- Middleware services (local scripts, remote HTTP services)
- Post-serve webhook endpoints

##### Component Interactions & Data Flows
- In capture mode: Proxy → Upstream API → Response → Save to Journal/Cache
- In simulate mode: Proxy → Matching Engine → Cached Response → Delay & Templating → Response
- Middleware & Post-serve callbacks may intercept/modify both directions.
- Core persists journal events and cache items; these backends (memory or BoltDB) feed the Matching and Journal Index modules.

##### Architectural Patterns & Design Principles
- Layered (Transport → Handlers → Business Logic → Persistence)
- Hexagonal/Ports-and-Adapters for Middleware & DataSources (core/interfaces + core/templating)
- Plugin-style extensibility for middleware and post-serve actions
- Separation of concerns between capture vs simulate vs modify vs diff modes
- Single binary deployable service, stateless except for optional BoltDB files

##### Additional Deployment & Extension Points
- How examples or functional-tests spin up the core service and execute HTTP calls.
- Extensibility hooks: storage backends, middleware adapters, templating datasources.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hoverctl CLI"
        HC["hoverctl (CLI Client)"]:::cli
        CMD["Commands (cobra CLI)"]:::cli
        CONF["Config Loader"]:::cli
        WRAP["HTTP Wrappers"]:::cli
    end

    subgraph "Core Service"
        subgraph "HTTP Layer"
            PROXY["Proxy Listener\n(port 8080)"]:::http
            HTTP["Admin API Listener\n(port 8888)"]:::http
        end
        subgraph "Business Logic"
            MODES["Modes Engine"]:::biz
            MATCH["Matching Engine"]:::biz
            DELAY["Delay Generator"]:::biz
            TEMP["Templating & DataSources"]:::biz
            ACTION["Post-Serve Actions"]:::biz
            MIDDLE["Middleware Module"]:::biz
        end
        subgraph "Persistence & State"
            CACHE["Cache\n(in-memory & BoltDB)"]:::state
            JOURNAL["Journal Store\n& Index"]:::state
            MODELS["Simulation Definitions"]:::state
        end
        subgraph "Cross-cutting Services"
            AUTH["Authentication & Authorization"]:::cross
            CORS["CORS Handling"]:::cross
            METRICS["Metrics Collection"]:::cross
            TLS["TLS / Cert Management"]:::cross
        end
    end

    subgraph "External Integrations"
        UA["Upstream Real APIs"]:::external
        MW["Middleware Services"]:::external
        WH["Post-Serve Webhooks"]:::external
    end

    HC --> CMD
    HC --> CONF
    HC --> WRAP
    WRAP -->|"invokes Admin API"| HTTP

    HTTP -->|"serves Admin API"| WRAP

    PROXY --> MATCH
    MATCH --> DELAY
    DELAY --> TEMP
    TEMP --> ACTION
    ACTION --> PROXY

    PROXY --> UA
    PROXY --> MW
    ACTION --> WH
    MIDDLE --> MW

    PROXY -->|"save event"| JOURNAL
    PROXY -->|"save cache"| CACHE
    CACHE --> MATCH
    JOURNAL --> MATCH

    PROXY -->|"Client Traffic"| MATCH
    MATCH -->|"Find Response"| PROXY

    HC -->|"HTTP/JSON"| HTTP

    TLS --> HTTP
    TLS --> PROXY
    AUTH --> HTTP
    CORS --> HTTP
    METRICS --> HTTP

    click main_go "https://github.com/spectolabs/hoverfly/blob/master/hoverctl/main.go"
    click CMD "https://github.com/spectolabs/hoverfly/tree/master/hoverctl/cmd/"
    click CONF "https://github.com/spectolabs/hoverfly/blob/master/hoverctl/configuration/config.go"
    click CONF "https://github.com/spectolabs/hoverfly/blob/master/hoverctl/configuration/target.go"
    click WRAP "https://github.com/spectolabs/hoverfly/tree/master/hoverctl/wrapper/"
    click PROXY "https://github.com/spectolabs/hoverfly/blob/master/core/listener.go"
    click PROXY "https://github.com/spectolabs/hoverfly/blob/master/core/proxy.go"
    click HTTP "https://github.com/spectolabs/hoverfly/blob/master/core/admin.go"
    click HTTP "https://github.com/spectolabs/hoverfly/blob/master/core/http.go"
    click HTTP "https://github.com/spectolabs/hoverfly/tree/master/core/handlers/"
    click MODES "https://github.com/spectolabs/hoverfly/tree/master/core/modes/"
    click MATCH "https://github.com/spectolabs/hoverfly/tree/master/core/matching/"
    click DELAY "https://github.com/spectolabs/hoverfly/tree/master/core/delay/"
    click TEMP "https://github.com/spectolabs/hoverfly/tree/master/core/templating/"
    click ACTION "https://github.com/spectolabs/hoverfly/tree/master/core/action/"
    click MIDDLE "https://github.com/spectolabs/hoverfly/tree/master/core/middleware/"
    click CACHE "https://github.com/spectolabs/hoverfly/tree/master/core/cache/"
    click JOURNAL "https://github.com/spectolabs/hoverfly/tree/master/core/journal/"
    click MODELS "https://github.com/spectolabs/hoverfly/tree/master/core/models/"
    click AUTH "https://github.com/spectolabs/hoverfly/tree/master/core/authentication/"
    click CORS "https://github.com/spectolabs/hoverfly/tree/master/core/cors/"
    click METRICS "https://github.com/spectolabs/hoverfly/tree/master/core/metrics/"
    click TLS "https://github.com/spectolabs/hoverfly/tree/master/core/certs/"

    classDef cli fill:#D6EAF8,stroke:#3498DB,color:#1B2631
    classDef http fill:#D5F5E3,stroke:#27AE60,color:#1B2631
    classDef biz fill:#FCF3CF,stroke:#F1C40F,color:#1B2631
    classDef state fill:#FADBD8,stroke:#E74C3C,color:#1B2631
    classDef cross fill:#E8DAEF,stroke:#8E44AD,color:#1B2631
    classDef external fill:#F2F4F4,stroke:#7B7D7D,color:#1B2631
    classDef core stroke:#34495E,stroke-width:2px
```
