If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/codenotary/immudb shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 10 active contributors
• Distributed ownership (top contributor 37% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live codenotary/immudb repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/codenotary/immudb.

What it runs against: a local clone of codenotary/immudb — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in codenotary/immudb | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of codenotary/immudb. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/codenotary/immudb.git
#   cd immudb
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of codenotary/immudb and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "codenotary/immudb(\\.git)?\\b" \\
  && ok "origin remote is codenotary/immudb" \\
  || miss "origin remote is not codenotary/immudb (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "cmd/immuadmin/command/cmd.go" \\
  && ok "cmd/immuadmin/command/cmd.go" \\
  || miss "missing critical file: cmd/immuadmin/command/cmd.go"
test -f "cmd/helper/config.go" \\
  && ok "cmd/helper/config.go" \\
  || miss "missing critical file: cmd/helper/config.go"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "BUILD.md" \\
  && ok "BUILD.md" \\
  || miss "missing critical file: BUILD.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/codenotary/immudb"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

immudb is an immutable database with built-in cryptographic proof and integrity verification, supporting SQL, Key-Value, and Document models. It prevents tampering by making data append-only and cryptographically verifiable—users can detect if their data has been modified without trusting the database itself. It achieves millions of transactions per second and runs on anything from IoT devices to cloud clusters. Monolithic Go binary with modular subsystems: cmd/ contains CLI tools (immuadmin, immuclient), build/ has multi-platform Dockerfiles and FIPS-compliant images, cryptographic core in main pkg namespace, SQL/KV/Document parsers coexist. Makefile orchestrates builds; .github/workflows/ runs push/pull/stress/performance/CodeQL checks.

DevSecOps engineers and compliance teams managing audit logs, financial transaction records, or tamper-sensitive data; developers building applications requiring cryptographic proof of data integrity without blockchain's performance penalty; organizations needing immutable compliance logs (healthcare, finance, energy).

Production-ready and actively developed. The project has 157M Docker Hub pulls, a mature Go codebase (6.1M LOC), comprehensive CI/CD workflows (.github/workflows/), official Helm charts (artifacthub.io), and semantic versioning (v1.4.1 noted in go.mod). Regular releases and active dependabot integration indicate sustained maintenance.

Low risk for core functionality—well-established cryptographic patterns and extensive testing. Moderate risk: Go v1.24.0 requirement may lag in some environments; large dependency tree (prometheus, grpc-ecosystem, spf13 tools) increases surface area; single-vendor stewardship (Codenotary). Verify SECURITY.md and breaking changes in CHANGELOG.md before major version upgrades.

Active development on relational features (SQL support), FIPS compliance (build/fips/), and performance optimization (workflows/performance.yml). Dependabot actively manages Go dependencies. .chglog/ and CHANGELOG.md track semantic versioning. Recent focus includes stress testing (workflows/stress.yml) and multi-arch builds (build/xgo/).

git clone https://github.com/codenotary/immudb.git && cd immudb && make all (builds server, client, admin tools per Makefile). Or: docker run -p 3322:3322 codenotary/immudb to start daemon. See BUILD.md for platform-specific setup and cmd/docs/ for generated CLI documentation.

Daily commands: make all builds binaries to ./cmd/immudb (server), ./cmd/immuclient (CLI client), ./cmd/immuadmin (admin tool). Then: ./cmd/immudb/immudb (default: localhost:3322). Or docker run -p 3322:3322 codenotary/immudb. immuclient connects via ./cmd/immuclient/immuclient -addr localhost -port 3322.

• README.md — Core project overview explaining immudb as an immutable, tamperproof database with zero-trust architecture; essential context for all contributors.
• cmd/immuadmin/command/cmd.go — Primary CLI entry point for the immuadmin tool; defines command structure and initialization for all administrative operations.
• cmd/helper/config.go — Central configuration management across platform-specific implementations; all components depend on this for settings.
• Makefile — Build orchestration and release process; required reading for understanding how the project compiles and packages binaries.
• BUILD.md — Detailed build instructions and environment setup; prerequisite for local development and CI/CD pipeline understanding.
• .github/workflows/push.yml — Primary CI/CD pipeline for testing and validation on each push; defines quality gates and automated checks.
• CONTRIBUTING.md — Contribution guidelines and development workflow; mandatory reference for submitting changes to the codebase.

Add a new immuadmin command

1. Create a new file in cmd/immuadmin/command/ (e.g., export.go) following the pattern of database.go or user.go (cmd/immuadmin/command/newcommand.go)
2. Implement struct with Options and Command() method matching the immuadmin command interface (cmd/immuadmin/command/newcommand.go)
3. Register the command in cmd.go's setupCommands() function or NewRootCmd() (cmd/immuadmin/command/cmd.go)
4. Add corresponding _test.go file with unit tests following the patterns in cmd_test.go (cmd/immuadmin/command/newcommand_test.go)
5. Update CONTRIBUTING.md or README.md with command documentation if user-facing (README.md)

Add platform-specific helper functionality

1. Create two files: cmd/helper/feature_unix.go and cmd/helper/feature_windows.go with OS-specific implementations (cmd/helper/feature_unix.go)
2. Define shared interface in cmd/helper/terminal.go or create new abstraction file (cmd/helper/terminal.go)
3. Add corresponding _test.go files for both Unix and Windows implementations (cmd/helper/feature_unix_test.go)
4. Test on both platforms using GitHub Actions workflows or local build commands from Makefile (Makefile)

Add container image variant

1. Create new Dockerfile in build/ directory (e.g., build/Dockerfile.lightweight) or modify existing (build/Dockerfile.lightweight)
2. Update Makefile docker targets to build the new variant (Makefile)
3. Add GitHub Actions workflow or extend push.yml to test the new image variant (.github/workflows/push.yml)
4. Document the image variant in README.md with use case and feature differences (README.md)

Add a new statistics/monitoring metric

1. Define metric structure in cmd/immuadmin/command/stats/metrics.go (cmd/immuadmin/command/stats/metrics.go)
2. Implement metric loading in cmd/immuadmin/command/stats/metricsloader.go (cmd/immuadmin/command/stats/metricsloader.go)
3. Add UI rendering logic in cmd/immuadmin/command/stats/ui.go for terminal display (cmd/immuadmin/command/stats/ui.go)
4. Add tests in cmd/immuadmin/command/stats/ui_test.go and metricsloader patterns (cmd/immuadmin/command/stats/ui_test.go)

• Go / gRPC — Core immudb is Go-based; CLI tooling uses gRPC for efficient, type-safe server communication
• Docker multi-stage builds — Enables lightweight, secure production images and specialized variants (FIPS, admin-only, full-featured)
• GitHub Actions CI/CD — Native to GitHub, enables multi-platform testing (Linux/Windows/macOS), automated releases, and container registry pushes
• Cobra CLI framework — De facto standard Go CLI library; provides command parsing, help generation, and subcommand composition
• Platform-specific code (unix/windows) — Terminal colors, path resolution, and detached process handling vary significantly; explicit build tags avoid cross-platform bugs

• Separate Unix and Windows helper files instead of conditional logic

  • Why: Improves code clarity and testability; easy to verify each platform's behavior independently
  • Consequence: Requires dual maintenance; small code duplication, but prevents subtle cross-platform issues

• Configuration stored in platform-specific paths (~/.immudb on Unix, AppData on Windows)

  • Why: Respects OS conventions; users find settings in expected locations
  • Consequence: Config management adds complexity; must handle missing/corrupted files gracefully on both platforms

• Stats/monitoring via gRPC pull (immuadmin querying immudb) rather than server push

  • Why: Simpler architecture; admin tool controls update frequency; works through firewalls
  • Consequence: Slightly higher latency for real-time monitoring; periodic polling may miss transient spikes

• Docker variants (standard, full, admin-only, FIPS) instead of single monolithic image

  • Why: Reduces attack surface; users deploy only needed components; FIPS variant for compliance
  • Consequence: Build system complexity increases; must test each variant independently in CI

• Does not provide a web UI or REST-only API (gRPC is primary protocol)
• Not a real-time monitoring/alerting system (pull-based stats only, no subscriptions)
• Does not handle multi-cluster immudb deployments (single-instance admin focus)
• Not a credential manager (uses platform OS credential stores minimally; relies on explicit authentication)

1. Port 3322 must be free (hardcoded default); override via config file or --port flag. 2) Cryptographic verification requires client-side validation—server compromise doesn't automatically alert clients; design your verification workflow carefully. 3) Go 1.24.0 minimum enforced in go.mod; older toolchains will fail. 4) FIPS mode (build/fips/) requires separate build; standard binaries use chacha20, not AES. 5) gRPC requires proto regeneration after .proto changes (protoc step not shown in Makefile—likely delegated to CI or manual invocation). 6) Prometheus metrics endpoint (default :9090 inferred) not documented in file list—check source code for exact port.

