# blarapp/blarify architecture

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

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

## Overview

##### Project type and purpose
- Blarify is an open-source code-analysis and graph-building CLI tool.
- It traverses a local codebase in multiple languages, builds a semantic graph of files, folders, classes, functions, and their relationships, then persists that graph to a database so that an LLM (or other client) can query, traverse, debug, or refactor the code.

##### File structure
- Top-level “blarify/” module contains all core packages:
- project_file_explorer – discovers files and folders in the target repo
- code_hierarchy – uses Tree-sitter definitions per language to build an AST hierarchy
- code_references – uses LSP (language servers) to resolve cross-file references
- graph – defines node and relationship types, environment, update logic, and an external relationship store
- db_managers – adapters for Neo4j or FalkorDB to persist the graph
- internal – CLI command implementations for create, update, diff operations
- utils, stats, logger – supporting utilities and metrics
- Entry point: main.py (parses CLI, delegates to internal/create or update routines)
- Examples and prebuilt scripts show typical usage patterns

##### Pull architecture cues from the README
- Purpose: present any codebase as a graph for LLM traversal
- Supported languages hint at a plug-in architecture for language definitions
- Quickstart refers to graph visualization, implying a separation between graph construction and graph consumption

a. Main components:
1. CLI / Orchestration Layer (main.py + internal/)
2. File Explorer (project_file_explorer/)
3. Syntax & Semantic Analyzers
– code_hierarchy (Tree-sitter)
– code_references (LSP helper)
4. Graph Model Layer (graph/ + external_relationship_store)
5. Persistence Layer (db_managers: Neo4j, FalkorDB)
6. Utilities & Metrics (logger, stats, utils)
7. External Services
– Language Servers (per supported language)
– Graph Consumers (LLM, visualization tools)
b. Relationships & interactions:
- CLI triggers File Explorer to scan file system → feeds file list to Syntax/ Semantic Analyzers.
- code_hierarchy builds node hierarchy; code_references resolves symbol links via language servers.
- Both pass their outputs to Graph Model Layer, which creates Node and Relationship objects.
- Graph Model Layer calls Persistence Layer adapters to write/read the graph.
- The graph can be queried by an LLM or exported to visualization.
- Utilities (logger, stats) are cross-cutting services used by all layers.
c. Architectural patterns & design principles:
- Modular “pipeline” or “stages” pattern: each stage (explore, parse, resolve, build, persist) is decoupled.
- Adapter pattern for DB managers and language definitions—easy to extend to new backends or languages.
- Single responsibility modules (each package focuses on one task).
- Incremental update support via diff/updater modules in internal/.
d. Key technologies & frameworks:
- Python 3, Tree-sitter for syntax trees.
- LSP protocol for cross-reference resolution.
- Neo4j & FalkorDB drivers for graph persistence.
- CLI via argparse or click (in main.py).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI / Orchestration Layer
    subgraph "CLI / Orchestration Layer"
        direction TB
        CLI["main.py"]:::internal
        Create["create.py"]:::internal
        Update["update.py"]:::internal
        UpdateHier["update-hierarchy.py"]:::internal
    end

    %% File Explorer
    subgraph "File Explorer"
        direction TB
        File["file.py"]:::internal
        Folder["folder.py"]:::internal
        Iterator["project_files_iterator.py"]:::internal
        StatsFE["project_files_stats.py"]:::internal
    end

    %% Syntax Parsing (Tree-sitter)
    subgraph "Syntax Parsing (Tree-sitter)"
        direction TB
        TSH["tree_sitter_helper.py"]:::internal
        LangDefs["language_definitions.py, *_definitions.py, FoundRelationshipScope.py"]:::internal
    end

    %% Semantic Reference Resolution (LSP)
    subgraph "Reference Resolution (LSP)"
        direction TB
        LSPHelper["lsp_helper.py"]:::internal
        ReferenceType["Reference.py"]:::internal
    end

    %% Graph Model Layer
    subgraph "Graph Model Layer"
        direction TB
        GraphCore["graph.py"]:::internal
        Env["graph_environment.py"]:::internal
        UpdateGraph["graph_update.py"]:::internal
        ExternalStore["external_relationship_store.py"]:::internal
        subgraph "Nodes"
            direction TB
            ClassNode["class_node.py"]:::internal
            FuncNode["function_node.py"]:::internal
            FileNode["file_node.py"]:::internal
            FolderNode["folder_node.py"]:::internal
            DeletedNode["deleted_node.py"]:::internal
        end
        subgraph "Relationships"
            direction TB
            RelCore["relationship.py"]:::internal
            RelCreator["relationship_creator.py"]:::internal
            ExternalRel["external_relationship.py"]:::internal
            RelType["relationship_type.py"]:::internal
        end
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        DBManager["db_manager.py"]:::internal
        Neo4j["neo4j_manager.py"]:::db
        Falkor["falkordb_manager.py"]:::db
    end

    %% Utilities & Metrics
    subgraph "Utilities & Metrics"
        direction TB
        Logger["logger.py"]:::internal
        Complexity["complexity.py"]:::internal
        Utils["utils/"]:::internal
    end

    %% Core Graph Builders & Updaters
    subgraph "Core Builders & Updaters"
        direction TB
        Creator["project_graph_creator.py"]:::internal
        DiffCreator["project_graph_diff_creator.py"]:::internal
        Updater["project_graph_updater.py"]:::internal
        Verifier["format_verifier.py"]:::internal
    end

    %% Examples & Prebuilt
    subgraph "Examples & Prebuilt Scripts"
        direction TB
        Example1["examples/graph_builder.py"]:::internal
        Example2["prebuilt/graph_builder.py"]:::internal
    end

    %% External Services
    LSP["Language Servers"]:::external
    LLM["LLM / Graph Consumers"]:::external
    Viz["Visualization Tools"]:::external

    %% Data Artifacts
    AST["AST Nodes"]:::data
    Refs["Reference Lists"]:::data
    GraphObjs["Node & Relationship Objects"]:::data

    %% Workflow connections
    CLI -->|"invoke create/update"| File
    File -->|"discovers files"| Iterator
    Iterator --> File
    File -->|"feeds file list"| TSH
    TSH -->|"build AST"| AST
    AST -->|"nodes input"| GraphCore
    File -->|"feeds file list"| LSPHelper
    LSPHelper -->|"resolve refs via"| LSP
    LSPHelper --> Refs
    Refs -->|"refs input"| GraphCore
    GraphCore --> GraphObjs
    GraphObjs --> UpdateGraph
    GraphCore --> ExternalStore
    GraphObjs --> DBManager
    DBManager --> Neo4j
    DBManager --> Falkor
    Neo4j --> LLM
    Falkor --> LLM
    LLM -->|"query graph"| GraphCore
    GraphCore --> Viz

    %% Utilities cross-cutting
    Logger -.-> CLI
    Logger -.-> File
    Logger -.-> TSH
    Logger -.-> LSPHelper
    Logger -.-> GraphCore
    Logger -.-> DBManager

    Complexity -.-> TSH
    Complexity -.-> LSPHelper

    Utils -.-> CLI
    Utils -.-> File
    Utils -.-> TSH
    Utils -.-> LSPHelper
    Utils -.-> GraphCore

    %% Core builders path
    Creator --> File
    DiffCreator --> File
    Updater --> File
    Verifier --> File

    Creator --> TSH
    DiffCreator --> TSH
    Updater --> TSH
    Verifier --> TSH

    %% Click events
    click CLI "https://github.com/blarapp/blarify/blob/main/blarify/main.py"
    click Create "https://github.com/blarapp/blarify/blob/main/blarify/internal/create.py"
    click Update "https://github.com/blarapp/blarify/blob/main/blarify/internal/update.py"
    click UpdateHier "https://github.com/blarapp/blarify/blob/main/blarify/internal/update-hierarchy.py"
    click File "https://github.com/blarapp/blarify/blob/main/blarify/project_file_explorer/file.py"
    click Folder "https://github.com/blarapp/blarify/blob/main/blarify/project_file_explorer/folder.py"
    click Iterator "https://github.com/blarapp/blarify/blob/main/blarify/project_file_explorer/project_files_iterator.py"
    click StatsFE "https://github.com/blarapp/blarify/blob/main/blarify/project_file_explorer/project_files_stats.py"
    click TSH "https://github.com/blarapp/blarify/blob/main/blarify/code_hierarchy/tree_sitter_helper.py"
    click LangDefs "https://github.com/blarapp/blarify/blob/main/blarify/code_hierarchy/languages/language_definitions.py"
    click LSPHelper "https://github.com/blarapp/blarify/blob/main/blarify/code_references/lsp_helper.py"
    click ReferenceType "https://github.com/blarapp/blarify/blob/main/blarify/code_references/types/Reference.py"
    click GraphCore "https://github.com/blarapp/blarify/blob/main/blarify/graph/graph.py"
    click Env "https://github.com/blarapp/blarify/blob/main/blarify/graph/graph_environment.py"
    click UpdateGraph "https://github.com/blarapp/blarify/blob/main/blarify/graph/graph_update.py"
    click ExternalStore "https://github.com/blarapp/blarify/blob/main/blarify/graph/external_relationship_store.py"
    click ClassNode "https://github.com/blarapp/blarify/blob/main/blarify/graph/node/class_node.py"
    click FuncNode "https://github.com/blarapp/blarify/blob/main/blarify/graph/node/function_node.py"
    click FileNode "https://github.com/blarapp/blarify/blob/main/blarify/graph/node/file_node.py"
    click FolderNode "https://github.com/blarapp/blarify/blob/main/blarify/graph/node/folder_node.py"
    click DeletedNode "https://github.com/blarapp/blarify/blob/main/blarify/graph/node/deleted_node.py"
    click RelCore "https://github.com/blarapp/blarify/blob/main/blarify/graph/relationship/relationship.py"
    click RelCreator "https://github.com/blarapp/blarify/blob/main/blarify/graph/relationship/relationship_creator.py"
    click ExternalRel "https://github.com/blarapp/blarify/blob/main/blarify/graph/relationship/external_relationship.py"
    click RelType "https://github.com/blarapp/blarify/blob/main/blarify/graph/relationship/relationship_type.py"
    click DBManager "https://github.com/blarapp/blarify/blob/main/blarify/db_managers/db_manager.py"
    click Neo4j "https://github.com/blarapp/blarify/blob/main/blarify/db_managers/neo4j_manager.py"
    click Falkor "https://github.com/blarapp/blarify/blob/main/blarify/db_managers/falkordb_manager.py"
    click Logger "https://github.com/blarapp/blarify/blob/main/blarify/logger.py"
    click Complexity "https://github.com/blarapp/blarify/blob/main/blarify/stats/complexity.py"
    click Utils "https://github.com/blarapp/blarify/tree/main/blarify/utils/"
    click Creator "https://github.com/blarapp/blarify/blob/main/blarify/project_graph_creator.py"
    click DiffCreator "https://github.com/blarapp/blarify/blob/main/blarify/project_graph_diff_creator.py"
    click Updater "https://github.com/blarapp/blarify/blob/main/blarify/project_graph_updater.py"
    click Verifier "https://github.com/blarapp/blarify/blob/main/blarify/format_verifier.py"
    click Example1 "https://github.com/blarapp/blarify/blob/main/blarify/examples/graph_builder.py"
    click Example2 "https://github.com/blarapp/blarify/blob/main/blarify/prebuilt/graph_builder.py"

    %% Styles
    classDef internal fill:#D0E4F5,stroke:#0366d6,color:#0366d6
    classDef db fill:#E2F0CB,stroke:#6B8E23,color:#6B8E23
    classDef external fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00
    classDef data fill:#FFF5BA,stroke:#FFD700,color:#B8860B
```
