Code structure

Guide for navigating the rgBuilder workspace: how crates are segmented, how they connect, and where to put new functionality so it is not duplicated elsewhere.

1. Crate segmentation (overview)

flowchart TB
    subgraph entry["Entry & CLI"]
        RB["rg-build<br/>(binary + src/cli)"]
    end

    subgraph facade["Facade"]
        CORE["rgbuilder-core<br/>re-exports workspace API"]
    end

    subgraph orchestration["Orchestration"]
        PIPE["rgbuilder-pipeline<br/>discover / index repo"]
        INC["rgbuilder-incremental<br/>file tracker, deltas"]
    end

    subgraph extraction_layer["Extraction"]
        EXT["rgbuilder-extraction<br/>discover files, build graph"]
    end

    subgraph plugins["Plugin system"]
        API["rgbuilder-plugin-api<br/>LanguagePlugin trait"]
        HELP["rgbuilder-plugin-helpers<br/>tree-sitter helpers"]
        RUNTIME["rgbuilder-lang-runtime<br/>generic TS/regex plugins"]
        CFG["rgbuilder-config-formats<br/>yaml/json/toml/properties"]
        REG["rgbuilder-registry<br/>LanguageRegistry"]
        LANGS["rgbuilder-languages<br/>all Tier 1 plugins"]
        LANG["rgbuilder-lang-*<br/>(language implementations)"]
    end

    subgraph storage["Graph storage"]
        GRAPH["rgbuilder-graph<br/>CodeGraph, schema, snapshots"]
    end

    subgraph analytics["Graph analytics"]
        ANALYSIS["rgbuilder-analysis<br/>blast-radius, CFG/PDG, taint, …"]
    end

    subgraph query_export["Query & output"]
        GQL["rgbuilder-gql<br/>Cypher-like graph queries"]
        EXPORT["rgbuilder-export<br/>HTML, Mermaid, GraphML, DOT"]
    end

    subgraph cross_cutting["Cross-cutting"]
        SEM["rgbuilder-semantic<br/>signatures, IDL, types"]
        RULES["rgbuilder-rules<br/>labeling rule engine"]
        SEC["rgbuilder-security<br/>CVE / vulnerability patterns"]
        PROJ["rgbuilder-project-config<br/>.rgbuilder config, secrets, drift"]
        ERR["rgbuilder-error<br/>shared Error type"]
        MACROS["rgbuilder-macros<br/>plugin derive macros"]
    end

    RB --> CORE
    RB --> PIPE
    RB --> ANALYSIS
    RB --> GQL
    RB --> EXPORT

    CORE --> GRAPH
    CORE --> ANALYSIS
    CORE --> PIPE
    CORE --> EXT
    CORE --> GQL
    CORE --> EXPORT
    CORE --> INC
    CORE --> REG
    CORE --> SEM
    CORE --> RULES
    CORE --> SEC
    CORE --> PROJ

    PIPE --> EXT
    PIPE --> GRAPH
    PIPE --> REG

    EXT --> GRAPH
    EXT --> API

    REG --> API
    REG --> CFG
    LANGS --> REG
    LANGS --> LANG
    LANG --> API
    LANG --> HELP
    LANG --> RUNTIME

    ANALYSIS --> GRAPH
    ANALYSIS --> ERR

    GQL --> GRAPH
    GQL --> ANALYSIS

    EXPORT --> GRAPH

    INC --> GRAPH

    SEM --> API
    RULES --> GRAPH
    SEC --> GRAPH
    PROJ --> EXT

    GRAPH --> ERR
    PIPE --> ERR
    EXT --> ERR
    GQL --> ERR

    MACROS -.-> LANG

Reading the diagram: Data generally flows down and left-to-right during discover: registry → extraction → graph → analysis → persisted .rgbuilder/ artifacts. Query commands (blast-radius, gql, inspect) read the graph and analysis layers without re-parsing source unless slicing or CFG is required.

2. Segmented design (details)

Design principles

Layer responsibilities

Entry (rg-build root crate)

• src/main.rs — process entry, dispatches to CLI.
• src/cli/ — subcommands: discover, blast-radius, serve, gql, slice, inspect, metrics, semantic, communities, cpg, check, export.
• src/cli/http_serve.rs — default serve: dashboard + POST /api/query.
• src/cli/query_daemon.rs — serve --daemon; optional blast-radius client when .rgbuilder/query.sock exists (RGBUILDER_NO_QUERY_DAEMON=1 to disable).
• src/cli/*_output.rs — typed JSON serializers (blast_radius_output, discover_output, gql_output, …). Commands assemble domain results from workspace crates and serialize here; do not embed algorithm logic in output modules.
• src/languages/ — wires the active language bundle into a LanguageRegistry at runtime.
• Re-exports rgbuilder-core for library users (use rg-build::analysis, etc.).

Put new user-facing commands here; implement behavior in the appropriate workspace crate.

Facade (rgbuilder-core)

Stable “library surface” for embedders: re-exports graph, analysis, pipeline, export, gql, incremental, registry, rules, semantic, security, project-config. Also hosts memory monitoring helpers used during discover.

If you add a new workspace crate that external tools should use, export it through rgbuilder-core (and optionally the root rg-build crate).

Plugin system

Language crates (rgbuilder-lang-*): One crate per language or config dialect (e.g. rgbuilder-lang-java, rgbuilder-lang-github-actions). Each registers a plugin with the registry. Do not add parsing logic for an existing language in another language crate — extend the relevant rgbuilder-lang-* plugin instead. For Tier 1 / full analysis parity, see tier-1-language-support.md.

Ingestion pipeline

Discover flow: CLI discover → discover_impl → ProcessingPipeline → plugins → CodeGraph → analysis passes → write .rgbuilder/.

Graph storage (rgbuilder-graph)

• CodeGraph — high-level API over the backend.
• backend/ — MemoryBackend, indexes, batch insert, query.
• schema/ — Node, Edge, NodeType, EdgeType.
• snapshot/ — columnar v2 mmap snapshots (graph.snapshot.bin, 64B node / 40B edge rows + string pool); v1 bincode still readable. SnapshotNodeStore, ColumnarGraphMmap.
• export/ / import_json — JSON serialization (legacy graph.db).
• query/ — simple string queries over the backend.

All persistent graph topology belongs here. Analysis results that attach to nodes may use rgbuilder-analysis::results columnar tables, not new graph backends.

Graph analytics (rgbuilder-analysis)

Single home for graph algorithms and semantic analysis:

Do not reimplement SCC blast radius, PageRank, community detection, or CFG building outside this crate.

Query & export

Cross-cutting

Where CLI commands map

On-disk artifacts (.rgbuilder/)

Understanding files helps avoid duplicating cache layers:

3. Crate reference (non-language)

Alphabetical list of workspace crates excluding individual rgbuilder-lang-* plugins.

Language implementations (rgbuilder-lang-*)

There are many crates named rgbuilder-lang-<language> (and a few for CI/config dialects). Each implements LanguagePlugin (or a config plugin) for one language or format. They are registered through rgbuilder-registry and rgbuilder-languages — not linked directly from analysis or graph code.

When adding or fixing language support:

1. Change or add a rgbuilder-lang-* crate.
2. Register it in rgbuilder-languages.
3. Do not add language-specific parsing to rgbuilder-analysis or src/cli/.

Quick “where do I put this?” table

Related docs: user-guide.md, json-api.md, dashboard-design.md, cli-io-sanity-qe.md, graph-storage-architecture.md, CLI_STRUCTURE.txt.