🚀 MiniGraphDB – A Lightweight Graph Database Engine in C++

A high-performance, disk-persistent graph database engine built from scratch in C++17, featuring Dijkstra's shortest path and a Python visualization layer.

Interactive C++ CLI interacting with a persistent graph, exported to Python for real-time visualization.

---

🧠 Why This Project Stands Out

This project isn't just a CRUD app. It is a multi‑paradigm systems project that rigorously applies core Computer Science fundamentals to build a functioning database engine.

CS Domain	Implementation in this Project
Data Structures & Algorithms	unordered_map for O(1) node lookups, Adjacency List (vector) for cache‑efficient traversal, Dijkstra's Algorithm with a binary heap (priority_queue) for shortest paths.
Operating Systems	RAII for memory safety, custom Signal Handlers (SIGINT) for crash‑safe persistence, File I/O with std::fstream, and a ready‑to‑extend concurrency model.
Database Management	ACID‑ish text‑based serialization (custom .db format), query parsing, schema‑less property maps, and a full SAVE/LOAD lifecycle.
Computer Networks	(Portfolio Ready) The engine outputs structured JSON via an EXPORT command, acting as an API gateway to external visualization tools (Python).

---

✨ Key Features

• Custom Query Language: Intuitive CLI commands (CREATE NODE, FIND PATH, SHOW NODE).
• Smart String Parsing: Handles quoted labels (e.g., "Los Angeles") and key‑value properties.
• Disk Persistence: All data survives restarts; saves automatically on exit or Ctrl+C.
• Python Visualization Layer: Exports graph data to JSON and renders it using NetworkX + Matplotlib (or Plotly for interactive HTML).
• Modern C++: Leverages C++17 features (std::optional, std::filesystem, structured bindings).

---

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         C++ Core Engine                            │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐    │
│  │   Graph     │    │  Database   │    │  QueryProcessor     │    │
│  │ (Adj List)  │◄──►│ (Save/Load) │◄──►│ (CLI Parser)        │    │
│  └─────────────┘    └─────────────┘    └──────────┬──────────┘    │
│                                                    │               │
│                                              [EXPORT]              │
└─────────────────────────────────────────────────────┬───────────────┘
                                                      │
                                              graph_export.json
                                                      │
┌─────────────────────────────────────────────────────▼───────────────┐
│                         Python Visualization Layer                  │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  visualizer.py  (NetworkX / Matplotlib / Plotly)             │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

---

🛠️ Tech Stack

Backend (C++)

• Build System: CMake 3.10+
• Core: C++17 Standard Library (STL)
• Filesystem: std::filesystem for cross‑platform directory creation
• JSON Export: nlohmann/json (via FetchContent)

Frontend (Python)

• Graph Manipulation: NetworkX
• Visualization: Matplotlib / Plotly
• Data Exchange: JSON

---

📦 Getting Started

Prerequisites

• C++ Compiler: GCC 7+ or Clang 5+ (Supports C++17)
• CMake: 3.10+
• Python: 3.8+

Build & Run the Engine

# 1. Clone the repository
git clone https://github.com/yourusername/MiniGraphDB.git
cd MiniGraphDB

# 2. Build the C++ project
mkdir build && cd build
cmake .. && make -j

# 3. Run the interactive database shell
./minigraphdb

Visualize with Python

# 1. Install Python dependencies
cd ../python
pip install -r requirements.txt

# 2. Inside the C++ CLI, export the graph
db> EXPORT

# 3. Run the visualizer
python3 visualizer.py

---

🎮 Interactive Session Example

db> CREATE NODE 1 "New York" population="8.4M"
✅ Node 1 created.

db> CREATE NODE 2 "Los Angeles" population="3.8M"
✅ Node 2 created.

db> CREATE EDGE 1 2 "FLIGHT" weight=3945.2 airline="American"
✅ Edge (1 -> 2) created.

db> FIND PATH 1 2
✅ Shortest path: 1 -> 2

db> SHOW NODE 1
📌 Node 1 [Label: "New York"]
   Properties:
     population = "8.4M"
   Outgoing Edges:
     -> 2 [Label: "FLIGHT", Weight: 3945.2] {airline=American}

db> EXPORT
✅ Graph exported to python/export_data/graph_export.json

db> EXIT
✅ Database saved to data/graph.db

---

📂 Project Structure

MiniGraphDB/
├── CMakeLists.txt          # Build configuration
├── README.md               # This file
├── assets/                 # Demo screenshots/GIFs
│   └── demo.gif
├── include/                # C++ Headers
│   ├── Node.h
│   ├── Edge.h
│   ├── Graph.h
│   ├── Database.h
│   └── QueryProcessor.h
├── src/                    # C++ Sources
│   ├── Graph.cpp
│   ├── Database.cpp
│   └── QueryProcessor.cpp
├── data/                   # Persistent storage
│   └── graph.db
├── python/                 # Visualization Module
│   ├── requirements.txt
│   ├── visualizer.py
│   └── export_data/
│       └── graph_export.json
└── main.cpp                # Entry point with Signal Handling

---

🚀 Future Improvements (Roadmap)

• Indexing: Add B‑Tree indexes on node labels for faster lookups.
• Transactions: Implement commit/rollback for batch operations.
• Networking Layer: Expose a TCP socket interface (client‑server model).
• Weighted Graphs: Fully support dynamic edge weight updates.
• Binary Serialization: Implement memory‑mapped files for faster load times.

---

👤 Author & Contribution

Virendra Singh Bhati – Github

This project was built to demonstrate deep proficiency in C++, Data Structures, Operating Systems, and Database Design. It is fully open source.

Feel free to submit a PR or reach out for discussions on systems programming!

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---