# essentialkaos/go-zabbix architecture

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

- Interactive diagram: https://gitdiagram.com/essentialkaos/go-zabbix
- Repository: https://github.com/essentialkaos/go-zabbix

## Overview

This repository is a small, single-purpose Go library rather than a multi-service system. Its only runtime responsibility is to let another Go program send metric data to a Zabbix Server compatible with versions 3.x through 6.x.

The main entry point is the `zabbix` package itself, centered in `zabbix.go`. That file likely exposes the user-facing API for constructing requests, submitting metrics, and handling results. An external application imports this package and calls into it directly; there is no standalone daemon or web server in the repo.

`protocol.go` is the core internal boundary. It appears to own the Zabbix wire-format details: request/message framing, serialization of metric payloads, and parsing of the server’s response. Architecturally, this is the layer that separates the public API from the network protocol specifics.

The data flow is straightforward: caller code provides metric name/value/host-style inputs, the library converts them into Zabbix sender protocol messages, sends them to a Zabbix Server, and returns success/failure information from the server response. The only external runtime dependency is a reachable Zabbix Server.

There is no persistence layer, queue, or database. Any state is ephemeral and local to the request/connection lifecycle. That makes the package stateless from an architecture-diagram perspective.

`zabbix_test.go` and `example_test.go` define the behavioral contract for the API and serve as usage documentation. These tests are the best indicator of public-facing semantics and should be treated as the validation boundary for the package.

`fuzz.go` plus the large `testdata/corpus` directory show that protocol robustness is important. This subsystem exists to hammer the parser/encoder with malformed or edge-case inputs, which is especially relevant for a network protocol library.

The repository is organized with standard Go module tooling (`go.mod`, `go.sum`) and a `Makefile` for local automation. There are no custom build artifacts or generated source trees visible.

CI and quality tooling are part of the repo’s operational boundary: GitHub Actions runs tests, CodeQL analysis, and documentation generation (`ci.yml`, `codeql.yml`, `godoc.yml`). A typo checker config (`.typos.toml`) also indicates lightweight repo hygiene checks.

For an architecture diagram, the important boxes are: consuming Go application, `zabbix` library API, internal protocol encoder/decoder, network connection to Zabbix Server, and the test/fuzz toolchain around the protocol layer.

