Make first working versions of the examples

Author: habedi

AGENTS.md

@@ -30,7 +30,7 @@ Priorities, in order:
 
 ## Repository Layout
 
-- `rust/graphrag-agent/`: Graph RAG application in Rust.
+- `rust/graphrag-agent/`: GraphRAG application in Rust.
 - `rust/code-explorer/`: Rust source code navigator and structural analyzer using PageRank.
 - `python/fraud/`: Cypher-based fraud pattern detection over transaction stream.
 - `python/recommendation/`: Hybrid user friend and content recommendation system.

CONTRIBUTING.md

@@ -32,7 +32,7 @@ it has already been resolved.
 
 The repository is organized around four showcase applications:
 
-1. `rust/graphrag-agent`: Graph RAG application showcasing vector search, full-text search, and hybrid graph expansion.
+1. `rust/graphrag-agent`: GraphRAG application showcasing vector search, full-text search, and hybrid graph expansion.
 2. `rust/code-explorer`: Rust source code navigator illustrating structural graph analysis (PageRank, components, shortest path) on code syntax trees.
 3. `python/fraud`: Cypher-based fraud pattern detection over a simulated transaction stream.
 4. `python/recommendation`: Hybrid friend-of-friend and content recommendation system.

Makefile

@@ -82,3 +82,7 @@ setup-hooks: ## Install Git hooks (pre-commit and pre-push)
 test-hooks: ## Test Git hooks on all files
 	@echo "Testing Git hooks..."
 	@pre-commit run --all-files
+
+.PHONY: shell
+shell: ## Enter the Nix development shell environment
+	@nix develop

README.md

@@ -1,19 +1,74 @@
 ## IssunDB Example Applications
 
