# regullar/ezapi architecture

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

- Interactive diagram: https://gitdiagram.com/regullar/ezapi
- Repository: https://github.com/regullar/ezapi

## Overview

EzAPI is a protected-traffic gateway and Go client SDK. The client packages a command into a canonical-CBOR envelope, encrypts and signs it, then sends it over TLS to one gateway endpoint; the gateway authenticates, decrypts, applies policy and user operations, and returns an encrypted response. The graph preserves the documented BOLA/property checks and monitoring capabilities. Evidence is limited to the README and indexed excerpts; unsampled modules are represented only where documented, with uncertain links omitted.

Main entry points: [`pkg/gateway/server.go`](https://github.com/regullar/ezapi/blob/main/pkg/gateway/server.go) (HTTP gateway), [`pkg/gateway/client.go`](https://github.com/regullar/ezapi/blob/main/pkg/gateway/client.go) (Client SDK), [`pkg/security/pipeline.go`](https://github.com/regullar/ezapi/blob/main/pkg/security/pipeline.go) (Validation and authorization), [`pkg/crypto/hpke.go`](https://github.com/regullar/ezapi/blob/main/pkg/crypto/hpke.go) (Encrypted response)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client SDK"]
  node_client["Client SDK<br/>[client.go]"]
  node_crypto["HPKE and signing<br/>[hpke.go]"]
  node_certs["TLS certificates<br/>[certs.go]"]
end

subgraph group_wire["Wire Protocol"]
  node_protocol_env["Envelope and AAD<br/>[envelope.go]"]
  node_protocol_msg["Payload schemas<br/>[messages.go]"]
  node_protocol_cbor["Canonical CBOR<br/>[cbor.go]"]
  node_response["Encrypted response<br/>[hpke.go]"]
end

subgraph group_gateway["Gateway Runtime"]
  node_gateway["HTTP gateway<br/>[server.go]"]
  node_metrics["Request metrics<br/>[metrics.go]"]
end

subgraph group_policy["Security Policy"]
  node_registry[("Device registry<br/>[auth.go]")]
  node_rate["Rate limiting<br/>[ratelimit.go]"]
  node_pipeline["Validation and authorization<br/>[pipeline.go]"]
  node_replay[("Replay cache<br/>[replay.go]")]
end

subgraph group_domain["User Data"]
  node_user_store[("User store<br/>[memory.go]")]
  node_user_ops["Ping and user operations<br/>[pipeline.go]"]
end

node_caller(("API caller"))

node_caller -->|"calls"| node_client
node_client -->|"encodes request"| node_protocol_msg
node_client -->|"forms envelope"| node_protocol_env
node_client -->|"encrypts and signs"| node_crypto
node_client -->|"sends HTTPS request"| node_gateway
node_gateway -->|"checks limit"| node_rate
node_gateway -->|"decodes envelope"| node_protocol_env
node_gateway -->|"looks up device"| node_registry
node_gateway -->|"verifies and decrypts"| node_crypto
node_gateway -->|"executes request"| node_pipeline
node_pipeline -->|"decodes payload"| node_protocol_msg
node_pipeline -->|"checks request ID"| node_replay
node_pipeline -->|"dispatches operation"| node_user_ops
node_user_ops -->|"reads or updates"| node_user_store
node_gateway -->|"records outcomes"| node_metrics
node_gateway -->|"encrypts response"| node_response
node_response -->|"wraps ciphertext"| node_protocol_env
node_gateway -->|"returns CBOR response"| node_client
node_client -->|"decrypts response"| node_response
node_certs -.->|"configures TLS"| node_gateway
node_caller -.->|"requests ping or user access"| node_user_ops

click node_client "https://github.com/regullar/ezapi/blob/main/pkg/gateway/client.go"
click node_crypto "https://github.com/regullar/ezapi/blob/main/pkg/crypto/hpke.go"
click node_certs "https://github.com/regullar/ezapi/blob/main/pkg/crypto/certs.go"
click node_protocol_env "https://github.com/regullar/ezapi/blob/main/pkg/protocol/envelope.go"
click node_protocol_msg "https://github.com/regullar/ezapi/blob/main/pkg/protocol/messages.go"
click node_protocol_cbor "https://github.com/regullar/ezapi/blob/main/pkg/protocol/cbor.go"
click node_gateway "https://github.com/regullar/ezapi/blob/main/pkg/gateway/server.go"
click node_metrics "https://github.com/regullar/ezapi/blob/main/pkg/metrics/metrics.go"
click node_registry "https://github.com/regullar/ezapi/blob/main/pkg/security/auth.go"
click node_rate "https://github.com/regullar/ezapi/blob/main/pkg/security/ratelimit.go"
click node_pipeline "https://github.com/regullar/ezapi/blob/main/pkg/security/pipeline.go"
click node_replay "https://github.com/regullar/ezapi/blob/main/pkg/security/replay.go"
click node_user_store "https://github.com/regullar/ezapi/blob/main/pkg/storage/memory.go"
click node_user_ops "https://github.com/regullar/ezapi/blob/main/pkg/security/pipeline.go"
click node_response "https://github.com/regullar/ezapi/blob/main/pkg/crypto/hpke.go"

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_client,node_crypto,node_certs toneBlue
class node_protocol_env,node_protocol_msg,node_protocol_cbor,node_response toneAmber
class node_gateway,node_metrics,node_caller toneMint
class node_registry,node_rate,node_pipeline,node_replay toneRose
class node_user_store,node_user_ops toneIndigo
```

## Components

### Client SDK

- [Client SDK](https://github.com/regullar/ezapi/blob/main/pkg/gateway/client.go): `pkg/gateway/client.go`
- [HPKE and signing](https://github.com/regullar/ezapi/blob/main/pkg/crypto/hpke.go): `pkg/crypto/hpke.go`
- [TLS certificates](https://github.com/regullar/ezapi/blob/main/pkg/crypto/certs.go): `pkg/crypto/certs.go`

### Wire Protocol

- [Envelope and AAD](https://github.com/regullar/ezapi/blob/main/pkg/protocol/envelope.go): `pkg/protocol/envelope.go`
- [Payload schemas](https://github.com/regullar/ezapi/blob/main/pkg/protocol/messages.go): `pkg/protocol/messages.go`
- [Canonical CBOR](https://github.com/regullar/ezapi/blob/main/pkg/protocol/cbor.go): `pkg/protocol/cbor.go`
- [Encrypted response](https://github.com/regullar/ezapi/blob/main/pkg/crypto/hpke.go): `pkg/crypto/hpke.go`

### Gateway Runtime

- [HTTP gateway](https://github.com/regullar/ezapi/blob/main/pkg/gateway/server.go): `pkg/gateway/server.go`
- [Request metrics](https://github.com/regullar/ezapi/blob/main/pkg/metrics/metrics.go): `pkg/metrics/metrics.go`

### Security Policy

- [Device registry](https://github.com/regullar/ezapi/blob/main/pkg/security/auth.go): `pkg/security/auth.go`
- [Rate limiting](https://github.com/regullar/ezapi/blob/main/pkg/security/ratelimit.go): `pkg/security/ratelimit.go`
- [Validation and authorization](https://github.com/regullar/ezapi/blob/main/pkg/security/pipeline.go): `pkg/security/pipeline.go`
- [Replay cache](https://github.com/regullar/ezapi/blob/main/pkg/security/replay.go): `pkg/security/replay.go`

### User Data

- [User store](https://github.com/regullar/ezapi/blob/main/pkg/storage/memory.go): `pkg/storage/memory.go`
- [Ping and user operations](https://github.com/regullar/ezapi/blob/main/pkg/security/pipeline.go): `pkg/security/pipeline.go`

### Other components

- **API caller**

## Connections

- API caller → Client SDK: calls (evidence: `pkg/gateway/client.go`)
- Client SDK → Payload schemas: encodes request (evidence: `pkg/gateway/client.go`)
- Client SDK → Envelope and AAD: forms envelope (evidence: `pkg/gateway/client.go`)
- Client SDK → HPKE and signing: encrypts and signs (evidence: `pkg/gateway/client.go`)
- Client SDK → HTTP gateway: sends HTTPS request (evidence: `pkg/gateway/client.go`)
- HTTP gateway → Rate limiting: checks limit (evidence: `pkg/gateway/server.go`)
- HTTP gateway → Envelope and AAD: decodes envelope (evidence: `pkg/gateway/server.go`)
- HTTP gateway → Device registry: looks up device (evidence: `pkg/gateway/server.go`)
- HTTP gateway → HPKE and signing: verifies and decrypts (evidence: `pkg/gateway/server.go`)
- HTTP gateway → Validation and authorization: executes request (evidence: `pkg/gateway/server.go`)
- Validation and authorization → Payload schemas: decodes payload (evidence: `pkg/security/pipeline.go`)
- Validation and authorization → Replay cache: checks request ID (evidence: `pkg/security/pipeline.go`)
- Validation and authorization → Ping and user operations: dispatches operation (evidence: `pkg/security/pipeline.go`)
- Ping and user operations → User store: reads or updates (evidence: `pkg/security/pipeline.go`)
- HTTP gateway → Request metrics: records outcomes (evidence: `pkg/gateway/server.go`)
- HTTP gateway → Encrypted response: encrypts response (evidence: `pkg/gateway/server.go`)
- Encrypted response → Envelope and AAD: wraps ciphertext
- HTTP gateway → Client SDK: returns CBOR response (evidence: `pkg/gateway/client.go`)
- Client SDK → Encrypted response: decrypts response (evidence: `pkg/gateway/client.go`)
- TLS certificates → HTTP gateway: configures TLS
- API caller → Ping and user operations: requests ping or user access (evidence: `README.md`)
