# go-zookeeper/zk architecture

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

- Interactive diagram: https://gitdiagram.com/go-zookeeper/zk
- Repository: https://github.com/go-zookeeper/zk

## Overview

##### Project type and purpose
- This is a native Go client library for Apache Zookeeper. It provides session management, command encoding/decoding, watches, locks, and other ZK primitives for Go applications.

##### File structure
- Top-level files
- conn.go, flw.go, structs.go, constants.go, util.go, lock.go, create_mode.go, dnshostprovider.go – the core of the library.
- *_test.go files – unit tests for each component.
- _examples directory – sample Go programs showing how to use the API.
- Internal directory
- internal/assert – assertion helpers used in tests and internal code.
- Configuration and tooling
- .github/workflows – CI definitions (linting, testing).
- Makefile, go.mod – build and dependency management.

##### README for additional insights
- Confirms that this is purely a client library (no server component).

a. Main components
1. Public API Layer
– Exposed functions and types that application authors import.
2. Session & Connection Manager (conn.go)
– Establishes and maintains TCP connections to ZK servers.
– Handles session creation, heartbeats, reconnect logic.
3. Protocol Frame Layer (flw.go)
– Encodes requests into the wire format.
– Decodes response frames back into Go structs.
4. Data Structures & Constants (structs.go, constants.go)
– Defines request/response types, ACLs, error codes, create modes.
5. Watch & Event Dispatcher (util.go, structs.go)
– Registers watchers, dispatches events back to user callbacks.
6. Host Provider (dnshostprovider.go)
– Resolves ZK hostnames, handles DNS-based discovery.
7. Lock Implementation (lock.go)
– High-level distributed lock abstraction built on top of the core primitives.
8. Examples (/_examples)
– Illustrate basic usage and patterns.

b. Relationships and interactions
- User Application → Public API Layer → Session & Connection Manager
- Sends operations (create, get, set, delete, sync, exists)
- Session & Connection Manager ↔ Zookeeper Cluster
- Over TCP, uses Protocol Frame Layer to marshal/unmarshal
- Incoming Frames → Protocol Layer → Event Dispatcher → User callbacks
- Lock Implementation builds on Public API calls (create, delete, watches)
- Host Provider feeds server addresses into Connection Manager

c. Architectural patterns and principles
- Layered architecture: API → Session → Protocol → Transport
- Separation of concerns: encoding/decoding is isolated from connection logic
- Pluggable host resolution (allows custom DNS or static lists)
- Minimal global state; uses per-conn session objects

d. Key technologies and libraries
- Go’s net package for TCP connections
- Standard library sync primitives for concurrent event dispatch
- Go modules (go.mod) for dependency management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application
    App["User Application"]:::external

    %% Public API Layer
    subgraph "Public API Layer"
        ConnFile["conn.go"]:::public
        UtilFile["util.go"]:::public
        LockFile["lock.go"]:::public
        CreateModeFile["create_mode.go"]:::public
        ConstantsFile["constants.go"]:::public
        StructsFile["structs.go"]:::public
        HostProvFile["dnshostprovider.go"]:::public
    end

    %% Core Engine
    subgraph "Core Engine"
        Session["Session & Connection Manager"]:::core
        Protocol["Protocol Frame Layer"]:::core
        HostProvider["Host Provider"]:::core
    end

    %% Data Structures & Constants
    subgraph "Data Structures & Constants"
        StructsDS["structs.go"]:::core
        ConstantsDS["constants.go"]:::core
        CreateModeDS["create_mode.go"]:::core
    end

    %% Watch & Event Dispatcher
    Dispatch["Watch & Event Dispatcher"]:::core

    %% Lock Implementation
    LockImpl["Lock Implementation"]:::public

    %% Internal Assertion Helpers
    subgraph "Internal"
        Assert["assert.go"]:::internal
    end

    %% Examples
    Examples["/_examples/basic.go"]:::external

    %% Configuration & Tooling
    subgraph "Config & Tooling"
        Workflows[".github/workflows/*.yaml"]:::config
        MakefileFile["Makefile"]:::config
        GoMod["go.mod"]:::config
    end

    %% External System
    ZK["Zookeeper Cluster"]:::external

    %% Connections
    App -->|"Imports API"| ConnFile
    ConnFile -->|"Uses HostProvider"| HostProvFile
    ConnFile -->|"Creates Session"| Session
    Session -->|"SendRequest(opcode,payload)"| Protocol
    Protocol -->|"TCP"| ZK
    ZK -->|"Response Frames"| Protocol
    Protocol -->|"Decode->Event"| Dispatch
    Dispatch -->|"Invoke Callback"| App
    ConnFile -->|"Handles Watches"| Dispatch
    LockFile -->|"Builds on API"| ConnFile
    HostProvFile -->|"Resolves Hosts"| Session
    Assert -.-> UtilFile
    Examples -.-> ConnFile

    %% Click Events
    click ConnFile "https://github.com/go-zookeeper/zk/blob/master/conn.go"
    click UtilFile "https://github.com/go-zookeeper/zk/blob/master/util.go"
    click LockFile "https://github.com/go-zookeeper/zk/blob/master/lock.go"
    click CreateModeFile "https://github.com/go-zookeeper/zk/blob/master/create_mode.go"
    click ConstantsFile "https://github.com/go-zookeeper/zk/blob/master/constants.go"
    click StructsFile "https://github.com/go-zookeeper/zk/blob/master/structs.go"
    click HostProvFile "https://github.com/go-zookeeper/zk/blob/master/dnshostprovider.go"
    click Session "https://github.com/go-zookeeper/zk/blob/master/conn.go"
    click Protocol "https://github.com/go-zookeeper/zk/blob/master/flw.go"
    click StructsDS "https://github.com/go-zookeeper/zk/blob/master/structs.go"
    click ConstantsDS "https://github.com/go-zookeeper/zk/blob/master/constants.go"
    click CreateModeDS "https://github.com/go-zookeeper/zk/blob/master/create_mode.go"
    click Dispatch "https://github.com/go-zookeeper/zk/blob/master/util.go"
    click HostProvider "https://github.com/go-zookeeper/zk/blob/master/dnshostprovider.go"
    click LockImpl "https://github.com/go-zookeeper/zk/blob/master/lock.go"
    click Assert "https://github.com/go-zookeeper/zk/blob/master/internal/assert/assert.go"
    click Examples "https://github.com/go-zookeeper/zk/blob/master//_examples/basic.go"
    click Workflows "https://github.com/go-zookeeper/zk/blob/master/.github/workflows/*.yaml"
    click MakefileFile "https://github.com/go-zookeeper/zk/tree/master/Makefile"
    click GoMod "https://github.com/go-zookeeper/zk/blob/master/go.mod"

    %% Styles
    classDef public fill:#a2fca3,stroke:#333,stroke-width:1px
    classDef core fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef internal fill:#ffd6a5,stroke:#333,stroke-width:1px
    classDef config fill:#ffadad,stroke:#333,stroke-width:1px
```
