# codenotary/immudb architecture

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

- Interactive diagram: https://gitdiagram.com/codenotary/immudb
- Repository: https://github.com/codenotary/immudb

## Overview

1. **Repository shape**
   - This is a Go monorepo for **immudb**, an immutable database system that ships as a server, client tools, embedded library, and multiple protocol adapters.
   - The main architectural split is between **storage/verification internals** (`embedded/*`) and **network-facing services and tooling** (`pkg/*`, `cmd/*`).

2. **Primary runtime entrypoints**
   - `cmd/immudb` is the database server daemon.
   - `cmd/immuclient` is the interactive CLI client.
   - `cmd/immuadmin` is the administration CLI.
   - `cmd/immutest` and `cmd/version` are supporting binaries.
   - These executables are thin wrappers around shared packages; the real behavior lives in `pkg/server`, `pkg/client`, `pkg/pgsql`, and `embedded/*`.

3. **Core storage engine**
   - The lowest layer is `embedded/*`, which implements the immutable persistence model:
     - `embedded/store` for transactional KV storage and commit handling.
     - `embedded/ahtree`, `embedded/htree`, and `embedded/tbtree` for cryptographic/ordered index structures and historical access.
     - `embedded/appendable` for append-only file management and remote-backed appendables.
     - `embedded/sql` and `embedded/document` for SQL and document-model behavior on top of the immutable store.
   - This layer is where the **commit log, Merkle-style verification, indexing, snapshots, and transaction metadata** are maintained.

4. **Database abstraction layer**
   - `pkg/database` translates the storage engine into database-oriented concepts such as:
     - databases, references, sorted sets, scans, truncation, lazy loading, and replication support.
   - This is the bridge between low-level immutable storage and the higher-level server APIs.
   - It also helps organize multi-database behavior and operational concerns like runtime locking and metadata management.

5. **Server-side request handling**
   - `pkg/server` is the main service layer for the gRPC-facing database server.
   - It wires together:
     - database operations
     - sessions
     - authorization
     - transaction handling
     - metrics
     - replication hooks
     - remote storage integration
     - audit/access logging
   - Interceptors in this package enforce cross-cutting concerns such as request metadata, session auth, keep-alives, error mapping, and audit logging before requests reach the database layer.

6. **Protocol boundaries**
   - The server exposes **gRPC APIs** defined under `pkg/api/proto` and generated models under `pkg/api/protomodel`.
   - It also exposes a **PostgreSQL wire-protocol server** under `pkg/pgsql/server`, which lets standard PostgreSQL clients and ORMs connect.
   - The PostgreSQL path includes:
     - message parsing and session handling
     - SQL rewrite/compatibility logic
     - system catalog emulation under `pkg/pgsql/sys`
     - query execution plumbing that maps PG-style requests onto the database engine

7. **SQL compatibility layer**
   - `embedded/sql` is the SQL execution engine used by the database.
   - `pkg/pgsql/server/rewrite` adapts incoming PostgreSQL-flavored SQL into forms the engine can handle.
   - The `pkg/api/schema` package exposes schema-aware operations and proof-aware helpers used by the SQL/document surface.
   - Architecturally, SQL is not a separate database: it is an execution layer layered over the same immutable transaction store.

8. **Client architecture**
   - `pkg/client` contains the Go client SDK and connection/session logic.
   - It includes:
     - token management
     - heartbeating/session state
     - TLS/mTLS options
     - signature verification interceptors
     - streaming and SQL helpers
   - `pkg/stdlib` provides a Go `database/sql` driver facade.
   - `pkg/client/cache` and `pkg/client/state` manage local client-side persistence for tokens, history, UUID/state tracking, and cached reads.
   - `pkg/client/auditor` supports client-side monitoring of operations.

9. **Streaming and replication**
   - `pkg/stream` and `pkg/replication` implement data movement between nodes or from producers to consumers.
   - These packages handle stream encoding/decoding, KV and verification entry formats, pipelining, delays, and replication flows.
   - On the server side, `pkg/server/stream_replication.go` and related code integrate these streams into database operations.
   - This is a key boundary: replication is handled as a specialized pipeline, not as generic storage copying.

10. **Verification and cryptographic trust model**
   - `pkg/verification`, `pkg/signer`, `pkg/cert`, and the tree packages in `embedded/*` implement the trust model.
   - The core idea is that clients can verify database states and histories using proofs rather than trusting the server blindly.
   - The server stores and serves immutable state, while the client side contains verification logic and signature checks.