• Merkle Tree Verification — immudb's core integrity mechanism; clients verify data hasn't been tampered by replaying hash chains—understanding merkle proofs is essential to trust model
• Append-Only Log (LSM-style immutability) — immudb never deletes or modifies records; new versions create new entries—this architecture enables cryptographic proof of history
• ChaCha20-Poly1305 AEAD Encryption — immudb's default symmetric cipher (chacha20poly1305 in go.mod); provides authenticated encryption for data at rest and in transit
• Zero-Trust Security Model — immudb's foundational principle: cryptographic proofs let clients detect server compromise without trusting the database—critical to threat model
• gRPC Protocol Buffering — immudb's primary RPC transport (grpc-ecosystem/ deps); efficient binary serialization and code generation from .proto files
• Multi-Model Database (SQL/KV/Document) — immudb unifies relational, key-value, and document queries in one server; requires protocol negotiation and dual executor paths
• FIPS 140-2 Compliance — immudb supports dedicated FIPS builds (build/fips/) for regulated environments; requires certified crypto libraries and no chacha20 fallback

• ethereum/go-ethereum — Reference for cryptographic proof systems and tamper-detection; immudb borrows merkle tree verification concepts
• cockroachdb/cockroach — Competitor distributed SQL database; immudb differentiates via immutability and client-side verification instead of MVCC
• codenotary/vcn — Companion repo by same vendor; vcn provides artifact verification using immudb as backend storage
• mongodb/mongo — Alternative document database; immudb supports document model but adds cryptographic integrity guarantees
• codenotary/immudb-hands-on — Official tutorials and examples for immudb; referenced in docs.immudb.io; good for seeing real usage patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for SQL/Key-Value/Document model interactions