Main entry points: [`zabbix.go`](https://github.com/essentialkaos/go-zabbix/blob/master/zabbix.go) (zabbix pkg), [`protocol.go`](https://github.com/essentialkaos/go-zabbix/blob/master/protocol.go) (Protocol), [`.github/workflows/ci.yml`](https://github.com/essentialkaos/go-zabbix/blob/master/.github/workflows/ci.yml) (CI workflows), [`zabbix_test.go`](https://github.com/essentialkaos/go-zabbix/blob/master/zabbix_test.go) (API tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_consumer["Go app<br/>caller"]
  node_zabbix_api["zabbix pkg<br/>public API<br/>[zabbix.go]"]
  node_protocol["Protocol<br/>wire format<br/>[protocol.go]"]
  node_request_build["Build request<br/>payload assembly<br/>[protocol.go]"]
  node_encode["Encode msg<br/>serialization<br/>[protocol.go]"]
  node_send["Send data<br/>network I/O<br/>[protocol.go]"]
  node_parse["Parse reply<br/>response parsing<br/>[protocol.go]"]
  node_server[("Zabbix Server<br/>remote endpoint")]
  node_result["Result<br/>status<br/>[zabbix.go]"]
end

subgraph group_quality["Validation"]
  node_tests["API tests<br/>behavioral tests<br/>[zabbix_test.go]"]
  node_examples["Example docs<br/>usage examples<br/>[example_test.go]"]
  node_fuzz["Fuzz harness<br/>robustness tests<br/>[fuzz.go]"]
  node_corpus["Corpus<br/>fuzz inputs"]
end

subgraph group_ops["Repo tooling"]
  node_go_mod["Module<br/>[go.mod]"]
  node_go_sum["Checksums<br/>dependency lock<br/>[go.sum]"]
  node_makefile["Makefile<br/>automation"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_ci["CI workflows<br/>automation<br/>[ci.yml]"]
  node_codeql["CodeQL<br/>security scan<br/>[codeql.yml]"]
  node_godoc["Docgen<br/>docs workflow<br/>[godoc.yml]"]
  node_typos["Typos config<br/>lint config<br/>[.typos.toml]"]
end

node_consumer -->|"import/call"| node_zabbix_api
node_zabbix_api -->|"assemble"| node_request_build
node_request_build -->|"format"| node_encode
node_encode -->|"transmit"| node_send
node_send -->|"connect"| node_server
node_server -->|"reply"| node_parse
node_parse -->|"return"| node_result
node_zabbix_api -->|"delegates"| node_protocol
node_protocol -->|"owns"| node_request_build
node_protocol -->|"owns"| node_encode
node_protocol -->|"owns"| node_parse
node_tests -->|"validates"| node_zabbix_api
node_examples -->|"documents"| node_zabbix_api
node_fuzz -->|"targets"| node_protocol
node_corpus -->|"seeds"| node_fuzz
node_go_mod -->|"module"| node_zabbix_api
node_go_sum -->|"pins"| node_go_mod
node_makefile -->|"runs"| node_tests
node_ci -->|"checks"| node_tests
node_ci -->|"generates"| node_godoc
node_ci -->|"scans"| node_codeql
node_typos -->|"checks"| node_readme

click node_zabbix_api "https://github.com/essentialkaos/go-zabbix/blob/master/zabbix.go"
click node_protocol "https://github.com/essentialkaos/go-zabbix/blob/master/protocol.go"
click node_request_build "https://github.com/essentialkaos/go-zabbix/blob/master/protocol.go"
click node_encode "https://github.com/essentialkaos/go-zabbix/blob/master/protocol.go"
click node_send "https://github.com/essentialkaos/go-zabbix/blob/master/protocol.go"
click node_parse "https://github.com/essentialkaos/go-zabbix/blob/master/protocol.go"
click node_result "https://github.com/essentialkaos/go-zabbix/blob/master/zabbix.go"
click node_tests "https://github.com/essentialkaos/go-zabbix/blob/master/zabbix_test.go"
click node_examples "https://github.com/essentialkaos/go-zabbix/blob/master/example_test.go"
click node_fuzz "https://github.com/essentialkaos/go-zabbix/blob/master/fuzz.go"
click node_corpus "https://github.com/essentialkaos/go-zabbix/tree/master/testdata/corpus"
click node_go_mod "https://github.com/essentialkaos/go-zabbix/blob/master/go.mod"
click node_go_sum "https://github.com/essentialkaos/go-zabbix/blob/master/go.sum"
click node_makefile "https://github.com/essentialkaos/go-zabbix/tree/master/Makefile"
click node_readme "https://github.com/essentialkaos/go-zabbix/blob/master/README.md"
click node_ci "https://github.com/essentialkaos/go-zabbix/blob/master/.github/workflows/ci.yml"
click node_codeql "https://github.com/essentialkaos/go-zabbix/blob/master/.github/workflows/codeql.yml"
click node_godoc "https://github.com/essentialkaos/go-zabbix/blob/master/.github/workflows/godoc.yml"
click node_typos "https://github.com/essentialkaos/go-zabbix/blob/master/.typos.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_consumer,node_zabbix_api,node_protocol,node_request_build,node_encode,node_send,node_parse,node_server,node_result toneBlue
class node_tests,node_examples,node_fuzz,node_corpus toneAmber
class node_go_mod,node_go_sum,node_makefile,node_readme,node_ci,node_codeql,node_godoc,node_typos toneMint
```

## Components

### Core library

Public API and protocol implementation for sending metrics to Zabbix.

- **Go app**: caller · External Go program importing the library and sending metrics.
- [zabbix pkg](https://github.com/essentialkaos/go-zabbix/blob/master/zabbix.go): public API · User-facing package entry point for constructing and sending metric submissions. · `zabbix.go`
- [Protocol](https://github.com/essentialkaos/go-zabbix/blob/master/protocol.go): wire format · Internal Zabbix sender framing, serialization, and response parsing. · `protocol.go`
- [Build request](https://github.com/essentialkaos/go-zabbix/blob/master/protocol.go): payload assembly · Turns caller inputs into Zabbix sender messages. · `protocol.go`
- [Encode msg](https://github.com/essentialkaos/go-zabbix/blob/master/protocol.go): serialization · Serializes request data into the protocol wire format. · `protocol.go`
- [Send data](https://github.com/essentialkaos/go-zabbix/blob/master/protocol.go): network I/O · Writes the encoded request to a reachable Zabbix Server. · `protocol.go`
- [Parse reply](https://github.com/essentialkaos/go-zabbix/blob/master/protocol.go): response parsing · Reads and interprets the server response for success or failure. · `protocol.go`
- **Zabbix Server**: remote endpoint · Compatible Zabbix server receiving sender protocol traffic.
- [Result](https://github.com/essentialkaos/go-zabbix/blob/master/zabbix.go): status · Returned success or failure information for the caller. · `zabbix.go`

### Validation

Tests, fuzzing, and corpus data that define and harden the protocol contract.

- [API tests](https://github.com/essentialkaos/go-zabbix/blob/master/zabbix_test.go): behavioral tests · Package tests that validate public semantics. · `zabbix_test.go`
- [Example docs](https://github.com/essentialkaos/go-zabbix/blob/master/example_test.go): usage examples · Example-based tests that demonstrate library usage. · `example_test.go`
- [Fuzz harness](https://github.com/essentialkaos/go-zabbix/blob/master/fuzz.go): robustness tests · Fuzz entry point for exercising protocol edge cases. · `fuzz.go`
- [Corpus](https://github.com/essentialkaos/go-zabbix/tree/master/testdata/corpus): fuzz inputs · Seed inputs used to harden encoder and parser behavior. · `testdata/corpus`

### Repo tooling

Module, docs, and automation used to maintain the package.

- [Module](https://github.com/essentialkaos/go-zabbix/blob/master/go.mod): go module · Go module definition and dependency metadata. · `go.mod`
- [Checksums](https://github.com/essentialkaos/go-zabbix/blob/master/go.sum): dependency lock · Pinned module checksum data. · `go.sum`
- [Makefile](https://github.com/essentialkaos/go-zabbix/tree/master/Makefile): automation · Local developer automation and convenience targets. · `Makefile`
- [README](https://github.com/essentialkaos/go-zabbix/blob/master/README.md): docs · Primary project overview and usage documentation. · `README.md`
- [CI workflows](https://github.com/essentialkaos/go-zabbix/blob/master/.github/workflows/ci.yml): automation · GitHub Actions for tests, CodeQL, and documentation generation. · `.github/workflows/ci.yml`
- [CodeQL](https://github.com/essentialkaos/go-zabbix/blob/master/.github/workflows/codeql.yml): security scan · Static security analysis workflow. · `.github/workflows/codeql.yml`
- [Docgen](https://github.com/essentialkaos/go-zabbix/blob/master/.github/workflows/godoc.yml): docs workflow · Documentation generation workflow. · `.github/workflows/godoc.yml`
- [Typos config](https://github.com/essentialkaos/go-zabbix/blob/master/.typos.toml): lint config · Repository spelling/hygiene checks. · `.typos.toml`

## Connections

- Go app → zabbix pkg: import/call · An external Go program imports the package and invokes its API.
- zabbix pkg → Build request: assemble · Public API turns user inputs into a protocol request.
- Build request → Encode msg: format · Request data is serialized into sender wire format.
- Encode msg → Send data: transmit · Encoded bytes are written toward the server.
- Send data → Zabbix Server: connect · Library sends the metric payload to a Zabbix Server.
- Zabbix Server → Parse reply: reply · Server response is parsed back into library state.
- Parse reply → Result: return · Parsed response becomes caller-visible success or failure.
- zabbix pkg → Protocol: delegates · The public package relies on the internal protocol boundary.
- Protocol → Build request: owns · Protocol layer defines request framing and payload shape.
- Protocol → Encode msg: owns · Protocol layer handles serialization details.
- Protocol → Parse reply: owns · Protocol layer handles server response parsing.
- API tests → zabbix pkg: validates · Tests exercise public API behavior.
- Example docs → zabbix pkg: documents · Examples show intended usage of the exported package.
- Fuzz harness → Protocol: targets · Fuzzing focuses on protocol robustness.
- Corpus → Fuzz harness: seeds · Corpus files provide fuzzing inputs.
- Module → zabbix pkg: module · Go module defines how the package is consumed.
- Checksums → Module: pins · Checksum file locks module dependencies.
- Makefile → API tests: runs · Make targets likely orchestrate test execution.
- CI workflows → API tests: checks · CI runs the test suite.
- CI workflows → Docgen: generates · CI includes documentation generation.
- CI workflows → CodeQL: scans · CI includes CodeQL analysis.
- Typos config → README: checks · Spelling/hygiene config supports repository content checks.