11. **Authentication, authorization, and sessions**
   - `pkg/auth` centralizes users, tokens, permissions, password handling, and server/client interceptors.
   - `pkg/server/sessions` holds session lifecycle and transaction coordination.
   - Session invalidation, permission checks, and token handling are enforced in the server layer, with client helpers supporting secure login and refresh behavior.

12. **Remote storage and S3**
   - The storage layer can offload appendable data to remote object storage through `embedded/remotestorage` and `pkg/server/remote_storage.go`.
   - The README shows AWS S3 and compatible stores like MinIO as first-class deployment targets.
   - This means the persistence architecture has a local-disk path and a remote-object-storage path, with configuration controlling which becomes authoritative.

13. **Operational surfaces**
   - `pkg/server/webserver.go`, `webconsole`, and `swagger` provide human-readable/admin-facing surfaces.
   - `cmd/immuadmin` includes operational commands for backups, database management, stats, login, and server config.
   - `cmd/immuclient` includes CLI flows for querying, login, history, scanners, and tamperproofing-related commands.
   - These are separate from the database core; they consume the same server APIs.

14. **Packaging and deployment**
   - The repo includes Dockerfiles, Helm charts, release/build tooling, and OS-specific service packaging under `build/`, `helm/`, and `tools/packaging`.
   - This indicates the system is designed to run both as a self-contained daemon and in Kubernetes or containerized environments.
   - The build/test tooling also includes performance, stress, e2e, replication, and compatibility suites, which reflect the importance of durability and protocol correctness in the architecture.

15. **How data flows through the system**
   - A client request enters via gRPC or PostgreSQL wire protocol.
   - The server authenticates the session, applies authorization and request metadata, and routes the operation to database logic.
   - The database layer writes to the immutable store, updates indexes/history/proof structures, and may replicate or audit the event.
   - Responses can be verified by the client using stored state and proof material, while operational commands and web surfaces consume the same underlying APIs.

