# fortio/fortio architecture

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

- Interactive diagram: https://gitdiagram.com/fortio/fortio
- Repository: https://github.com/fortio/fortio

## Overview

##### Main Components
- CLI & Launcher: The top-level commands (main.go, cli/ directory) that parse command-line arguments to start the load test, echo server, or both.
- Load Generators: Components for generating load in various protocols. These include:
– HTTP load generation (fhttp/)
– gRPC load generation (fgrpc/ and jrpc/)
– TCP (tcprunner/) and UDP (udprunner/)
– Additional support for curl-like fetching (fcurl/)
- Server & Web UI: The server process (echosrv/, ui/ directories, rapi/ handlers) that serves a web UI, REST endpoints (for triggering tests, stopping tests, retrieving reports) and has support for additional server side features (like echoing requests, DEBUG endpoints, multi-proxy functionality).
- Supporting Libraries: Utility packages for network handling (fnet/), dynamic flags (dflag/), logging (log/), versioning (version/) and histogram/stats (stats/, histogram/). These provide the core building blocks for load measurement, metrics gathering, logging and configuration.
- CI/CD and Packaging: Infrastructure for building, testing, containerizing, and packaging Fortio (e.g., Dockerfile variants, .circleci/, .github/, debian/).
- Scripting Component: The “grol” scripting language which is embedded (grol/), allowing users to write scripts for interactive tests.

##### Relationships and Data Flow
- The CLI and server bootstrap the application and then call into the core libraries.
- The load generators invoke HTTP/gRPC/TCP/UDP routines from fhttp, fgrpc, tcprunner, and udprunner respectively. These modules handle the actual load and record performance metrics.
- The measured results (latency histograms, percentiles, response codes) are aggregated by the statistics/histogram modules and then optionally exposed via the web UI or saved as JSON files.
- The web server (running on port 8080 by default) provides a UI, acts as a proxy (via multi-target forwarding and TCP proxies), and also exposes debugging endpoints.
- Optional REST endpoints (under /fortio/rest/) allow remote triggering, stopping, and status queries for load runs.
- Logging and dynamic flag configuration are used across components to allow for runtime adjustments and structured logging.

##### Architectural Patterns & Design Principles
- Modular/Pipeline Design: Each protocol-specific load generator is isolated in its own package while sharing common libraries for metrics and configuration.
- Separation of Concerns: There is a clear distinction between the CLI interface, load generation logic, and the web/REST server.
- Embeddability: Many components, such as the load generation libraries, are designed to be reused/integrated by other projects.
- CI/CD & Packaging: Use of Dockerfiles, GitHub workflows, and CircleCI to support automated testing, building, and packaging.
- Lightweight Design: Fortio is designed for high performance and low dependency overhead (e.g., using a specialized HTTP client in fhttp).

##### Key Technologies, Frameworks, and Tools
- Go Language – central to all components.
- Docker – many Dockerfiles and container images are provided.
- gRPC and HTTP/1.1 (with optional HTTP/2 via -h2 flag) support.
- CI/CD configurations (.circleci, .github) indicate integration with CircleCI and Dependabot.
- Linux packaging (debian/) for distributing binaries.
- Embedded web UI using HTML, CSS, and JavaScript for result graphing.

