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/vesoft-inc/nebula 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 all four use cases

• Last commit 7mo ago
• 34+ active contributors
• Distributed ownership (top contributor 29% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 7mo ago

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

What it runs against: a local clone of vesoft-inc/nebula — 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 vesoft-inc/nebula | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 229 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of vesoft-inc/nebula. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/vesoft-inc/nebula.git
#   cd nebula
#
# 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 vesoft-inc/nebula and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "vesoft-inc/nebula(\\.git)?\\b" \\
  && ok "origin remote is vesoft-inc/nebula" \\
  || miss "origin remote is not vesoft-inc/nebula (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "cmake/nebula/GeneralCMakeConfig.cmake" \\
  && ok "cmake/nebula/GeneralCMakeConfig.cmake" \\
  || miss "missing critical file: cmake/nebula/GeneralCMakeConfig.cmake"
test -f "cmake/nebula/ThirdPartyConfig.cmake" \\
  && ok "cmake/nebula/ThirdPartyConfig.cmake" \\
  || miss "missing critical file: cmake/nebula/ThirdPartyConfig.cmake"
test -f "conf/nebula-graphd.conf.default" \\
  && ok "conf/nebula-graphd.conf.default" \\
  || miss "missing critical file: conf/nebula-graphd.conf.default"
test -f "conf/nebula-storaged.conf.default" \\
  && ok "conf/nebula-storaged.conf.default" \\
  || miss "missing critical file: conf/nebula-storaged.conf.default"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 229 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~199d)"
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/vesoft-inc/nebula"
  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).

NebulaGraph is a distributed, horizontally-scalable open-source graph database written in C++ that processes large volumes of property graph data with millisecond-latency queries. It separates storage and compute layers, uses RAFT consensus for strong consistency, and implements an OpenCypher-compatible query language for social networks, knowledge graphs, recommendation systems, and financial transaction analysis. Monorepo structure: src/ contains storage/query/metadata engines; proto/ and thrift/ define RPC schemas; tests/ for unit and integration tests organized by component; cmake/ handles cross-platform builds with dependency discovery for Folly, Glog, and other C++ libraries. GitHub Actions orchestrate CI across nightly, PR, and release workflows.

Infrastructure engineers and database architects deploying large-scale graph infrastructure, data platform teams building knowledge graphs and recommendation engines, and C++ systems engineers contributing to a mature distributed database codebase.

Production-ready and actively maintained. The monorepo consolidation (v2.6.0+) shows architectural maturity; extensive CI/CD workflows (.github/workflows/) cover nightly builds, code analysis (codeql), and release management. The project has thousands of GitHub stars and is used by enterprise customers. Actively developed with multiple GitHub Actions for automated testing and asset management.

Relatively low risk for a distributed system. Heavy C++ dependency footprint (10M+ lines) requires proficiency in modern C++ and understanding of distributed consensus. The codebase transitioned from multi-repo to monorepo structure; legacy split repos (nebula-graph, nebula-storage, nebula-common) are archived but may create confusion. Build system complexity (CMake with custom FindXXX modules for Folly, Fbthrift, Breakpad) can be brittle across environments.

Active development on distributed consensus, query optimization, and storage layer improvements. Multiple GitHub workflows running automatically: nightly builds, CodeQL security analysis, PR validation (pull_request.yml), release candidate management (rc.yml), and cherry-pick automation (auto_cherry_pick.yml). Code style enforcement via .clang-format, .clang-tidy, and custom linters in .linters/cpp/.

git clone https://github.com/vesoft-inc/nebula.git
cd nebula
mkdir build && cd build
cmake ..
make -j$(nproc)
make install

Refer to CMakeLists.txt for build targets and cmake/ for platform-specific dependency resolution (requires Folly, Glog, Gflags, Fbthrift).

Daily commands: After building with cmake: ./bin/nebula-metad (metadata service), ./bin/nebula-storaged (storage daemon), ./bin/nebula-graphd (query service). Configuration via flags (see .gflags definitions). For development: make test runs suite; see .github/workflows/pull_request.yml for CI test sequence.

• CMakeLists.txt — Root build configuration; defines the entire compilation pipeline, third-party dependencies, and module discovery for this distributed graph database
• cmake/nebula/GeneralCMakeConfig.cmake — Core Nebula build system configuration; sets compiler flags, optimization levels, and platform-specific settings that affect all compiled components
• cmake/nebula/ThirdPartyConfig.cmake — Manages critical dependencies (RocksDB, Folly, Thrift, glog) essential for the database kernel; any version mismatch breaks the entire system
• conf/nebula-graphd.conf.default — Default Graph API daemon configuration; defines query execution parameters, connection limits, and query optimizer settings developers must understand
• conf/nebula-storaged.conf.default — Storage daemon configuration; controls partitioning, replication, and RocksDB tuning—critical for understanding data persistence and HA architecture
• .github/workflows/pull_request.yml — CI/CD pipeline enforcing code quality standards; defines linting, sanitization, and test requirements all contributors must pass
• Coding_Style_Guide.md — Mandatory style and architectural guidelines for C++ contributions; non-compliance blocks PR merges