immudb supports three data models (SQL, Key-Value, Document) but the test coverage for cross-model interactions and edge cases appears limited based on the file structure. The repo has stress.yml and performance.yml workflows but lacks dedicated integration tests validating data consistency across these three models, especially during concurrent operations. This would strengthen the 'tamperproof' guarantee.

• [ ] Review existing tests in cmd/cmdtest/ and identify gaps in SQL-KV-Document interaction scenarios
• [ ] Create tests/integration/multimodel_test.go for cross-model ACID properties
• [ ] Add test cases for concurrent writes across different data models with verification of immutability
• [ ] Update .github/workflows/pull.yml to run integration tests on PR

Implement gRPC/Protocol Buffer documentation generator for API stability

The repo uses gRPC extensively (grpc-gateway dependency visible) but CONTRIBUTING.md and docs appear to lack auto-generated gRPC service documentation. With cmd/docs/man/generate.go already generating CLI docs, extending this to generate markdown documentation for all gRPC services would help contributors and users understand the API contract. This is critical for a 'zero trust' immutable DB where API stability matters.

• [ ] Audit .proto files to identify all gRPC services (likely in pkg/pb or similar)
• [ ] Create cmd/docs/grpc/generate.go following the pattern of cmd/docs/man/generate.go
• [ ] Generate markdown docs for each gRPC service and save to docs/grpc-api/
• [ ] Add generation step to Makefile and ci workflow (build/RELEASING.md)

Add platform-specific performance benchmarks in CI for FIPS-compliant builds

The repo has build/fips/ with FIPS compliance Dockerfiles (build/fips/check-fips.sh) but no dedicated performance benchmarks comparing standard vs FIPS-compiled builds. Given the cryptographic nature of an immutable/tamperproof database, documenting performance overhead of FIPS mode (aead/chacha20, crypto dependencies) across platforms would be valuable for operators making compliance decisions.

• [ ] Create .github/workflows/fips-benchmark.yml that builds and benchmarks both standard and FIPS versions
• [ ] Add benchmark test file tests/performance/fips_benchmark_test.go measuring throughput/latency differences
• [ ] Store results in build/benchmarks/ and reference in docs (e.g., SECURITY.md)
• [ ] Document in CONTRIBUTING.md how to run local FIPS benchmarks before submitting crypto-related PRs

• Add integration tests for immuclient + immuadmin coordination: cmd/cmdtest/ lacks scenarios validating client-side crypto verification with malicious server responses. Start by extending cmd/cmdtest/random.go and cmd/cmdtest/stdout_collector.go.
• Document FIPS build and verification: build/fips/check-fips.sh exists but build/RELEASING.md lacks step-by-step FIPS compliance validation. Add markdown instructions and example test vectors.
• Expand BUILD.md with troubleshooting section: Missing guidance on common make all failures (protoc missing, Go version mismatch, linker errors on musl-based systems). Add real error messages and solutions.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.