# knacklabs/blarify architecture

> Architecture diagram of the GitHub repository knacklabs/blarify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/knacklabs/blarify
- Repository: https://github.com/knacklabs/blarify

## Overview

##### Project Type and Purpose
- blarify is an open-source **code-analysis tool** that:
– Scans a local project’s files
– Builds a unified graph of code hierarchy (classes, functions, modules)
– Resolves cross-references using language servers or Tree-sitter
– Persists that graph in a database (Neo4j or FalkorDB)
– Enables LLMs or other clients to traverse, debug, and refactor code

##### Main Architectural Components
A. **CLI / Entrypoint** (main.py)
- Parses user commands (create, update, prebuilt, stats).
B. **Project File Explorer** (project_file_explorer/)
- Recursively finds source files and folders
- Emits a file metadata stream
C. **Parser & Hierarchy Extraction** (code_hierarchy/)
- Uses Tree-sitter (tree_sitter_helper.py) or language definitions to build ASTs
- Outputs hierarchy nodes (ClassNode, FunctionNode, FileNode, etc.)
D. **Reference Resolver** (code_references/)
- Interfaces with LSP servers (lsp_helper.py)
- Produces “Reference” objects indicating cross-file symbol usage
E. **Graph Builder / Updater** (project_graph_creator.py, project_graph_updater.py, graph/)
- Combines hierarchy nodes & references into a single in-memory directed graph
- Applies updates, diffs, and environment contexts
F. **Database Manager** (db_managers/)
- Neo4jManager and FalkorDBManager handle persistence via REST/bolt or custom API
G. **Utilities & Prebuilt** (utils/, prebuilt/)
- Helper scripts (file removal, path calculation)
- Prebuilt graph loader for faster startup
H. **Examples & Quickstart** (examples/, docs/)
- Sample graph builders, usage guides

##### Data Flows and Interactions
1. CLI → Project File Explorer: “Scan all files”
2. Explorer → Parser & Reference Resolver (in parallel or sequence)
3. Parser & Reference Resolver → Graph Builder
4. Graph Builder ↔ Graph Environment (for incremental updates)
5. Graph Builder → Database Manager: “Persist nodes & relationships”
6. Database Manager → Database (Neo4j or FalkorDB)
7. Database ← LLM or Client Tools (query/traverse)

##### Architectural Patterns & Principles
- **Layered Pipeline:** clear separation between discovery, parsing, graph construction, and persistence
- **Plugin-style Language Support:** each language definition file implements the same interface
- **Incremental Updates:** ability to update only changed files (internal/update-hierarchy, update.py)
- **Extensibility Points:** utils/experimental, prebuilt graphs, new DB backends