Main entry points: [`pkg/server/server.go`](https://github.com/codenotary/immudb/blob/master/pkg/server/server.go) (Server), [`pkg/client/client.go`](https://github.com/codenotary/immudb/blob/master/pkg/client/client.go) (Client SDK), [`embedded/store/immustore.go`](https://github.com/codenotary/immudb/blob/master/embedded/store/immustore.go) (Store), [`pkg/database/database.go`](https://github.com/codenotary/immudb/blob/master/pkg/database/database.go) (Database layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entrypoints"]
  node_cmd_immudb["immudb<br/>server binary<br/>[immudb.go]"]
  node_cmd_immuclient["immuclient<br/>cli binary<br/>[immuclient.go]"]
  node_cmd_immuadmin["immuadmin<br/>admin binary<br/>[immuadmin.go]"]
  node_cmd_immutest["immutest<br/>test binary<br/>[immutest.go]"]
end

subgraph group_core["Core Store"]
  node_embedded_store[("Store<br/>[immustore.go]")]
  node_embedded_appendable["Appendable<br/>append-only IO<br/>[appendable.go]"]
  node_embedded_tbtree{{"TBTree<br/>history index<br/>[tbtree.go]"}}
  node_embedded_ahtree{{"AHTree<br/>hash tree<br/>[ahtree.go]"}}
  node_embedded_sql["SQL engine<br/>embedded sql<br/>[engine.go]"]
  node_embedded_document["Document engine<br/>embedded document<br/>[engine.go]"]
end

subgraph group_services["Services"]
  node_database_layer["Database layer<br/>db abstraction<br/>[database.go]"]
  node_server_layer["Server<br/>[server.go]"]
  node_server_sessions["Sessions<br/>session manager<br/>[manager.go]"]
  node_auth_layer["Auth<br/>[auth.go]"]
  node_pgsql_server["PostgreSQL<br/>wire protocol<br/>[server.go]"]
  node_pgsql_rewrite["SQL rewrite<br/>compat rewrite<br/>[rewriter.go]"]
  node_api_schema["API schema<br/>proto/schema<br/>[schema.proto]"]
  node_replication["Replication<br/>stream pipeline<br/>[replicator.go]"]
end

subgraph group_clients["Clients"]
  node_client_sdk["Client SDK<br/>go client<br/>[client.go]"]
  node_stdlib["SQL driver<br/>database/sql facade<br/>[driver.go]"]
  node_client_state["Client state<br/>local cache<br/>[state_service.go]"]
end

subgraph group_ops["Ops Surface"]
  node_immuadmin_ops["Admin ops<br/>ops cli<br/>[cmd.go]"]
  node_webconsole["Web UI<br/>admin web<br/>[webconsole.go]"]
  node_packaging["Packaging<br/>deploy tooling<br/>[nfpm.yaml]"]
end

node_cmd_immudb -->|"starts"| node_server_layer
node_cmd_immuclient -->|"uses"| node_client_sdk
node_cmd_immuadmin -->|"uses"| node_client_sdk
node_cmd_immutest -.->|"exercises"| node_client_sdk
node_server_layer -->|"routes to"| node_database_layer
node_server_layer -->|"manages"| node_server_sessions
node_server_layer -->|"enforces"| node_auth_layer
node_server_layer -->|"publishes"| node_replication
node_server_layer -->|"serves"| node_api_schema
node_database_layer -->|"persists via"| node_embedded_store
node_database_layer -->|"executes"| node_embedded_sql
node_database_layer -->|"stores"| node_embedded_document
node_database_layer -->|"indexes"| node_embedded_tbtree
node_embedded_store -->|"writes to"| node_embedded_appendable
node_embedded_store -->|"verifies with"| node_embedded_ahtree
node_embedded_store -->|"indexes with"| node_embedded_tbtree
node_embedded_sql -->|"reads/writes"| node_embedded_store
node_embedded_document -->|"reads/writes"| node_embedded_store
node_pgsql_server -->|"rewrites"| node_pgsql_rewrite
node_pgsql_server -->|"executes on"| node_embedded_sql
node_pgsql_server -.->|"shares auth"| node_server_layer
node_client_sdk -->|"calls"| node_server_layer
node_client_sdk -->|"connects"| node_pgsql_server
node_client_sdk -->|"persists"| node_client_state
node_stdlib -->|"wraps"| node_client_sdk
node_immuadmin_ops -->|"operates via"| node_client_sdk
node_webconsole -->|"consumes"| node_server_layer
node_packaging -.->|"packages"| node_cmd_immudb
node_packaging -.->|"packages"| node_cmd_immuclient
node_packaging -.->|"packages"| node_cmd_immuadmin

click node_cmd_immudb "https://github.com/codenotary/immudb/blob/master/cmd/immudb/immudb.go"
click node_cmd_immuclient "https://github.com/codenotary/immudb/blob/master/cmd/immuclient/immuclient.go"
click node_cmd_immuadmin "https://github.com/codenotary/immudb/blob/master/cmd/immuadmin/immuadmin.go"
click node_cmd_immutest "https://github.com/codenotary/immudb/blob/master/cmd/immutest/immutest.go"
click node_embedded_store "https://github.com/codenotary/immudb/blob/master/embedded/store/immustore.go"
click node_embedded_appendable "https://github.com/codenotary/immudb/blob/master/embedded/appendable/appendable.go"
click node_embedded_tbtree "https://github.com/codenotary/immudb/blob/master/embedded/tbtree/tbtree.go"
click node_embedded_ahtree "https://github.com/codenotary/immudb/blob/master/embedded/ahtree/ahtree.go"
click node_embedded_sql "https://github.com/codenotary/immudb/blob/master/embedded/sql/engine.go"
click node_embedded_document "https://github.com/codenotary/immudb/blob/master/embedded/document/engine.go"
click node_database_layer "https://github.com/codenotary/immudb/blob/master/pkg/database/database.go"
click node_server_layer "https://github.com/codenotary/immudb/blob/master/pkg/server/server.go"
click node_server_sessions "https://github.com/codenotary/immudb/blob/master/pkg/server/sessions/manager.go"
click node_auth_layer "https://github.com/codenotary/immudb/blob/master/pkg/auth/auth.go"
click node_pgsql_server "https://github.com/codenotary/immudb/blob/master/pkg/pgsql/server/server.go"
click node_pgsql_rewrite "https://github.com/codenotary/immudb/blob/master/pkg/pgsql/server/rewrite/rewriter.go"
click node_api_schema "https://github.com/codenotary/immudb/blob/master/pkg/api/schema/schema.proto"
click node_replication "https://github.com/codenotary/immudb/blob/master/pkg/replication/replicator.go"
click node_client_sdk "https://github.com/codenotary/immudb/blob/master/pkg/client/client.go"
click node_stdlib "https://github.com/codenotary/immudb/blob/master/pkg/stdlib/driver.go"
click node_client_state "https://github.com/codenotary/immudb/blob/master/pkg/client/state/state_service.go"
click node_immuadmin_ops "https://github.com/codenotary/immudb/blob/master/cmd/immuadmin/command/cmd.go"
click node_webconsole "https://github.com/codenotary/immudb/blob/master/webconsole/webconsole.go"
click node_packaging "https://github.com/codenotary/immudb/blob/master/tools/packaging/conf/nfpm.yaml"

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_cmd_immudb,node_cmd_immuclient,node_cmd_immuadmin,node_cmd_immutest toneBlue
class node_embedded_store,node_embedded_appendable,node_embedded_tbtree,node_embedded_ahtree,node_embedded_sql,node_embedded_document toneAmber
class node_database_layer,node_server_layer,node_server_sessions,node_auth_layer,node_pgsql_server,node_pgsql_rewrite,node_api_schema,node_replication toneMint
class node_client_sdk,node_stdlib,node_client_state toneRose
class node_immuadmin_ops,node_webconsole,node_packaging toneIndigo
```

## Components

### Entrypoints

CLI and daemon binaries that wrap shared packages.

- [immudb](https://github.com/codenotary/immudb/blob/master/cmd/immudb/immudb.go): server binary · Database daemon entrypoint. · `cmd/immudb/immudb.go`
- [immuclient](https://github.com/codenotary/immudb/blob/master/cmd/immuclient/immuclient.go): cli binary · Interactive client entrypoint. · `cmd/immuclient/immuclient.go`
- [immuadmin](https://github.com/codenotary/immudb/blob/master/cmd/immuadmin/immuadmin.go): admin binary · Administration CLI entrypoint. · `cmd/immuadmin/immuadmin.go`
- [immutest](https://github.com/codenotary/immudb/blob/master/cmd/immutest/immutest.go): test binary · Supporting test entrypoint. · `cmd/immutest/immutest.go`

### Core Store

Immutable storage, indexing, verification, and SQL/document layers.

- [Store](https://github.com/codenotary/immudb/blob/master/embedded/store/immustore.go): immutable tx store · Transactional KV storage, commits, and verification metadata. · `embedded/store/immustore.go`
- [Appendable](https://github.com/codenotary/immudb/blob/master/embedded/appendable/appendable.go): append-only IO · Append-only file management and remote-backed appendables. · `embedded/appendable/appendable.go`
- [TBTree](https://github.com/codenotary/immudb/blob/master/embedded/tbtree/tbtree.go): history index · Historical access and ordered index structure. · `embedded/tbtree/tbtree.go`
- [AHTree](https://github.com/codenotary/immudb/blob/master/embedded/ahtree/ahtree.go): hash tree · Appendable hash tree for cryptographic verification. · `embedded/ahtree/ahtree.go`
- [SQL engine](https://github.com/codenotary/immudb/blob/master/embedded/sql/engine.go): embedded sql · SQL execution and relational operators on immutable data. · `embedded/sql/engine.go`
- [Document engine](https://github.com/codenotary/immudb/blob/master/embedded/document/engine.go): embedded document · Document-model execution on top of the same store. · `embedded/document/engine.go`

### Services

Server-facing APIs, protocol adapters, auth, sessions, and replication.

- [Database layer](https://github.com/codenotary/immudb/blob/master/pkg/database/database.go): db abstraction · Database-oriented operations, scans, references, truncation, and replication bridge. · `pkg/database/database.go`
- [Server](https://github.com/codenotary/immudb/blob/master/pkg/server/server.go): gRPC server · Main request handling and cross-cutting server service layer. · `pkg/server/server.go`
- [Sessions](https://github.com/codenotary/immudb/blob/master/pkg/server/sessions/manager.go): session manager · Session lifecycle and transaction coordination. · `pkg/server/sessions/manager.go`
- [Auth](https://github.com/codenotary/immudb/blob/master/pkg/auth/auth.go): authz/authn · Users, tokens, permissions, and interceptors. · `pkg/auth/auth.go`
- [PostgreSQL](https://github.com/codenotary/immudb/blob/master/pkg/pgsql/server/server.go): wire protocol · PostgreSQL-compatible server and SQL compatibility path. · `pkg/pgsql/server/server.go`
- [SQL rewrite](https://github.com/codenotary/immudb/blob/master/pkg/pgsql/server/rewrite/rewriter.go): compat rewrite · Rewrites PostgreSQL-flavored SQL into engine-compatible forms. · `pkg/pgsql/server/rewrite/rewriter.go`
- [API schema](https://github.com/codenotary/immudb/blob/master/pkg/api/schema/schema.proto): proto/schema · gRPC/proto schema and schema-aware helpers. · `pkg/api/schema/schema.proto`
- [Replication](https://github.com/codenotary/immudb/blob/master/pkg/replication/replicator.go): stream pipeline · Encoding, pipelining, and replication flows between nodes. · `pkg/replication/replicator.go`

### Clients

Go client SDK, SQL driver, and local state helpers.

- [Client SDK](https://github.com/codenotary/immudb/blob/master/pkg/client/client.go): go client · Connection, session, heartbeat, TLS, and verification-aware client logic. · `pkg/client/client.go`
- [SQL driver](https://github.com/codenotary/immudb/blob/master/pkg/stdlib/driver.go): database/sql facade · Go database/sql connector and rows/tx facade. · `pkg/stdlib/driver.go`
- [Client state](https://github.com/codenotary/immudb/blob/master/pkg/client/state/state_service.go): local cache · Token, history, and UUID/state persistence. · `pkg/client/state/state_service.go`

### Ops Surface

Admin, web, and packaging surfaces around the core database.

- [Admin ops](https://github.com/codenotary/immudb/blob/master/cmd/immuadmin/command/cmd.go): ops cli · Backups, databases, stats, login, and server config workflows. · `cmd/immuadmin/command/cmd.go`
- [Web UI](https://github.com/codenotary/immudb/blob/master/webconsole/webconsole.go): admin web · Human-facing web console and swagger surface. · `webconsole/webconsole.go`
- [Packaging](https://github.com/codenotary/immudb/blob/master/tools/packaging/conf/nfpm.yaml): deploy tooling · Docker, Helm, and service packaging for deployment. · `tools/packaging/conf/nfpm.yaml`

## Connections

- immudb → Server: starts · Daemon boots the shared server service layer.
- immuclient → Client SDK: uses · CLI is built on the shared client SDK.
- immuadmin → Client SDK: uses · Admin workflows call the same client SDK.
- immutest → Client SDK: exercises · Test binary drives client/server interactions.
- Server → Database layer: routes to · Server request handlers delegate to database operations.
- Server → Sessions: manages · Server coordinates sessions and transaction lifecycle.
- Server → Auth: enforces · Authentication and authorization interceptors gate requests.
- Server → Replication: publishes · Server integrates stream replication into database events.
- Server → API schema: serves · gRPC APIs are defined by the shared schema.
- Database layer → Store: persists via · Database abstraction stores transactional data in the immutable store.
- Database layer → SQL engine: executes · SQL-oriented database operations flow into the embedded engine.
- Database layer → Document engine: stores · Document operations are layered on the same immutable storage.
- Database layer → TBTree: indexes · Historical and ordered access rely on TBTree structures.
- Store → Appendable: writes to · Store commit data is backed by append-only files.
- Store → AHTree: verifies with · Store uses the appendable hash tree for proof material.
- Store → TBTree: indexes with · Store maintains historical index structures for reads and proofs.
- SQL engine → Store: reads/writes · SQL engine operates on the same immutable transaction store.
- Document engine → Store: reads/writes · Document engine is layered over the same store.
- PostgreSQL → SQL rewrite: rewrites · PostgreSQL requests are normalized before execution.
- PostgreSQL → SQL engine: executes on · Rewritten SQL maps to the embedded SQL engine.
- PostgreSQL → Server: shares auth · Protocol path reuses server-side session and auth controls.
- Client SDK → Server: calls · Client SDK talks to the gRPC server.
- Client SDK → PostgreSQL: connects · Clients can also connect through PostgreSQL protocol adapters.
- Client SDK → Client state: persists · Local state holds tokens, history, and identifiers.
- SQL driver → Client SDK: wraps · database/sql facade is built on the client SDK.
- Admin ops → Client SDK: operates via · Admin CLI uses client connectivity for operational commands.
- Web UI → Server: consumes · Web console and swagger surfaces consume server APIs.
- Packaging → immudb: packages · Deployment tooling packages the database daemon.
- Packaging → immuclient: packages · Deployment tooling packages the client binary.
- Packaging → immuadmin: packages · Deployment tooling packages the admin binary.