Add a new graph storage feature (e.g., new index type)

1. Define the feature's CMake module in cmake/nebula/ following NebulaCMakeMacros conventions (cmake/nebula/NebulaCMakeMacros.cmake)
2. Add configuration parameters to storaged config template with sensible defaults (conf/nebula-storaged.conf.default)
3. Update code style and architectural requirements in the Coding Style Guide (Coding_Style_Guide.md)
4. Add unit tests and integration tests; ensure they pass PR workflow checks (.github/workflows/pull_request.yml)
5. Document your feature in the RFC template for design review (docs/rfcs/0000-template.md)

Upgrade a critical third-party dependency (e.g., RocksDB version)

1. Update the find module to detect new library version (cmake/FindRocksdb.cmake)
2. Verify linker flags and ABI compatibility in LinkerConfig (cmake/nebula/LinkerConfig.cmake)
3. Update third-party config to fetch new version (cmake/nebula/ThirdPartyConfig.cmake)
4. Run extended nightly test suite to catch regressions (.github/workflows/nightly.yml)
5. Pin the new version in master build configuration (CMakeLists.txt)

Add platform support (e.g., ARM64 optimizations)

1. Add architecture-specific detection in PlatformCheck (cmake/nebula/PlatformCheck.cmake)
2. Define platform-specific compiler flags in GeneralCompilerConfig (cmake/nebula/GeneralCompilerConfig.cmake)
3. Update daemon configs with platform-tuned defaults (e.g., thread counts) (conf/nebula-storaged.conf.default)
4. Add platform-specific sanitizer and linker configs if needed (cmake/nebula/SanitizerConfig.cmake)
5. Enable nightly builds for the new platform (.github/workflows/nightly.yml)

• CMake + C++ — Enables cross-platform compilation (Linux, macOS, Windows), close-to-metal performance for distributed graph algorithms, and fine-grained control over memory and threading
• RocksDB — Provides high-throughput, low-latency key-value storage with strong consistency and compression—critical for graph edge/vertex persistence at scale
• Thrift — Language-agnostic RPC framework enabling polyglot client libraries (Go, Python, Java) and efficient binary serialization for inter-daemon communication
• Folly — Facebook's modern C++ library providing lock-free data structures, async I/O primitives, and high-performance utilities reducing custom wheel-reinvention
• glog + gflags — Production-grade logging and command-line flag parsing; essential for operating distributed systems with distributed tracing and runtime tuning

• Three-tier daemon architecture (graphd, metad, storaged) vs. monolithic design

  • Why: Allows independent scaling of compute, metadata, and storage; enables rolling upgrades and fault isolation
  • Consequence: Increased operational complexity; inter-daemon network overhead; requires careful transaction coordination

• Thrift RPC for inter-daemon communication vs. gRPC

  • Why: Thrift has mature C++ bindings, lower overhead for binary protocols, and proven battle-tested in Meta/LinkedIn systems
  • Consequence: Fewer language bindings than gRPC; less built-in HTTP/2 multiplexing; requires manual batch optimization

• Graph partitioning by vertex ID vs. edge-based partitioning

  • Why: Vertex partitioning simplifies consistency, reduces transaction span across partitions, and aligns with most graph workloads
  • Consequence: Hot vertices (hubs) cause uneven load; cross-partition edges may require multi-hop queries

• CMake as build system vs. Bazel/Ninja-only

  • Why: CMake offers portable dependency management, easier integration with system packages, and lower learning curve for C++ teams
  • Consequence: Build configuration is verbose; longer build times on cold cache vs. incremental Bazel builds; platform-specific quirks

• Real-time streaming ingestion (batch/OLTP focused; OLAP analytics delegated to external ETL)
• Schema-free design (enforces strong typing for predictability and optimization)
• Single-node embedded mode (requires distributed cluster; no in-process library mode)
• SQL dialect (uses nGQL, a Cypher-like DSL; no SQL compatibility layer)
• Multi-tenancy with resource isolation (shared-nothing architecture assumes single tenant per cluster)

