How knacklabs/blarify works
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