-## Graph Benchmarks
-
 [![Tests](https://img.shields.io/github/actions/workflow/status/IssunDB/example-apps/tests.yml?label=tests&style=flat&labelColor=282c34&logo=github)](https://github.com/IssunDB/example-apps/actions/workflows/tests.yml)
 [![Code Coverage](https://img.shields.io/codecov/c/github/IssunDB/example-apps?label=coverage&style=flat&labelColor=282c34&logo=codecov)](https://codecov.io/gh/IssunDB/example-apps)
 [![Python version](https://img.shields.io/badge/python-%3E=3.10-3776ab?style=flat&labelColor=282c34&logo=python)](https://github.com/IssunDB/example-apps)
 [![License: MIT](https://img.shields.io/badge/license-MIT-ffd343?style=flat&labelColor=282c34&logo=open-source-initiative)](LICENSE)
 
-This repository includes a collection of example applications that use the [IssunDB](https://github.com/IssunDB/issundb) graph database.
+This repository includes a collection of example applications that use the [IssunDB](https://github.com/IssunDB/issun-db) graph database.
+
+---
+
+### Examples
+
+Currently, the following table lists the included examples:
+
+| # | Example                                               | Language | Description                                                                              |
+|---|-------------------------------------------------------|----------|------------------------------------------------------------------------------------------|
+| 1 | [GraphRAG Pipeline](rust/graphrag-agent)              | Rust     | Knowledge graph extraction and retrieval-augmented generation using an LLM.              |
+| 2 | [Codebase Explorer](rust/code-explorer)               | Rust     | Syntax dependency graph constructor and function ranking using PageRank.                 |
+| 3 | [Fraud Detection System](python/fraud)                | Python   | Real-time financial transaction stream analyzer using Cypher queries.                    |
+| 4 | [Social Recommendation System](python/recommendation) | Python   | Hybrid friend and content recommender using collaborative filtering and semantic search. |
 
 ---
 
 ### Quickstart
 
-To be added.
+#### Prerequisites
+
+To build and run the example applications, you need:
+
+- Rust (version 1.85 or newer) toolchain: [Install Rust](https://www.rust-lang.org/tools/install)
+- Python (version 3.10 or newer) with `uv` package manager: [Install uv](https://github.com/astral-sh/uv)
+
+#### Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/IssunDB/example-apps.git
+   cd example-apps
+   ```
+
+2. Set up the Python virtual environment and install dependencies:
+   ```bash
+   uv sync --all-extras
+   ```
+
+3. Build the Rust applications:
+   ```bash
+   make build
+   ```
+
+#### Running the Demos
+
+You can run any of the demos using the provided `Makefile` targets:
+
+- Run the GraphRAG pipeline:
+  ```bash
+  make demo-grag
+  ```
+- Run the Codebase Explorer:
+  ```bash
+  make demo-code-exp
+  ```
+- Run the Fraud Detection stream:
+  ```bash
+  make demo-fraud
+  ```
+- Run the Social Recommendation system:
+  ```bash
+  make demo-recommend
+  ```
 
 ---
 

assets/diagrams/code_explorer.dot

@@ -0,0 +1,82 @@
+digraph CodebaseExplorer {
+    fontname = "Helvetica,Arial,sans-serif"
+    layout = dot
+    rankdir = TB
+    ranksep = 0.5
+    nodesep = 0.4
+    splines = true
+    bgcolor = "white"
+
+    node [
+    fontname = "Helvetica,Arial,sans-serif",
+    shape = rect,
+    style = "filled",
+    color = "#475569",
+    fillcolor = "white",
+    penwidth = 1.4,
+    margin = "0.16,0.10"
+    ]
+
+    edge [
+    fontname = "Helvetica,Arial,sans-serif",
+    fontsize = 10,
+    color = "#475569",
+    fontcolor = "#475569",
+    penwidth = 1.2
+    ]
+
+    // Nodes
+    sources [label = "Rust Source Files\n(.rs)", fillcolor = "#DBEAFE", color = "#2563EB"]
+
+    subgraph cluster_parsing {
+    label = "1. Parse & Analyze"
+    style = "rounded"
+    color = "#2563EB"
+    fillcolor = "#F8FAFC"
+    penwidth = 1.4
+    margin = 12
+
+    syn_parse [label = "syn AST Parsing", fillcolor = "#F1F5F9"]
+    extract_defs [label = "Extract Definitions\n(modules, functions, structs)", fillcolor = "#F1F5F9"]
+    extract_deps [label = "Extract Dependencies\n(calls, imports, definitions)", fillcolor = "#F1F5F9"]
+    }
+
+    subgraph cluster_storage {
+    label = "2. Graph Storage"
+    style = "rounded"
+    color = "#7C3AED"
+    fillcolor = "#F8FAFC"
+    penwidth = 1.4
+    margin = 12
+
+    db_nodes [label = "Store Nodes\n(labeled AST elements)", fillcolor = "#F3E8FF", color = "#7C3AED"]
+    db_edges [label = "Store Edges\n(typed relations)", fillcolor = "#F3E8FF", color = "#7C3AED"]
+    db_csr [label = "Build CSR Matrix\n(in-memory adjacency)", fillcolor = "#F3E8FF", color = "#7C3AED"]
+    }
+
+    subgraph cluster_ranking {
+    label = "3. Analysis & Ranking"
+    style = "rounded"
+    color = "#16A34A"
+    fillcolor = "#F8FAFC"
+    penwidth = 1.4
+    margin = 12
+
+    pagerank [label = "PageRank Solver", fillcolor = "#F1F5F9"]
+    rankings [label = "Ranked Functions\n(top critical symbols)", fillcolor = "#DCFCE7", color = "#16A34A"]
+    }
+
+    // Edges
+    sources -> syn_parse
+    syn_parse -> extract_defs
+    syn_parse -> extract_deps
+
+    extract_defs -> db_nodes
+    extract_deps -> db_edges
+
+    db_nodes -> db_csr
+    db_edges -> db_csr
+
+    db_csr -> pagerank
+    pagerank -> rankings
+}