Grafyx - Code Knowledge Graph & Documentation Tool

=============================================================
    ██████╗ ██████╗  █████╗ ███████╗██╗   ██╗██╗  ██╗
   ██╔════╝ ██╔══██╗██╔══██╗██╔════╝╚██╗ ██╔╝╚██╗██╔╝
   ██║  ███╗██████╔╝███████║█████╗   ╚████╔╝  ╚███╔╝ 
   ██║   ██║██╔══██╗██╔══██║██╔══╝    ╚██╔╝   ██╔██╗ 
   ╚██████╔╝██║  ██║██║  ██║██║        ██║   ██╔╝ ██╗
    ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝   ╚═╝  ╚═╝
=============================================================

Visualize Your Codebase Like Never Before

This project is in Beta and may have bugs

---

✦ Table of Contents

1. Overview
2. Visual Demo
3. Architecture
4. Features
5. Live Physics Engine
6. Installation
7. Quick Start for New Users
8. Usage
9. Configuration
10. Attribution

---

✦ Overview

Grafyx is a high-performance, CLI-driven code knowledge graph tool designed to map and visualize the complex relationships within modern codebases. By parsing directory structures and service interactions, Grafyx generates an interactive 2D/3D force-directed graph that helps developers understand dependency chains, structural bottlenecks, and project architecture at a glance.

Developed with Rust for safety and speed, and D3.js for fluid frontend interactions, Grafyx bridges the gap between static analysis and intuitive visual exploration.

---

⬢ Visual Demo

---

❖ Architecture

Grafyx follows a decoupled architecture, ensuring high-speed processing and a responsive user experience.

┌─────────────────────────────────────────────────────────────────────────┐
│                             GRAFYX PLATFORM                             │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐    ┌─────────────────┐    ┌──────────────┐            │
│  │   Rust CLI   │    │  Graph Engine   │    │   Storage    │            │
│  │   (Parser)   │◄──►│  (Node/Edge IR) │◄──►│ (SQLite/JSON)│            │
│  └──────────────┘    └────────┬────────┘    └──────────────┘            │
│                               │                                         │
│                               ▼                                         │
│                      ┌─────────────────┐                                │
│                      │  D3.js Frontend │                                │
│                      │  (Interactive)  │                                │
│                      └─────────────────┘                                │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

---

✥ Features

Feature	Description	Status
Recursive Scanning	Scans entire projects to map file/directory hierarchies.	✔ Active
Hot Physics	Real-time adjustable simulation forces with sub-millisecond response.	✔ Active
Static Binaries	Universal Linux binaries (MUSL) optimized for Arch and Ubuntu.	✔ Active
Self-Managing	Integrated install and upgrade commands for zero-friction setup.	✔ Active
Apple Silicon Native	Native performance for M1/M2/M3 architecture via ARM64 targets.	✔ Active
Dual Storage	Outputs both human-readable JSON and performance-optimized SQLite.	✔ Active

---

◈ Live Physics Engine

Grafyx features a "Hot Update" physics engine inspired by tools like Obsidian. Adjusting sliders instantly ripples through the graph without requiring a full re-render, keeping the simulation fluid and "liquid."

Force Parameters

• Repulsion: Determines how much nodes push away from each other.
• Link Distance: Controls the target length for edges.
• Gravity (Center Force): Pulls all nodes toward the center point.
• Damping: Adjusts the decay rate of movement for stability.

---

⬢ Installation

✦ Recommended: Binary Install (Quick)

Install Grafyx globally with a single command. The installer automatically configures your PATH.

Linux (AMD64)

curl -L https://github.com/0xarchit/grafyx/releases/latest/download/grafyx-linux-amd64-static -o grafyx && chmod +x grafyx && ./grafyx install && rm grafyx

macOS (Apple Silicon)

curl -L https://github.com/0xarchit/grafyx/releases/latest/download/grafyx-macos-aarch64 -o grafyx && chmod +x grafyx && ./grafyx install && rm grafyx

macOS (Intel)

curl -L https://github.com/0xarchit/grafyx/releases/latest/download/grafyx-macos-x86_64 -o grafyx && chmod +x grafyx && ./grafyx install && rm grafyx

Windows (PowerShell)

iwr https://github.com/0xarchit/grafyx/releases/latest/download/grafyx-windows-amd64.exe -OutFile grafyx.exe; .\grafyx install; del grafyx.exe

✦ Manual: Build from Source

git clone https://github.com/0xarchit/grafyx.git
cd grafyx/tool
cargo build --release

---

✦ Quick Start for New Users

If this is your first time using Grafyx, run the command below from your project root.

Scan Command

grafyx --dirs <directories space separated> --output ./<output folder>

Example:

grafyx --dirs tool web --output ./output-test

After scan completes:

• Open ./<output folder>/index.html in your browser.
• Use grafyx.json for readable data export.
• Use grafyx.db for fast programmatic queries.

---

⌗ Usage

Grafyx handles its own lifecycle and codebase mapping.

Commands

Command	Alias	Description
grafyx --dirs <directories...> --output ./<output-folder>	-	Shortcut command to scan directories.
grafyx install	i	Installs the binary permanently to your system PATH.
grafyx upgrade	u	Automatically updates Grafyx to the latest version.
grafyx uninstall	-	Cleanly removes Grafyx from your system.
grafyx --version	-	Display current version.

Scan Flags

Flag	Description
--dirs	One or more directories to scan, space separated.
--output	Output folder for grafyx.json, grafyx.db, and index.html.
--format	Output type: json, sqlite, or both (default).
--ignore	Optional ignore patterns to exclude files/directories.

---

⌬ Configuration

Settings are persisted in the browser's localStorage under grafyx-settings. This allows you to maintain your custom visual configuration across different scans of the same project.

• Theme: Fixed dark mode for maximum contrast.
• Node Colors: Scaled based on connectivity or type (Service/Import vs. Structural).
• Link Colors:
  • Vibrant Green: Service dependencies/imports.
  • White: Structural hierarchy.

---

§ License

Grafyx is licensed under the Apache License 2.0.
See the LICENSE file for the full text and attribution requirements.

---

℡ Attribution

Grafyx is created and maintained by 0xArchit.

If you build on top of this project, please provide proper attribution. Any derivative works must retain the original copyright notice in the license.

---

Grafyx - Code Knowledge Graph Tool © 2026 0xArchit