RAFT consensus implementation requires deep understanding of distributed state machines and failure modes—don't assume strong consistency without reading consensus logs. Thrift RPC layer: changes to .thrift files don't auto-regenerate; must re-run CMake or explicitly invoke thrift compiler. Build system: custom cmake/ FindXXX modules can fail silently if dependencies (Folly, Glog, Fbthrift) aren't installed in standard paths; set CMAKE_PREFIX_PATH if build fails. Graph query execution spans src/graph/ and src/storage/; query planner lives in src/graph/planner/ while execution operators are split; touching both requires understanding push-down semantics. Pre-commit hooks in .linters/cpp/hooks/ are not enforced by default—CI will fail if you skip formatting; run manually: python cpplint.py. Storage snapshot/recovery: RAFT logs can diverge if clock skew exists between nodes; synchronize system clocks before deployment.

• RAFT Consensus — NebulaGraph uses RAFT for strong consistency across distributed storage replicas; understanding leader election, log replication, and snapshotting is essential to debug data loss or split-brain scenarios
• Graph Query Planning and Execution — The core of NebulaGraph: src/graph/planner/ transforms OpenCypher into an optimized execution plan; src/graph/executor/ interprets that plan. This pattern (planning → execution) is central to how queries run
• Property Graph Model — NebulaGraph stores vertices and edges with typed properties; understanding schema-less vs schema-enforced trade-offs is key to data modeling and query correctness
• Storage Engine Separation (LSM Tree / KV Store) — NebulaGraph's storage layer abstracts over key-value backends; familiarity with log-structured merge trees, write amplification, and compaction helps optimize storage I/O patterns
• RPC Protocol Serialization (Thrift) — NebulaGraph uses Apache Thrift for inter-service communication (graph ↔ storage, meta ↔ storage); understanding .thrift schema evolution and backward compatibility is critical for distributed upgrades
• OpenCypher Graph Query Language — NebulaGraph's primary query interface; developers must understand Cypher syntax (MATCH, WHERE, RETURN) and semantic differences from SQL for correct query writing and debugging
• Asynchronous I/O and Futures (Folly Library) — NebulaGraph's concurrency model relies heavily on folly::Future for async RPC calls and query execution; understanding callback chains and exception handling is crucial for debugging deadlocks or request timeouts

• apache/incubator-hugegraph — Alternative open-source graph database (Java-based) with similar distributed architecture; common architecture patterns like separation of storage and compute
• JanusGraph/janusgraph — Distributed graph database backend using pluggable storage engines; shares OLTP graph query patterns and storage layer design philosophy with NebulaGraph
• vesoft-inc/nebula-python — Official Python client library for NebulaGraph; used by practitioners to connect applications to the database
• vesoft-inc/nebula-studio — Official web UI / query IDE for NebulaGraph; frontend companion tool for database management and graph visualization
• opencypher/openCypher — Reference implementation and specification for Cypher query language that NebulaGraph implements; crucial for understanding query semantics

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 ClangTidy integration tests in CI/CD pipeline

The repo has .clang-tidy configuration and cmake/ClangTidy.cmake setup, but there's no dedicated GitHub Actions workflow to enforce clang-tidy checks on PRs. This would catch code quality issues early and ensure consistency with the repo's C++ standards defined in Coding_Style_Guide.md.

• [ ] Review .clang-tidy configuration and cmake/ClangTidy.cmake to understand current setup
• [ ] Create new workflow file .github/workflows/clang-tidy-check.yml that runs on pull_request events
• [ ] Configure workflow to run clang-tidy against modified C++ files and comment results on PR
• [ ] Test locally using existing CMake configuration before submitting
• [ ] Reference existing workflows like pull_request.yml for CI pattern consistency

Implement pre-commit hook validation in CI

The repo contains .linters/cpp/hooks/pre-commit.sh for local linting but no automated enforcement. Adding a CI check to validate that contributors have properly formatted code (via clang-format defined in .clang-format) would reduce lint-and-fix commit noise.

• [ ] Examine .clang-format configuration and .linters/cpp/cpplint.py to understand style rules
• [ ] Create .github/workflows/code-format-check.yml that runs clang-format in check-only mode
• [ ] Add step to fail if formatting issues are found, with instructions to run local pre-commit hook
• [ ] Document in CONTRIBUTING.md how to run pre-commit hooks locally before pushing
• [ ] Consider adding GitHub Action that auto-fixes and commits formatting (optional enhancement)

Add missing CMake FindModule documentation and tests

The cmake/ directory contains many FindXXX.cmake modules (FindRocksdb.cmake, FindFolly.cmake, FindGlog.cmake, etc.) but likely lacks tests verifying these modules correctly locate dependencies across different environments. Adding unit/integration tests would catch broken dependency resolution early.

