# haproxytech/dataplaneapi architecture

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

- Interactive diagram: https://gitdiagram.com/haproxytech/dataplaneapi
- Repository: https://github.com/haproxytech/dataplaneapi

## Overview

##### Main components
- API Server: This is the central HTTP/HTTPS server (listening on configurable ports, with TLS options available) that receives and handles requests from clients (see “cmd/dataplaneapi/main.go” and “handlers” packages).
- Handlers and Operations Layer: A significant portion of the code (under “handlers” and “operations”) implements business logic. Each “operation” (for example, for ACLs, backends, frontends, map updates, etc.) is responsible for interpreting API commands, validating configuration changes, and constructing the new HAProxy configuration.
- Configuration Manager & FS Interaction: The “configuration” and “storage” directories indicate components that manage reading/writing HAProxy’s configuration files, map files, SSL certificates, and other auxiliary resources. They ensure persistence and allow for backups, reload retention, as well as migration between configuration versions.
- HAProxy Integration & Command Execution: The project wraps around the HAProxy binary and external commands. It invokes reload, restart, and validation commands against the running HAProxy process. The “haproxy” directory and parts of the runtime logic (e.g., “runtime/serve.go”) encapsulate this integration.
- Service Discovery: The “discovery” directory provides support for integrating with external service registries (like AWS and Consul) to automatically update HAProxy configuration.
- Auxiliary and Debug Components: There are command line tools (see “client-native”, “runtime/commands”) and a command socket for debugging and system introspection.
- Testing Framework: Extensive end-to-end tests (inside “e2e”) and unit tests in “test” reflect robust automated testing practices.

##### Relationships and Interactions
- Client requests enter the system through the API Server. Requests are routed to appropriate handler components.
- The handlers call into the operations layer which enforces business rules and interacts with the configuration manager.
- Updated configuration is written to the file system and/or communicated via shells/command calls to trigger HAProxy reloads or restarts.
- A background monitoring or runtime layer manages inotify watchers and handles transactions, ensuring changes are consistent across stored configurations.
- Service discovery components run in parallel to update configuration based on dynamic changes from external services.

##### Architectural Patterns and Design Principles
- Layered Architecture: The clear separation between API serving, business logic (handlers/operations), and integration with external systems (HAProxy, file systems, service discovery) emphasizes separation of concerns.
- Command Pattern: The operations packages act as builders and invokers for specific commands (e.g., creating, editing, and deleting HAProxy configuration fragments).
- Modular Design: Having separate directories for each configuration domain (ACL, backend, frontend, log, spoe, etc.) allows independent evolution and testing.
- Transaction and State Management: There is careful handling of configuration transactions, backup retention and migration (see “operations”, “transactions” directories), ensuring HAProxy’s high availability.

##### Relevant Technologies and Frameworks
- The project is built in Go (note the numerous “*.go” files and use of go modules).
- Integration with HAProxy is a core requirement, and the API wraps around HAProxy’s configurations and reload logic.
- External service integrations (e.g., AWS, Consul) for service discovery are highlighted.
- Testing frameworks: Use of BATS for end-to-end testing can be indicated, as seen in the “e2e” directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    client["Client"]:::client
    api["API Server\n(HTTP/HTTPS)"]:::api
    client -->|"request"| api

    subgraph "Business Logic"
        handlers["Handlers"]:::business
        ops["Operations"]:::business
    end
    api -->|"routes_to"| handlers
    handlers -->|"invokes"| ops

    subgraph "Configuration Management"
        configM["Config Manager"]:::config
        storage["Storage"]:::config
        storageT["StorageType"]:::config
    end
    ops -->|"updates"| configM
    configM -->|"uses"| storage
    storage -->|"defines"| storageT

    subgraph "HAProxy Integration"
        haproxyExec["HAProxy Executor"]:::haprox
        runtimeServe["Runtime Serve"]:::haprox
    end
    ops -->|"triggers"| haproxyExec
    ops -->|"signals"| runtimeServe

    discovery["Service Discovery"]:::discovery
    discovery -->|"feeds"| configM

    subgraph "Debug & CLI Tools"
        runtimeCmd["Runtime Commands"]:::debug
        clientNative["Client Native"]:::debug
    end
    api -->|"debug_route"| runtimeCmd
    api -->|"debug_route"| clientNative

    subgraph "Testing Framework"
        e2e["E2E Tests"]:::testing
        unitTest["Unit Tests"]:::testing
    end
    e2e -->|"tests"| api
    unitTest -->|"tests"| api

    click api "https://github.com/haproxytech/dataplaneapi/blob/master/cmd/dataplaneapi/main.go"
    click handlers "https://github.com/haproxytech/dataplaneapi/tree/master/handlers"
    click ops "https://github.com/haproxytech/dataplaneapi/tree/master/operations"
    click configM "https://github.com/haproxytech/dataplaneapi/tree/master/configuration"
    click storage "https://github.com/haproxytech/dataplaneapi/tree/master/storage"
    click storageT "https://github.com/haproxytech/dataplaneapi/tree/master/storagetype"
    click haproxyExec "https://github.com/haproxytech/dataplaneapi/tree/master/haproxy"
    click runtimeServe "https://github.com/haproxytech/dataplaneapi/blob/master/runtime/serve.go"
    click discovery "https://github.com/haproxytech/dataplaneapi/tree/master/discovery"
    click runtimeCmd "https://github.com/haproxytech/dataplaneapi/tree/master/runtime/commands"
    click clientNative "https://github.com/haproxytech/dataplaneapi/tree/master/client-native"
    click e2e "https://github.com/haproxytech/dataplaneapi/tree/master/e2e"
    click unitTest "https://github.com/haproxytech/dataplaneapi/tree/master/test"

    classDef api fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px,color:#0D47A1;
    classDef business fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px,color:#2E7D32;
    classDef config fill:#FFECB3,stroke:#F57F17,stroke-width:2px,color:#F57F17;
    classDef haprox fill:#FFCDD2,stroke:#C62828,stroke-width:2px,color:#C62828;
    classDef discovery fill:#D1C4E9,stroke:#512DA8,stroke-width:2px,color:#512DA8;
    classDef debug fill:#F0F4C3,stroke:#827717,stroke-width:2px,color:#827717;
    classDef testing fill:#B2EBF2,stroke:#00796B,stroke-width:2px,color:#00796B;
    classDef client fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px,color:#8E24AA;
    class client client;
    class api api;
    class handlers,ops business;
    class configM,storage,storageT config;
    class haproxyExec,runtimeServe haprox;
    class discovery discovery;
    class runtimeCmd,clientNative debug;
    class e2e,unitTest testing;
```