- Do not oversimplify: even if a component seems “small” (e.g., the logger module), include it as an essential piece because it is used across all parts of the system.
- External dependencies, such as TLS certificate handling for secure connections and external tools like Homebrew or Docker Hub.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level: CLI & Server Bootstrap
    subgraph "Bootstrap Layer"
        CLI["CLI/Server Bootstrap"]:::bootstrap
    end

    %% Load Generators Layer
    subgraph "Load Generators"
        HTTP["HTTP Load Generator"]:::load
        GRPC["gRPC Load Generator"]:::load
        TCP["TCP Load Generator"]:::load
        UDP["UDP Load Generator"]:::load
        CURL["CURL-like Fetcher"]:::load
    end

    %% Metrics & Histogram Aggregation Layer
    subgraph "Metrics & Aggregation"
        METRICS["Metrics & Histogram Aggregation"]:::metrics
    end

    %% Server & Web UI Layer
    subgraph "Server & UI"
        WEB["Server & Web UI"]:::server
    end

    %% Utility Libraries (shared among components)
    subgraph "Utility Libraries"
        UTILS["Utility Libraries"]:::utils
    end

    %% Scripting Engine
    subgraph "Scripting"
        SCRIPT["Scripting Engine"]:::script
    end

    %% CI/CD and Packaging
    subgraph "CI/CD & Packaging"
        CICD["CI/CD and Packaging"]:::cicd
    end

    %% Data Flow Connections
    CLI -->|"initiate_load"| HTTP
    CLI -->|"initiate_load"| GRPC
    CLI -->|"initiate_load"| TCP
    CLI -->|"initiate_load"| UDP
    CLI -->|"initiate_load"| CURL

    HTTP -->|"record_metrics"| METRICS
    GRPC -->|"record_metrics"| METRICS
    TCP  -->|"record_metrics"| METRICS
    UDP  -->|"record_metrics"| METRICS
    CURL -->|"record_metrics"| METRICS

    METRICS -->|"display_results"| WEB

    CLI ---|"uses"| UTILS
    HTTP ---|"uses"| UTILS
    GRPC ---|"uses"| UTILS
    TCP  ---|"uses"| UTILS
    UDP  ---|"uses"| UTILS
    CURL ---|"uses"| UTILS
    METRICS ---|"uses"| UTILS
    WEB ---|"uses"| UTILS

    SCRIPT ---|"enhances"| CLI
    SCRIPT ---|"can_invoke"| HTTP

    CICD ---|"builds_and_tests"| CLI
    CICD ---|"builds_and_tests"| WEB
    CICD ---|"builds_and_tests"| HTTP
    CICD ---|"builds_and_tests"| GRPC
    CICD ---|"builds_and_tests"| TCP
    CICD ---|"builds_and_tests"| UDP
    CICD ---|"builds_and_tests"| CURL
    CICD ---|"builds_and_tests"| METRICS

    %% Click Events for CLI & Launcher
    click CLI "https://github.com/fortio/fortio/blob/master/main.go"
    click CLI "https://github.com/fortio/fortio/blob/master/cli/fortio_main.go"

    %% Click Events for HTTP Load Generator
    click HTTP "https://github.com/fortio/fortio/blob/master/fhttp/httprunner.go"
    click HTTP "https://github.com/fortio/fortio/blob/master/fhttp/http_server.go"

    %% Click Events for gRPC Load Generator
    click GRPC "https://github.com/fortio/fortio/blob/master/fgrpc/grpcrunner.go"
    click GRPC "https://github.com/fortio/fortio/blob/master/jrpc/jrpcClient.go"
    click GRPC "https://github.com/fortio/fortio/blob/master/jrpc/jrpcServer.go"

    %% Click Event for TCP Load Generator
    click TCP "https://github.com/fortio/fortio/blob/master/tcprunner/tcprunner.go"

    %% Click Event for UDP Load Generator
    click UDP "https://github.com/fortio/fortio/blob/master/udprunner/udprunner.go"

    %% Click Event for CURL-like Fetcher
    click CURL "https://github.com/fortio/fortio/blob/master/fcurl/fcurl.go"

    %% Click Events for Server & Web UI
    click WEB "https://github.com/fortio/fortio/blob/master/echosrv/echo.go"
    click WEB "https://github.com/fortio/fortio/tree/master/ui/"
    click WEB "https://github.com/fortio/fortio/blob/master/rapi/restHandler.go"

    %% Click Events for Metrics & Histogram Aggregation
    click METRICS "https://github.com/fortio/fortio/blob/master/stats/stats.go"
    click METRICS "https://github.com/fortio/fortio/blob/master/histogram/main.go"

    %% Click Events for Utility Libraries
    click UTILS "https://github.com/fortio/fortio/blob/master/fnet/network.go"
    click UTILS "https://github.com/fortio/fortio/blob/master/dflag/dflag.go"
    click UTILS "https://github.com/fortio/fortio/blob/master/log/logger.go"
    click UTILS "https://github.com/fortio/fortio/blob/master/version/version.go"

    %% Click Event for Scripting Engine
    click SCRIPT "https://github.com/fortio/fortio/blob/master/grol/grol.go"

    %% Click Events for CI/CD and Packaging
    click CICD "https://github.com/fortio/fortio/tree/master/.circleci/"
    click CICD "https://github.com/fortio/fortio/tree/master/.github/"
    click CICD "https://github.com/fortio/fortio/tree/master/debian/"
    click CICD "https://github.com/fortio/fortio/tree/master/Dockerfile"

    %% Styles
    classDef bootstrap fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef load fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef server fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef metrics fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef utils fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef script fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef cicd fill:#87CEFA,stroke:#333,stroke-width:2px;
```
