# jsainsburyplc/consul-client architecture

> Architecture diagram of the GitHub repository jsainsburyplc/consul-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jsainsburyplc/consul-client
- Repository: https://github.com/jsainsburyplc/consul-client

## Overview

This is a Java client library for Consul’s HTTP API. A caller builds a Consul client, obtains domain-specific clients, and uses them to register services and checks, discover healthy instances, or read and write key/value data. The library also exposes sessions, events, prepared queries, ACL, catalog, coordinate, operator, and status APIs, plus caches for watching changes. The sampled source shows health and agent requests using the shared HTTP helpers, and HTTP response metadata wrapping; unsampled client relationships are omitted or marked unverified.

Main entry points: [`src/main/java/com/orbitz/consul/HealthClient.java`](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/HealthClient.java) (Health discovery), [`src/main/java/com/orbitz/consul/util/Http.java`](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/util/Http.java) (HTTP handling), [`src/main/java/com/orbitz/consul/Consul.java`](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/Consul.java) (Consul factory), [`src/main/java/com/orbitz/consul/AgentClient.java`](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/AgentClient.java) (Agent operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry"]
  node_consul["Consul factory<br/>[Consul.java]"]
end

subgraph group_api["Consul API clients"]
  node_agent["Agent operations<br/>[AgentClient.java]"]
  node_health["Health discovery<br/>[HealthClient.java]"]
  node_kv["Key-value store"]
  node_catalog["Catalog queries<br/>[CatalogClient.java]"]
  node_session["Sessions<br/>[SessionClient.java]"]
  node_prepared["Prepared queries"]
  node_other_apis["Other API clients"]
  node_kv_value["KV value model<br/>[Value.java]"]
  node_health_models["Health models"]
  node_agent_check["Agent check model<br/>[Check.java]"]
end

subgraph group_watch["Watch and async"]
  node_cache["Health cache"]
  node_async_callback["Async callback"]
end

subgraph group_shared["Shared runtime"]
  node_query_options["Query options<br/>[QueryOptions.java]"]
  node_http["HTTP handling<br/>[Http.java]"]
  node_response["Consul response"]
  node_errors["Error handling"]
end

node_caller(("Application caller"))
node_consul_api{{"Consul server"}}

node_caller -->|"builds client"| node_consul
node_consul -.->|"provides client"| node_agent
node_consul -.->|"provides client"| node_health
node_consul -.->|"provides client"| node_kv
node_caller -->|"registers service"| node_agent
node_caller -->|"discovers services"| node_health
node_caller -->|"reads and writes"| node_kv
node_caller -->|"subscribes"| node_cache
node_agent -->|"executes requests"| node_http
node_health -->|"extracts responses"| node_http
node_kv -->|"uses transport"| node_http
node_http -->|"sends HTTP"| node_consul_api
node_http -->|"wraps metadata"| node_response
node_health -->|"returns health data"| node_health_models
node_agent -->|"registers checks"| node_agent_check
node_kv -->|"reads values"| node_kv_value
node_cache -->|"watches service health"| node_health
node_health -->|"applies query options"| node_query_options
node_prepared -->|"queries Consul"| node_consul_api
node_session -.->|"manages sessions"| node_consul_api
node_catalog -.->|"queries catalog"| node_consul_api
node_other_apis -.->|"exposes API calls"| node_consul_api

click node_consul "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/Consul.java"
click node_agent "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/AgentClient.java"
click node_health "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/HealthClient.java"
click node_kv "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/KeyValueClient.java"
click node_catalog "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/CatalogClient.java"
click node_session "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/SessionClient.java"
click node_prepared "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/PreparedQueryClient.java"
click node_other_apis "https://github.com/jsainsburyplc/consul-client/tree/master/src/main/java/com/orbitz/consul"
click node_kv_value "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/model/kv/Value.java"
click node_health_models "https://github.com/jsainsburyplc/consul-client/tree/master/src/main/java/com/orbitz/consul/model/health"
click node_agent_check "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/model/agent/Check.java"
click node_cache "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/cache/ServiceHealthCache.java"
click node_async_callback "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/async/ConsulResponseCallback.java"
click node_query_options "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/option/QueryOptions.java"
click node_http "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/util/Http.java"
click node_response "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/model/ConsulResponse.java"
click node_errors "https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/ConsulException.java"

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_consul toneBlue
class node_agent,node_health,node_kv,node_catalog,node_session,node_prepared,node_other_apis,node_kv_value,node_health_models,node_agent_check toneAmber
class node_cache,node_async_callback,node_consul_api toneMint
class node_query_options,node_http,node_response,node_errors toneRose
class node_caller toneIndigo
```

## Components

### Client entry

- [Consul factory](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/Consul.java): `src/main/java/com/orbitz/consul/Consul.java`

### Consul API clients

- [Agent operations](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/AgentClient.java): `src/main/java/com/orbitz/consul/AgentClient.java`
- [Health discovery](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/HealthClient.java): `src/main/java/com/orbitz/consul/HealthClient.java`
- [Key-value store](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/KeyValueClient.java): `src/main/java/com/orbitz/consul/KeyValueClient.java`
- [Catalog queries](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/CatalogClient.java): `src/main/java/com/orbitz/consul/CatalogClient.java`
- [Sessions](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/SessionClient.java): `src/main/java/com/orbitz/consul/SessionClient.java`
- [Prepared queries](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/PreparedQueryClient.java): `src/main/java/com/orbitz/consul/PreparedQueryClient.java`
- [Other API clients](https://github.com/jsainsburyplc/consul-client/tree/master/src/main/java/com/orbitz/consul): `src/main/java/com/orbitz/consul`
- [KV value model](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/model/kv/Value.java): `src/main/java/com/orbitz/consul/model/kv/Value.java`
- [Health models](https://github.com/jsainsburyplc/consul-client/tree/master/src/main/java/com/orbitz/consul/model/health): `src/main/java/com/orbitz/consul/model/health`
- [Agent check model](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/model/agent/Check.java): `src/main/java/com/orbitz/consul/model/agent/Check.java`

### Watch and async

- [Health cache](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/cache/ServiceHealthCache.java): `src/main/java/com/orbitz/consul/cache/ServiceHealthCache.java`
- [Async callback](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/async/ConsulResponseCallback.java): `src/main/java/com/orbitz/consul/async/ConsulResponseCallback.java`

### Shared runtime

- [Query options](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/option/QueryOptions.java): `src/main/java/com/orbitz/consul/option/QueryOptions.java`
- [HTTP handling](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/util/Http.java): `src/main/java/com/orbitz/consul/util/Http.java`
- [Consul response](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/model/ConsulResponse.java): `src/main/java/com/orbitz/consul/model/ConsulResponse.java`
- [Error handling](https://github.com/jsainsburyplc/consul-client/blob/master/src/main/java/com/orbitz/consul/ConsulException.java): `src/main/java/com/orbitz/consul/ConsulException.java`

### Other components

- **Application caller**
- **Consul server**

## Connections

- Application caller → Consul factory: builds client
- Consul factory → Agent operations: provides client (evidence: `src/main/java/com/orbitz/consul/Consul.java`)
- Consul factory → Health discovery: provides client (evidence: `src/main/java/com/orbitz/consul/Consul.java`)
- Consul factory → Key-value store: provides client (evidence: `src/main/java/com/orbitz/consul/Consul.java`)
- Application caller → Agent operations: registers service
- Application caller → Health discovery: discovers services
- Application caller → Key-value store: reads and writes
- Application caller → Health cache: subscribes
- Agent operations → HTTP handling: executes requests (evidence: `src/main/java/com/orbitz/consul/AgentClient.java`)
- Health discovery → HTTP handling: extracts responses (evidence: `src/main/java/com/orbitz/consul/HealthClient.java`)
- Key-value store → HTTP handling: uses transport (evidence: `src/main/java/com/orbitz/consul/KeyValueClient.java`)
- HTTP handling → Consul server: sends HTTP (evidence: `src/main/java/com/orbitz/consul/util/Http.java`)
- HTTP handling → Consul response: wraps metadata (evidence: `src/main/java/com/orbitz/consul/util/Http.java`)
- Health discovery → Health models: returns health data (evidence: `src/main/java/com/orbitz/consul/HealthClient.java`)
- Agent operations → Agent check model: registers checks (evidence: `src/main/java/com/orbitz/consul/AgentClient.java`)
- Key-value store → KV value model: reads values (evidence: `src/main/java/com/orbitz/consul/KeyValueClient.java`)
- Health cache → Health discovery: watches service health (evidence: `src/main/java/com/orbitz/consul/cache/ServiceHealthCache.java`)
- Health discovery → Query options: applies query options (evidence: `src/main/java/com/orbitz/consul/HealthClient.java`)
- Prepared queries → Consul server: queries Consul (evidence: `src/main/java/com/orbitz/consul/PreparedQueryClient.java`)
- Sessions → Consul server: manages sessions
- Catalog queries → Consul server: queries catalog
- Other API clients → Consul server: exposes API calls
