# haproxytech/client-native architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Go-library (“client-native”) exposing two main clients:
– Configuration Client: read/modify HAProxy config files.
– Runtime Client: send commands and parse output over HAProxy’s UNIX stats socket.
- It also provides pluggable subsystems for storage (maps, SSL certs, general files) and SPOE.
- It uses code generation (go-swagger, internal generators) to produce models and parsers.

##### High-Level Component Identification
A. Application (your code that imports client-native)
B. client_native.New(...) Builder (entrypoint)
C. Sub-clients & modules
1. Configuration Module
2. Runtime Module
3. Storage Module(s)
4. SPOE Module
D. Code Generation Tools (cmd/*, specification/*)
E. Autogenerated Models (models/*)
F. Config-Parser Library (config-parser/*)
G. Underlying HAProxy Interfaces
1. HAProxy Config File on disk
2. HAProxy UNIX Socket (stats socket)
3. HAProxy SPOE Socket/Protocol

##### Relationships & Data Flows
- Application → calls client_native.New(opts...)
- Builder selects and wires:
– Configuration.New(...) → uses configuration/ + config-parser to load/validate config file → reads/writes disk.
– runtime_api.New(...) → uses runtime/ to open UNIX socket → send commands, parse responses.
– storage.New(...) → filesystem abstraction for maps, certificates, general files.
– spoe.NewSpoe(...) → uses spoe/* to talk SPE/Agent.
- All sub-clients rely on shared Models (models/*), autogenerated from the Swagger spec in specification/*.
- Code generation tools (cmd/kubebuilder_marker_generator, cmd/struct_equal_generator, etc.) consume specification/*.yaml and produce code under models/, configuration/, config-parser/parsers, etc.

##### Architectural Patterns & Principles
- Modular design: clearly separated modules for config, runtime, storage, spoe.
- Builder/Options pattern: client is configured by passing Option functions.
- Code-generation pipeline: specification YAML → go-swagger + internal cmd/* tools → autogenerated code.
- Clean separation:
– “runtime” for live interactions
– “configuration” + “config-parser” for static file manipulation
– “storage” for caching artifacts
– “spoe” for event processing

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "Build-Time Codegen" 
    direction TB
    Spec["Specification (YAML)"]:::buildtime
    Tools["Code Generation Tools (cmd/)"]:::buildtime
    Models["Autogenerated Models (models/)"]:::buildtime
    Parsers["Generated Parsers (config-parser/)"]:::buildtime

    Spec -->|"feeds into"| Tools
    Tools --> Models
    Tools --> Parsers
  end

  subgraph "Client API & Runtime Modules"
    direction TB
    App["Application"]:::external
    Builder["client_native Builder"]:::runtime
    Config["Configuration Module"]:::runtime
    Parser["Config-Parser Library"]:::runtime
    RuntimeM["Runtime Module"]:::runtime
    Storage["Storage Module"]:::runtime
    SPOE["SPOE Module"]:::runtime

    App -->|"calls New(opts...)"| Builder
    Builder --> Config
    Builder --> RuntimeM
    Builder --> Storage
    Builder --> SPOE

    Config --> Parser
    Config --> Models
    RuntimeM --> Models
    Storage --> Models
    SPOE --> Models
  end

  subgraph "External HAProxy Interfaces" 
    direction TB
    Disk["HAProxy Config File on Disk"]:::external
    UnixSock["HAProxy UNIX Socket"]:::external
    SPOESock["HAProxy SPOE Socket"]:::external

    Config -->|"reads/writes"| Disk
    RuntimeM -->|"send commands"| UnixSock
    SPOE -->|"communicates over"| SPOESock
  end

  %% Click Events
  click App "https://github.com/haproxytech/client-native/blob/master/client_native.go"
  click Builder "https://github.com/haproxytech/client-native/blob/master/options/options.go"
  click Config "https://github.com/haproxytech/client-native/tree/master/configuration/"
  click Parser "https://github.com/haproxytech/client-native/tree/master/config-parser/"
  click RuntimeM "https://github.com/haproxytech/client-native/tree/master/runtime/"
  click Storage "https://github.com/haproxytech/client-native/tree/master/storage/"
  click SPOE "https://github.com/haproxytech/client-native/tree/master/spoe/"
  click Tools "https://github.com/haproxytech/client-native/tree/master/cmd/"
  click Spec "https://github.com/haproxytech/client-native/tree/master/specification/"
  click Models "https://github.com/haproxytech/client-native/tree/master/models/"

  %% Styles
  classDef buildtime fill:#F3E5F5,stroke:#4A148C,color:#4A148C;
  classDef runtime fill:#E3F2FD,stroke:#0D47A1,color:#0D47A1;
  classDef external fill:#FFF3E0,stroke:#E65100,color:#E65100;
```
