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/dgraph-io/dgraph 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
• 17 active contributors
• Distributed ownership (top contributor 35% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{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 dgraph-io/dgraph repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dgraph-io/dgraph.

What it runs against: a local clone of dgraph-io/dgraph — 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 dgraph-io/dgraph | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main 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 dgraph-io/dgraph. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dgraph-io/dgraph.git
#   cd dgraph
#
# 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 dgraph-io/dgraph and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "codec/codec.go" \\
  && ok "codec/codec.go" \\
  || miss "missing critical file: codec/codec.go"
test -f "algo/uidlist.go" \\
  && ok "algo/uidlist.go" \\
  || miss "missing critical file: algo/uidlist.go"
test -f "conn/pool.go" \\
  && ok "conn/pool.go" \\
  || miss "missing critical file: conn/pool.go"

# 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/dgraph-io/dgraph"
  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).

Dgraph is a horizontally scalable, distributed GraphQL database with a native graph backend that provides ACID transactions, consistent replication, and linearizable reads. It optimizes query performance by tightly controlling on-disk data arrangement to minimize seeks and network calls, serving GraphQL queries over terabytes of structured data with sub-millisecond latency. Monolithic Go project organized by functional domain: /acl handles authorization, /dql likely contains query language parsing, /dgraph core database engine with distributed consensus (via etcd/raft), /graphql for GraphQL schema and query execution. CI/CD heavily containerized via Docker (Dockerfile, .dockerignore) and orchestrated through 14+ GitHub Actions workflows. Build system uses Make (Makefile) with language-specific tool integration (golangci, hadolint, shellcheck configured in .trunk/)

DevOps engineers and backend developers building real-time applications (e.g., recommendation engines, knowledge graphs, social networks) who need a production-grade graph database supporting ACID transactions across multiple nodes without sacrificing query performance or consistency guarantees.

Dgraph is production-ready at v25.0.0 with 23.7k GitHub stars and active enterprise adoption. The codebase shows extensive CI coverage (14 distinct test workflows in .github/workflows/), comprehensive test suites (core, integration2, jepsen, ldbc, systest, vector, upgrade tests), and frequent commits. This is a mature, actively maintained project backed by a commercial company.

The project has substantial Go dependencies (60+ in go.mod) including complex ones like etcd/raft, badger v4, and blevesearch, increasing maintenance burden. The large monolithic codebase (6.9MB of Go code) and complex distributed systems semantics (Raft consensus, ACID transactions) make contributions risky without deep domain knowledge. Dependency updates via renovate.json and nightly CVE testing mitigate some risk, but the breadth of features creates a large attack surface.

Active development across multiple fronts: vector database support (ci-dgraph-vector-tests.yml), upgrade path testing (ci-dgraph-upgrade-fixed-versions-tests.yml, ci-dgraph-weekly-upgrade-tests.yml), ARM64 support (ci-dgraph-tests-arm64.yml), and security hardening (ci-dgraph-nightly-cves.yml). The nightly build pipeline (cd-dgraph-nightly.yml) and standard CD pipeline (cd-dgraph.yml) indicate continuous feature releases. Jepsen and LDBC testing suggest active work on consistency verification and benchmark compliance.

git clone https://github.com/dgraph-io/dgraph.git
cd dgraph
# Requires Go 1.26.3+ (from go.mod)
go build ./cmd/dgraph
# Or use Docker (recommended per README)
docker pull dgraph/dgraph:latest
docker run -it -p 8080:8080 -p 9080:9080 dgraph/dgraph:latest dgraph zero

Daily commands:

# Zero node (cluster manager)
docker run -it -p 5080:5080 dgraph/dgraph:latest dgraph zero
# Alpha node (query processor) in separate terminal
docker run -it -p 8080:8080 -p 9080:9080 --link dgraph-zero:zero dgraph/dgraph:latest dgraph alpha --zero=zero:5080
# Query via HTTP on :8080 or GRPC on :9080

• Makefile — Build orchestration for the entire Dgraph project; defines compilation targets, test execution, and deployment workflows.
• go.mod — Declares all Go dependencies including Badger (storage), gqlgen (GraphQL), and Ristretto (caching); critical for reproducible builds.
• codec/codec.go — Core serialization/deserialization logic for storing and retrieving graph data; fundamental to data persistence layer.
• algo/uidlist.go — Efficient UID (unique identifier) management and list operations; central to graph traversal performance.
• conn/pool.go — Connection pooling for distributed Dgraph nodes; enables horizontal scalability and cluster communication.
• backup/run.go — Backup and restore functionality; critical for data durability and disaster recovery in production systems.
• acl/acl.go — Access control list implementation with JWT support; essential for securing multi-tenant deployments.

Add a new graph traversal algorithm

1. Create algorithm implementation in algo/ directory following uidlist.go patterns (algo/new_algorithm.go)
2. Add unit tests with benchmark comparisons (algo/new_algorithm_test.go)
3. Register algorithm in codec for query execution planning (codec/codec.go)
4. Document complexity guarantees and use cases in README or algo/doc.go (algo/doc.go)

Add a new data source connector (e.g., Kafka ingestion)

1. Create parser module similar to chunker/json_parser.go (chunker/kafka_parser.go)
2. Implement Reader interface and batch serialization logic (chunker/kafka_parser.go)
3. Add end-to-end tests with sample data (chunker/kafka_parser_test.go)
4. Register in Makefile test targets and CI workflows (.github/workflows/ci-dgraph-core-tests.yml)

Extend ACL with new permission model

1. Enhance ACL rule evaluation in acl/acl.go (acl/acl.go)
2. Add new JWT claims handling in acl/utils.go (acl/utils.go)
3. Update audit logging to track new permission decisions (audit/audit.go)
4. Add integration tests with curl examples (acl/acl_curl_test.go)

Add monitoring/observability for a new subsystem

1. Instrument code with OpenCensus metrics (see audit/interceptor.go pattern) (new_subsystem/monitoring.go)
2. Update Prometheus scrape config if metrics endpoint needed (compose/prometheus.yml)
3. Add histogram and counter metrics to go.mod dependencies if needed (go.mod)

• Badger v4 (embedded LSM store) — Provides persistent, ordered key-value storage optimized for graph index locality; ACID properties enable consistent replication.
• Raft consensus (conn/raft_server.go) — Ensures linearizable reads and fault-tolerant replication across distributed nodes without external coordination service.
• gqlgen + gqlparser — Native GraphQL schema generation and parsing; tightly couples database schema to query API for zero impedance mismatch.
• Ristretto (distributed cache) — High-performance, bounded in-memory cache for query plans and hot data; reduces disk I/O and latency for repeated access patterns.
• Go 1.26.3 — Enables efficient concurrent graph traversal via goroutines; native support for distributed systems patterns (channels, context).
• OpenCensus + Prometheus — Real-time observability for query latency, throughput, and cluster health; integrates with standard monitoring stacks.

• Embedded storage (Badger) vs. separate database

  • Why: Tight coupling optimizes for query performance by controlling data layout; eliminates network round-trips within a node.
  • Consequence: Requires operational complexity for backup/restore and makes multi-node scaling harder than sharded external databases; state cannot be trivially moved.

• GraphQL as first-class schema language vs. property graph model

  • Why: Enforces schema discipline and leverages GraphQL ecosystem; reduces impedance for client applications.
  • Consequence: Less flexible for ad-hoc data exploration; schema changes require careful coordination in production.

• Raft for consensus vs. eventual consistency

  • Why: Provides ACID transactions and linearizable reads; critical for financial/transactional workloads.
  • Consequence: Higher write latency (quorum waits); cannot partition during network splits (loses availability).

• Binary codec (codec/codec.go) vs. JSON storage

  • Why: Reduces storage footprint and deserialization cost for graph traversals; enables efficient UID list compression (algo/cm-sketch.go).
  • Consequence: Proprietary on-disk format; makes direct inspection/debugging harder without tooling.

• Full-text search (delegates to Bleve integration, not primary feature)
• Real-time collaborative editing (optimized for batch transactions, not OT/CRDT)
• Triggers and stored procedures (stateless execution model)
• Multi-database joins (single logical database per cluster)
• Automatic sharding configuration (requires manual shard key specification)

Raft/consensus complexity: Modifying distributed transaction logic requires deep understanding of etcd/raft and ACID semantics; tests like jepsen (ci-dgraph-jepsen-tests.yml) validate linearizability non-trivially. Platform constraints: Official support only on Linux/amd64 and Linux/arm64 (dropped Mac/Windows support in 2021); macOS/Windows builds may silently fail in CI. Schema evolution: GraphQL schema changes require careful migration planning due to stored metadata; breaking schema changes may require data reload. Cluster bootstrap: Zero and Alpha nodes must be carefully coordinated (zero:5080 must be advertised correctly); misconfigured --zero flags cause cluster formation failures. Docker-first culture: Repository assumes Docker for testing/deployment; bare-metal builds require manual toolchain setup (protoc for .proto compilation, etc.).

• Raft Consensus — Dgraph uses etcd/raft v3 to maintain consistency and leader election across distributed nodes; understanding Raft is essential for debugging replication issues and cluster failures
• ACID Transactions — Dgraph's core differentiator is strong ACID guarantees across multiple nodes via badger v4; breaking transaction semantics is a critical bug
• Linearizable Reads — Dgraph provides linearizability (stronger than eventual consistency); jepsen tests validate this; understanding read-after-write consistency is required for debugging replication edge cases
• Protocol Buffers (protobuf) — Dgraph uses protobuf for GRPC message serialization and schema definitions; understanding .proto file structure is needed for API changes
• GraphQL Schema Stitching — Dgraph's native GraphQL layer (gqlparser v2, gqlgen) auto-generates resolvers from schema; modifying schema handling requires knowledge of this code generation
• Write-Ahead Logging (WAL) — Badger v4 (the embedded KV store) uses WAL for durability; understanding log structure is crucial for debugging data corruption or recovery issues
• SIMD JSON Parsing — Dgraph uses simdjson-go for fast JSON deserialization of GraphQL queries; CPU-specific performance regressions may surface here

• dgraph-io/badger — Embedded key-value store that powers Dgraph's on-disk storage layer (v4 is a hard dependency)
• dgraph-io/dgo — Official Go client library for Dgraph; essential for building applications that query a running Dgraph instance
• dgraph-io/gqlparser — GraphQL query parser used by Dgraph to validate and execute incoming GraphQL requests
• etcd-io/etcd — Dgraph uses etcd/raft v3 for distributed consensus and leader election across cluster nodes
• neo4j/neo4j — Primary competitor: graph database with different consistency/replication model (eventual vs. strong ACID)

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 ACL JWT algorithm validation

The acl/ directory contains jwt_algo_test.go but lacks integration tests covering edge cases like token expiration, invalid signatures, and algorithm mismatches across distributed nodes. Given Dgraph's emphasis on ACID transactions and security, robust ACL testing is critical. The existing acl_integration_test.go and integration_test.go could be expanded to cover JWT-specific scenarios that interact with the graph backend.

• [ ] Review existing test coverage in acl/jwt_algo_test.go and acl/acl_integration_test.go
• [ ] Add integration tests for JWT token expiration and refresh scenarios
• [ ] Add tests for algorithm mismatch attacks and signature validation failures
• [ ] Test JWT validation across multi-node Dgraph clusters (using the existing upgrade_test.go patterns)
• [ ] Verify tests pass using TESTING.md guidelines

Add CI workflow for vector search feature validation

The repo includes ci-dgraph-vector-tests.yml in the workflows directory, but no corresponding comprehensive documentation or validation suite for vector search capabilities. Given Dgraph's positioning as a real-time graph database and the dependencies on simdjson-go (v0.3.0) and viterin/vek (v0.4.3), there's an opportunity to add detailed vector operation tests and benchmark workflows to ensure performance regression detection.

• [ ] Examine ci-dgraph-vector-tests.yml to understand current test scope
• [ ] Create a new test file (e.g., algo/vector_operations_test.go) for vector-specific algorithms
• [ ] Add benchmarks for common vector operations (dot product, cosine similarity, etc.)
• [ ] Update the CI workflow to include performance regression detection against baseline metrics
• [ ] Document vector search capabilities in TESTING.md with specific test invocation commands

Refactor and expand audit logging test coverage

The audit/ directory contains only audit.go with no corresponding *_test.go files, despite audit logging being critical for compliance and security in a production graph database. This represents a significant testing gap. With ACL integration and compliance features, comprehensive audit trail validation is essential.

• [ ] Create audit/audit_test.go with unit tests for audit event creation and formatting
• [ ] Create audit/audit_integration_test.go testing audit logs across ACL operations and mutations
• [ ] Add tests verifying audit log immutability and timestamp accuracy
• [ ] Test audit log rotation and retention policies (if implemented)
• [ ] Add tests validating audit log output to various backends (file, syslog, etc.) if supported
• [ ] Reference acl/acl_integration_test.go patterns for test structure consistency

• Add GraphQL schema validation tests for edge cases in /graphql directory—currently Jepsen (ci-dgraph-jepsen-tests.yml) validates consistency but schema mutation tests may be sparse. Look at existing test patterns in *_test.go files.
• Improve error messages in ACL authorization failures (acl/acl.go)—add specific predicate/namespace context to denials so users understand exactly which permissions are missing, similar to how major databases do it.
• Expand documentation in TESTING.md for how to run individual test suites from .github/workflows/ locally (core-tests, integration2, systest, vector)—currently developers must extract commands from YAML, making reproduction slow.

Dgraph's security posture is moderate with several areas requiring attention. The codebase demonstrates good security practices with dedicated security reporting channels (SECURITY.md) and use of security-focused dependencies (HashiCorp Vault, OpenTelemetry). However, critical concerns include: (1) presence of

• Medium · Outdated Go Version in Dockerfile — Dockerfile, Stage I. The Dockerfile specifies golang:1.25.0 as the base image for building, which may contain security vulnerabilities. Go 1.25.0 is older than the current go.mod requirement of go 1.26.3, creating a version mismatch between development and build environments. Fix: Update the builder stage to use golang:1.26.3 or later to match go.mod specifications and ensure all security patches are applied. Additionally, pin exact digest hashes instead of just version tags.
• Medium · Outdated Ubuntu Base Image — Dockerfile, Stage II. The Dockerfile uses ubuntu:24.04 without specifying a digest hash. Base images should be pinned to specific digests to prevent supply chain attacks and ensure reproducible builds. Additionally, package versions should be verified. Fix: Pin the Ubuntu image to a specific digest hash (e.g., ubuntu:24.04@sha256:...) and consider using distroless images for smaller attack surface. Regularly update base images to patch OS-level vulnerabilities.
• Medium · Hardcoded File Reference - HMAC Secret — acl/hmac-secret. The file 'acl/hmac-secret' appears in the repository structure. This suggests hardcoded cryptographic material may be present in the repository, which is a security risk if credentials or secrets are committed. Fix: Ensure this file is added to .gitignore immediately. Move all secrets to environment variables, secrets management systems (HashiCorp Vault is already a dependency), or configuration management tools. Rotate any secrets that may have been exposed.
• Low · Missing Security Headers Configuration — Web server configuration (not explicitly visible in provided files). No explicit security headers configuration is visible in the codebase structure review. GraphQL endpoints and web servers should implement HSTS, CSP, X-Content-Type-Options, and other security headers. Fix: Implement middleware for security headers. Ensure CORS is properly configured, CSP headers are set, and X-Content-Type-Options is configured to 'nosniff'.
• Low · Sensitive Test Files Exposure — audit/testfiles/zero_audit_0_1.log.enc. Directory 'audit/testfiles' contains 'zero_audit_0_1.log.enc' - an encrypted audit log. Test files with sensitive data should not be committed to repositories. Fix: Remove sensitive test files from repository. Use mocked data or fixtures instead. If retention is necessary, ensure the data is properly sanitized and does not contain production credentials.
• Low · Incomplete Dependency List — go.mod. The go.mod file snippet appears incomplete ('go.opentelemetry.io/contrib/instrumentati...'). Full dependency verification cannot be completed, potentially masking vulnerable transitive dependencies. Fix: Ensure complete go.mod and go.sum files are maintained. Use 'go mod verify' in CI/CD. Implement automated dependency scanning using tools like 'go list -json -m all' and vulnerability checkers.
• Low · Docker Image Copy Incomplete in Dockerfile — Dockerfile, Stage II. The final Dockerfile stage contains an incomplete COPY command ('COPY -' without destination or complete path), which indicates potential configuration issues. Fix: Complete and validate all COPY directives in the Dockerfile. Ensure only necessary artifacts are copied into the final image to minimize attack surface.
• Low · No Image Scanning Configuration — .trunk/configs/.trivyignore.yaml, GitHub workflows. The .trunk configuration references '.trivyignore.yaml' but no image scanning workflows are explicitly visible for container security scanning. Fix: Implement automated container image scanning in CI/CD using Trivy, Snyk, or similar tools. Add image signing and verification steps. Document any ignored vulnerabilities with justification.

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.