• [ ] Audit all cmake/Find*.cmake files to document their expected behavior and variables they set
• [ ] Create cmake/tests/ directory with test scripts that verify each FindModule can locate dependencies
• [ ] Add CI workflow .github/workflows/cmake-tests.yml to validate FindModule behavior on multiple OS/compiler combinations
• [ ] Document findings in cmake/README.md or CONTRIBUTING.md about dependency resolution
• [ ] Test with different cmake configurations (with/without system libraries) to ensure robustness

• Add missing unit tests for graph/executor/ operators that lack test coverage—many execution nodes (like Join, Aggregate) have minimal isolated tests despite being critical path. Start with JoinExecutor tests to understand executor pattern.: tests/storage/ExecTest.cpp
• Expand documentation in src/interface/*.thrift with detailed comments explaining RPC contract semantics (e.g., what happens on storage timeout, which fields are optional). Many .thrift files are schema-only with no semantic docs.: src/interface/
• Add CMake configuration validation: detect conflicting Folly/Fbthrift versions early and provide clear error messages. Currently build failures from version mismatches are cryptic. See cmake/FindFbthrift.cmake and similar for patterns.: cmake/FetchModule.cmake

The Nebula graph database project demonstrates reasonable security awareness with CI/CD pipelines, static analysis tooling, and security documentation. However, several areas require attention: configuration file management to prevent credential leakage, input validation patterns for query execution to prevent injection attacks, Docker security hardening, GitHub Actions workflow security, and dependency management. The codebase structure suggests a mature project, but without deep code analysis, potential vulnerabilities in query parsing and execution layers cannot be fully assessed. Recommended immediate actions: review configuration handling, audit GitHub Actions workflows, enable comprehensive clang-tidy security checks, and implement dependency scanning in CI/CD.

• Medium · Potential hardcoded credentials in configuration files — conf/ directory. Configuration files are present in the repository (nebula-graphd.conf.default, nebula-metad.conf.default, nebula-storaged-listener.conf.default, nebula-standalone.conf.default). While these appear to be default/template files, there is a risk that sensitive information like passwords, API keys, or database credentials could be accidentally committed to version control. Fix: Ensure configuration files containing secrets are never committed to the repository. Use environment variables or secure vaults for sensitive data. Document in CONTRIBUTING.md that contributors must use .gitignore for local config files with credentials.
• Medium · Missing input validation patterns in codebase structure — src/ (not fully provided, but likely in query execution modules). The codebase is a graph database with query execution capabilities. Without direct code review, potential injection vulnerabilities (Cypher/Query injection equivalent) could exist in query parsing and execution layers if user inputs are not properly sanitized. Fix: Implement parameterized queries and prepared statements throughout the codebase. Conduct security-focused code review of query parsing modules. Add input validation frameworks and sanitization utilities.
• Medium · Docker configuration exposure risk — .dockerignore, Docker-related configurations. The presence of .dockerignore and multiple Dockerfile references suggests containerized deployment. Docker images could potentially expose sensitive build arguments, environment variables, or internal service credentials if not properly configured. Fix: Review Dockerfile(s) to ensure: (1) Multi-stage builds are used to exclude build tools, (2) Secrets are passed as build args with --secret flag, not ENV, (3) .dockerignore properly excludes sensitive files, (4) No credentials hardcoded in images.
• Low · GitHub Actions workflow security — .github/workflows/ directory. Multiple GitHub Actions workflows are present (.github/workflows/) including release, upload, and deployment pipelines. These workflows may have elevated permissions and could be vectors for supply chain attacks if not properly secured. Fix: Review all workflow files for: (1) Principle of least privilege on permissions, (2) Pinned action versions (avoid 'latest'), (3) Secret management best practices, (4) Approval requirements for sensitive operations, (5) Use of trusted third-party actions only.
• Low · C++ compiler and linter configuration — .clang-tidy, .clang-format. The presence of .clang-tidy and .clang-format configuration files suggests the project uses these tools. However, without reviewing the actual configurations, there's no assurance that security-relevant linting rules are enabled. Fix: Ensure .clang-tidy includes security checks: enable -checks=,-readability- to catch potential security issues. Enable compiler warnings with -Wall -Wextra -Wpedantic flags in CMakeLists.txt.
• Low · Third-party dependency management — cmake/Find*.cmake files, CMakeLists.txt. The project has numerous external dependencies (RocksDB, Folly, Thrift, Jemalloc, etc.) managed through CMake find modules. Without visible dependency version pinning or security scanning, there's risk of using outdated or vulnerable transitive dependencies. Fix: Implement dependency version pinning. Use tools like OWASP Dependency-Check or Snyk in CI/CD pipelines. Regularly update and audit dependencies. Document minimum version requirements with security 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.