A streamlined, graph-based infrastructure documentation engine designed specifically for HomeLab enthusiasts to map physical hardware to virtual services.[cite: 1]

🚀 The Vision

Documentation in a HomeLab often falls into two extremes: overly complex enterprise tools like NetBox or static notes that quickly become outdated[cite: 1]. LabGraph bridges this gap by prioritizing automated discovery, visual clarity, and context-aware documentation[cite: 1]. It allows you to see the exact relationship between a physical server in your rack and the digital services running within it[cite: 1, 2].

✨ Key Features

🔍 Automated Discovery & Monitoring

Hypervisor/Runtime Sync: Background workers pull real-time inventory from Proxmox VE, Docker, and TrueNAS APIs[cite: 1, 2].
Active Monitoring: Integrated heartbeat service performing ICMP pings and HTTP/HTTPS status checks for live "Up/Down" indicators[cite: 2].
Network Scanning: Scheduled tasks to scan subnets and identify undocumented "rogue" devices via Nmap[cite: 2].

🗺️ Visualization Suite

Hierarchical "Drill-Down": A nested accordion list view showing the chain from Physical Location → Hardware Host → Virtualization Layer → VM/Container → Application[cite: 1, 2].
Interactive Topology Map: A dynamic network graph powered by React Flow that auto-arranges nodes based on gateway relationships[cite: 2].
Contextual Sidebar: Click any node to see technical specs (IP, MAC, Port), resource sparklines, and documentation instantly[cite: 2].

📖 Knowledge & Lifecycle Management

Integrated Markdown Wiki: Every node has an associated "Sidecar" Markdown file for technical notes, rendered directly in the detail view[cite: 1, 2].
Maintenance Logs: A chronological event ledger to track hardware swaps, thermal paste changes, and upgrades[cite: 1, 2].
Global Command Palette: Use Ctrl + K to search for any device, IP, or wiki entry instantly[cite: 2].

⚡ HomeLab Utilities

Power & Cost Estimator: Input wattage for hardware to calculate total rack draw and monthly electricity costs[cite: 1, 2].
IPAM: Dedicated tracker for VLAN IDs, CIDR ranges, and IP exhaustion[cite: 1, 2].
Public Status Page: A toggleable, read-only dashboard for family members to check service status[cite: 1, 2].

🛠️ Tech Stack

Frontend: React, TypeScript, Tailwind CSS (DaisyUI), React Flow[cite: 1, 3].
Backend: Python, Django Rest Framework (DRF)[cite: 1, 3].
Task Queue: Celery & Redis (for background scans and heartbeats).
Database: PostgreSQL[cite: 1, 3].
Security: NextAuth.js, OWASP Top 10 compliance, and strict validation via Pydantic/Zod.

💻 Getting Started (Dev Container)

This project is optimized for development using VS Code Dev Containers.

Clone the repository:

git clone [https://github.com/your-username/LabGraph.git](https://github.com/your-username/LabGraph.git)
cd LabGraph

Open in VS Code:

code .

Reopen in Container: When prompted, select "Reopen in Container" to build the environment (includes Python, Node.js, PostgreSQL, and Redis).

Initialize the Environment: Once the container is running, execute the following in the terminal:

# Install dependencies
pip install -r requirements.txt
npm install

# Run migrations
python manage.py migrate

# Start development servers
python manage.py runserver 0.0.0.0:8000 &
npm run dev

🎨 Branding & Identity

The LabGraph logo is a geometric Connected Node Hexagon.

The Shape: A hexagon representing a single data node.
The Interior: Three horizontal bars representing a stylized server rack.
The Connectivity: Circuit-like lines branching out to represent the network graph and data flow[cite: 3].
Color Palette: GitHub Dark theme inspired (Deep Charcoal #0d1117, Electric Blue #58a6ff, and Success Green #238636)[cite: 3].

📝 License

Distributed under the MIT License. See LICENSE for more information[cite: 3].