diagram additions to projects

.github/workflows/export-excalidraw.yml

@@ -0,0 +1,74 @@
+name: Export Excalidraw Diagrams
+
+on:
+  # Runs on any PR (any target branch) that touches .excalidraw files → validate only
+  pull_request:
+    paths:
+      - '**/*.excalidraw'
+
+  # Runs when .excalidraw files land on main (PR merged) → export + commit
+  push:
+    branches: [main]
+    paths:
+      - '**/*.excalidraw'
+
+  workflow_dispatch:
+
+jobs:
+  # Shared setup + export (runs in both cases)
+  export:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install excalidraw-brute-export-cli
+        # Local install so npx resolves playwright from the same node_modules,
+        # guaranteeing the Firefox cache path matches what the CLI expects
+        run: npm install excalidraw-brute-export-cli
+
+      - name: Install Playwright + Firefox
+        # Uses the locally installed playwright (correct version) to install Firefox
+        run: npx playwright install --with-deps firefox
+
+      # On PR → validates every .excalidraw can be exported (job fails = PR blocked)
+      # On push → same step, but followed by the commit step below
+      - name: Export .excalidraw files → diagrams/
+        run: |
+          set -eo pipefail
+          find . -name "*.excalidraw" \
+            -not -path "./.git/*" \
+            -not -path "./node_modules/*" \
+          | while IFS= read -r file; do
+            rel="${file#./}"
+            out="diagrams/${rel%.excalidraw}.svg"
+            mkdir -p "$(dirname "$out")"
+            echo "Exporting: $rel → $out"
+            npx excalidraw-brute-export-cli \
+              -i "$file" \
+              -format svg \
+              --scale 1 \
+              --background 1 \
+              --embed-scene 0 \
+              --dark-mode 0 \
+              -o "$out"
+          done
+
+      # Commits back on push to main (PR merged) or manual workflow_dispatch
+      # Skipped entirely during PR validation
+      - name: Commit exported SVGs
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add diagrams/
+          git diff --cached --quiet || git commit -m "chore: auto-export excalidraw diagrams [skip ci]"
+          git push

README.md

@@ -1,5 +1,7 @@
 # RingNet
 
+![Fraud ring graph visualization](assets/images/graph.png)
+
 Graph-based fraud ring detection using Neo4j. Models financial entities as a property graph to detect connected fraud networks through shared identifiers, behavioral patterns, and multi-hop traversal — a use case where graph databases outperform relational at scale.
 
 ---
@@ -259,6 +261,24 @@ The documents in `system_design/` are structured as interview artifacts — ADR,
 
 ---
 
+## Graph Visualization
+
+The image below is the output of running the ring detection query in the Neo4j browser with graph view enabled.
+
+```cypher
+MATCH path = (start:Account {fraud_confirmed: true})-[:HAS_PHONE|HAS_EMAIL|HAS_DEVICE*1..6]-(connected:Account)
+WHERE start <> connected
+RETURN path
+```
+
+This query starts from every confirmed fraud account and traverses outward through shared identifiers — phone, email, and device — up to 6 hops deep. Returning `path` instead of individual properties tells the browser to render the full traversal, including the intermediate Phone, Email, and Device nodes that connect accounts.
+
+Each cluster in the graph is a fraud ring. The intermediate nodes between accounts show *how* the accounts are connected — a shared phone node between two account nodes means both accounts registered the same phone number. The three distinct clusters correspond to the three rings planted by `GenerateData.java` with sizes 5, 8, and 12.
+
+![Fraud ring graph visualization](assets/images/graph.png)
+
+---
+
 ## References
 
 - [Neo4j Fraud Detection Use Cases](https://neo4j.com/use-cases/fraud-detection/)