How codenotary/immudb works
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: server.go Server · client.go Client SDK · immustore.go Store · database.go Database layer
Components 24
Entrypoints
CLI and daemon binaries that wrap shared packages.
- immudb · Database daemon entrypoint.
cmd/immudb/immudb.go - immuclient · Interactive client entrypoint.
cmd/immuclient/immuclient.go - immuadmin · Administration CLI entrypoint.
cmd/immuadmin/immuadmin.go - immutest · Supporting test entrypoint.
cmd/immutest/immutest.go
Core Store
Immutable storage, indexing, verification, and SQL/document layers.
- Store · Transactional KV storage, commits, and verification metadata.
embedded/store/immustore.go - Appendable · Append-only file management and remote-backed appendables.
embedded/appendable/appendable.go - TBTree · Historical access and ordered index structure.
embedded/tbtree/tbtree.go - AHTree · Appendable hash tree for cryptographic verification.
embedded/ahtree/ahtree.go - SQL engine · SQL execution and relational operators on immutable data.
embedded/sql/engine.go - Document engine · 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 · Database-oriented operations, scans, references, truncation, and replication bridge.
pkg/database/database.go - Server · Main request handling and cross-cutting server service layer.
pkg/server/server.go - Sessions · Session lifecycle and transaction coordination.
pkg/server/sessions/manager.go - Auth · Users, tokens, permissions, and interceptors.
pkg/auth/auth.go - PostgreSQL · PostgreSQL-compatible server and SQL compatibility path.
pkg/pgsql/server/server.go - SQL rewrite · Rewrites PostgreSQL-flavored SQL into engine-compatible forms.
pkg/pgsql/server/rewrite/rewriter.go - API schema · gRPC/proto schema and schema-aware helpers.
pkg/api/schema/schema.proto - Replication · Encoding, pipelining, and replication flows between nodes.
pkg/replication/replicator.go
Clients
Go client SDK, SQL driver, and local state helpers.
- Client SDK · Connection, session, heartbeat, TLS, and verification-aware client logic.
pkg/client/client.go - SQL driver · Go database/sql connector and rows/tx facade.
pkg/stdlib/driver.go - Client state · Token, history, and UUID/state persistence.
pkg/client/state/state_service.go
Ops Surface
Admin, web, and packaging surfaces around the core database.
Connections 30
- 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.