# peterfraedrich/consulmq architecture

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

- Interactive diagram: https://gitdiagram.com/peterfraedrich/consulmq
- Repository: https://github.com/peterfraedrich/consulmq

## Overview

##### Main components
a. Client Application (producer/consumer) – any Go program that calls `consulmq.Connect(...)`, `Push`, `Pop`, etc.
b. ConsulMQ Library – your Go package consisting of `consulmq.go`, `functions.go`, and associated tests.
c. Consul Cluster (external service) – the distributed KV store and lock/session subsystem.
d. Queue Artifacts in KV Store – the `_index` key (JSON list of message IDs) plus per-message keys under unique IDs.

##### Interactions and data flows
- Client → ConsulMQ Library: calls API methods `Connect`, `Push`, `Pop`, etc.
- Library → Consul HTTP API:
- Acquire distributed lock (using Consul sessions) on the queue’s `_index`.
- Read `_index` key (JSON array of IDs).
- For Push: generate new ID, write message body under `<MQName>/<ID>`, append ID to `_index`, write back.
- For Pop: remove first ID from `_index`, write back index, then read or delete the message key.
- Release the lock.
- Library returns results/errors to Client.

##### Architectural patterns and design principles
- Single shared resource (the `_index`) protected by a distributed lock.
- Each message is an independent KV entry, enabling durability and distribution.
- The library is a thin adapter over Consul’s KV + Session APIs (no external broker).
- JSON is used as the on-chain format for the index; message payloads are raw bytes.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main Flow
    ClientApp["Client Application\n(examples/hello_world.go)"]:::client
    LibraryCore["ConsulMQ Library\nCore (consulmq.go, functions.go)"]:::lib
    ConsulAPI["Consul HTTP API"]:::api
    KVStore["Consul KV Store\n_index + <MSG_ID> entries"]:::data

    ClientApp -->|"Connect(), Push(), Pop()"| LibraryCore
    LibraryCore -->|"HTTP API Calls"| ConsulAPI
    ConsulAPI -->|"Lock _index\nRead _index\nWrite msg/<ID>\nUpdate _index\nUnlock"| KVStore
    KVStore -->|"KV Data"| ConsulAPI
    ConsulAPI -->|"HTTP Response"| LibraryCore
    LibraryCore -->|"Results/Errors"| ClientApp

    %% Supporting Components
    subgraph "Testing & CI" 
        LibraryTests["Library Tests\n(consulmq_test.go,\nfunctions_test.go)"]:::lib
        IntegrationTest["Integration Test\n(testdata/test.config)"]:::ext
        CI["CI Pipeline\n(.github/workflows/go.yml)"]:::infra
    end

    subgraph "Project Metadata" 
        Module["Module & Dependencies\n(go.mod, go.sum)"]:::infra
        RepoMeta["Repo Docs & Config\n(README.md,\nLICENSE,\n.gitignore)"]:::infra
    end

    %% Click Events
    click ClientApp "https://github.com/peterfraedrich/consulmq/blob/master/examples/hello_world.go"
    click LibraryCore "https://github.com/peterfraedrich/consulmq/blob/master/consulmq.go"
    click LibraryCore "https://github.com/peterfraedrich/consulmq/blob/master/functions.go"
    click LibraryTests "https://github.com/peterfraedrich/consulmq/blob/master/consulmq_test.go"
    click LibraryTests "https://github.com/peterfraedrich/consulmq/blob/master/functions_test.go"
    click IntegrationTest "https://github.com/peterfraedrich/consulmq/blob/master/testdata/test.config"
    click CI "https://github.com/peterfraedrich/consulmq/blob/master/.github/workflows/go.yml"
    click Module "https://github.com/peterfraedrich/consulmq/blob/master/go.mod"
    click RepoMeta "https://github.com/peterfraedrich/consulmq/blob/master/README.md"

    %% Styles
    classDef client fill:#FFD580,stroke:#CC8400,color:#000;
    classDef lib fill:#B3E6B3,stroke:#4D994D,color:#000;
    classDef api fill:#ADD8E6,stroke:#2D7F9A,color:#000;
    classDef data fill:#F0F0F0,stroke:#999999,color:#000;
    classDef ext fill:#E6CCFF,stroke:#995FCC,color:#000;
    classDef infra fill:#FFF2CC,stroke:#CCA64D,color:#000;
```