##### Final Checklist
[ ] All major components identified and labeled
[ ] Extensibility/plugin points clearly marked

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry & CLI
    subgraph "Entry & CLI"
        direction TB
        CLI["CLI / Entrypoint<br/>(main.py)"]:::cli
        Create["create.py"]:::cli
        UpdateH["update-hierarchy.py"]:::cli
        Update["update.py"]:::cli
    end

    %% I/O & Persistence
    subgraph "I/O & Persistence"
        direction TB
        Explorer["Project File Explorer"]:::io
        DBManager["Database Manager"]:::io
        Neo4j["Neo4jManager"]:::io
        Falkor["FalkorDBManager"]:::io
        Database[(Database)]:::db
    end

    %% Core Processing
    subgraph "Core Processing"
        direction TB
        Parser["Parser & Hierarchy Extraction"]:::core
        RefResolver["Reference Resolver"]:::core
        GraphBuilder["Graph Builder / Updater"]:::core
        subgraph "Graph Modules"
            direction TB
            GraphCore["graph.py"]:::core
            Env["graph_environment.py"]:::core
            UpdateMod["graph_update.py"]:::core
            Diff["project_graph_diff_creator.py"]:::core
            Creator["project_graph_creator.py"]:::core
            Updater["project_graph_updater.py"]:::core
        end
        subgraph "Nodes & Relationships"
            direction TB
            FileNode["FileNode"]:::node_file
            ClassNode["ClassNode"]:::node_class
            FuncNode["FunctionNode"]:::node_func
            RelStore["external_relationship_store.py"]:::core
        end
    end

    %% Utilities & Examples
    subgraph "Utilities & Examples"
        direction TB
        Utils["Utilities"]:::util
        Experimental["experimental"]:::util
        Prebuilt["Prebuilt"]:::util
        Examples["Examples & Quickstart"]:::util
    end

    %% External Dependencies
    subgraph "External Services"
        direction TB
        Treesitter[("Tree-sitter")]:::external
        LSP[("LSP Servers")]:::external
        LLM[("LLM / Client Tools")]:::external
    end

    %% Flows
    CLI -->|"scan all files"| Explorer
    Explorer -->|"file metadata"| Parser
    Explorer -->|"file metadata"| RefResolver
    Parser -->|"ASTs / Hierarchy Nodes"| GraphBuilder
    RefResolver -->|"References"| GraphBuilder
    GraphBuilder -->|"Graph Δ"| Env
    Env -->|"Context"| GraphBuilder
    GraphBuilder -->|"Persist nodes & relationships"| DBManager
    DBManager -->|"REST/bolt"| Database
    LLM -->|"queries"| DBManager

    Treesitter -.-> Parser
    LSP -.-> RefResolver

    %% Click Events
    click CLI "https://github.com/knacklabs/blarify/blob/codeknack/blarify/main.py"
    click Create "https://github.com/knacklabs/blarify/blob/codeknack/blarify/internal/create.py"
    click UpdateH "https://github.com/knacklabs/blarify/blob/codeknack/blarify/internal/update-hierarchy.py"
    click Update "https://github.com/knacklabs/blarify/blob/codeknack/blarify/internal/update.py"
    click Explorer "https://github.com/knacklabs/blarify/tree/codeknack/blarify/project_file_explorer/"
    click Parser "https://github.com/knacklabs/blarify/blob/codeknack/blarify/code_hierarchy/tree_sitter_helper.py"
    click RefResolver "https://github.com/knacklabs/blarify/blob/codeknack/blarify/code_references/lsp_helper.py"
    click Creator "https://github.com/knacklabs/blarify/blob/codeknack/blarify/project_graph_creator.py"
    click Updater "https://github.com/knacklabs/blarify/blob/codeknack/blarify/project_graph_updater.py"
    click Diff "https://github.com/knacklabs/blarify/blob/codeknack/blarify/project_graph_diff_creator.py"
    click GraphCore "https://github.com/knacklabs/blarify/blob/codeknack/blarify/graph/graph.py"
    click Env "https://github.com/knacklabs/blarify/blob/codeknack/blarify/graph/graph_environment.py"
    click UpdateMod "https://github.com/knacklabs/blarify/blob/codeknack/blarify/graph/graph_update.py"
    click RelStore "https://github.com/knacklabs/blarify/blob/codeknack/blarify/graph/external_relationship_store.py"
    click FileNode "https://github.com/knacklabs/blarify/blob/codeknack/blarify/graph/node/file_node.py"
    click ClassNode "https://github.com/knacklabs/blarify/blob/codeknack/blarify/graph/node/class_node.py"
    click FuncNode "https://github.com/knacklabs/blarify/blob/codeknack/blarify/graph/node/function_node.py"
    click DBManager "https://github.com/knacklabs/blarify/blob/codeknack/blarify/db_managers/db_manager.py"
    click Neo4j "https://github.com/knacklabs/blarify/blob/codeknack/blarify/db_managers/neo4j_manager.py"
    click Falkor "https://github.com/knacklabs/blarify/blob/codeknack/blarify/db_managers/falkordb_manager.py"
    click Utils "https://github.com/knacklabs/blarify/tree/codeknack/blarify/utils/"
    click Experimental "https://github.com/knacklabs/blarify/tree/codeknack/blarify/utils/experimental/"
    click Prebuilt "https://github.com/knacklabs/blarify/blob/codeknack/blarify/prebuilt/graph_builder.py"
    click Examples "https://github.com/knacklabs/blarify/blob/codeknack/blarify/examples/graph_builder.py"

    %% Styles
    classDef cli fill:#f9d5a2,stroke:#333,stroke-width:1px
    classDef core fill:#b3cde3,stroke:#333,stroke-width:1px
    classDef io fill:#ccebc5,stroke:#333,stroke-width:1px
    classDef util fill:#e5e5e5,stroke:#333,stroke-width:1px
    classDef db fill:#decbe4,stroke:#333,stroke-width:1px
    classDef node_file fill:#fff2aa,stroke:#333,stroke-width:1px
    classDef node_class fill:#ffbbb3,stroke:#333,stroke-width:1px
    classDef node_func fill:#a2d2ff,stroke:#333,stroke-width:1px
    classDef external fill:#f0f0f0,stroke-dasharray: 5 5,stroke:#666,stroke-width:1px
```
