diff --git a/client/src/features/ai/components/AiPanel.jsx b/client/src/features/ai/components/AiPanel.jsx
index 4f89de5..c76137c 100644
--- a/client/src/features/ai/components/AiPanel.jsx
+++ b/client/src/features/ai/components/AiPanel.jsx
@@ -1,275 +1,359 @@
-import React, { useEffect, useState } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
 import { useDispatch, useSelector } from 'react-redux';
 import { X, AlertTriangle, Loader2, Zap, Wrench } from 'lucide-react';
 import {
   analyzeImpact,
+  resetAiState,
   selectAiImpactState,
 } from '../slices/aiSlice';
 import { selectGraphData } from '../../graph/slices/graphSlice';
 import { aiService } from '../services/aiService';
 
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Converts a raw upstream error message into a user-actionable string.
+ * BUG 1 FIX: previously the 429 from OpenAI was swallowed and shown as
+ * "Failed to load explanation" with no guidance.
+ */
+function friendlyErrorMessage(rawMessage) {
+  const msg = rawMessage || 'Failed to load explanation.';
+
+  if (msg.includes('429') || msg.toLowerCase().includes('quota')) {
+    return 'AI quota exceeded. Add credits at platform.openai.com/billing, or switch to Anthropic / Gemini in your server .env (AI_PROVIDER=anthropic).';
+  }
+  if (msg.includes('503') || msg.toLowerCase().includes('not configured')) {
+    return 'AI provider is not configured. Check AI_API_KEY in your server .env file.';
+  }
+  if (msg.includes('401') && msg.toLowerCase().includes('api')) {
+    return 'AI API key is invalid or expired. Check AI_API_KEY in your server .env file.';
+  }
+  return msg;
+}
+
+// ─── component ──────────────────────────────────────────────────────────────
+
 export default function AiPanel({ nodeId, graph, onClose }) {
   const dispatch = useDispatch();
   const graphData = useSelector(selectGraphData);
   const impactState = useSelector(selectAiImpactState);
   const jobId = graphData?.jobId;
-  const [streamedText, setStreamedText] = useState('');
-  const [isStreaming, setIsStreaming] = useState(false);
-  const [streamError, setStreamError] = useState('');
+
+  const [streamedText, setStreamedText]       = useState('');
+  const [isStreaming, setIsStreaming]          = useState(false);
+  const [streamError, setStreamError]         = useState('');
   const [isLoadingRefactor, setIsLoadingRefactor] = useState(false);
-  const [refactorError, setRefactorError] = useState('');
+  const [refactorError, setRefactorError]     = useState('');
   const [refactorSuggestion, setRefactorSuggestion] = useState(null);
 
+  // BUG 9 FIX: debounce ref — prevents firing a stream on every rapid node click
+  const debounceRef = useRef(null);
+
   const nodeData = nodeId ? graph?.[nodeId] : null;
 
   useEffect(() => {
+    // BUG 6 FIX: clear stale impact data from the previous node immediately
+    dispatch(resetAiState());
+    setStreamedText('');
+    setStreamError('');
+    setRefactorSuggestion(null);
+    setRefactorError('');
+
     if (!nodeId || !jobId) {
-      setStreamedText('');
       setIsStreaming(false);
-      setStreamError('');
+      clearTimeout(debounceRef.current);
       return;
     }
 
+    // Cancel any in-flight debounce from a previous rapid click
+    clearTimeout(debounceRef.current);
+
     let isCancelled = false;
     const controller = new AbortController();
 
-    setStreamedText('');
-    setIsStreaming(true);
-    setStreamError('');
-    setRefactorSuggestion(null);
-    setRefactorError('');
+    // BUG 9 FIX: wait 600 ms before firing the stream — if the user clicks
+    // another node within that window the previous timeout is cancelled.
+    debounceRef.current = setTimeout(() => {
+      setIsStreaming(true);
+
+      aiService
+        .streamExplain({
+          question: `Explain the file ${nodeId}: its purpose, key functions, dependencies, and architectural risks.`,
+          jobId,
+          signal: controller.signal,
 
-    aiService
-      .streamExplain({
-        question: `Explain the file ${nodeId} and include its purpose, key functions, dependencies, and risks.`,
-        jobId,
-        signal: controller.signal,
-        onChunk: (text) => {
-          if (isCancelled) return;
-          setStreamedText((prev) => prev + text);
-        },
-        onDone: () => {
-          if (isCancelled) return;
-          setIsStreaming(false);
-        },
-        onError: (error) => {
-          if (isCancelled) return;
-          setStreamError(error?.message || 'Failed to load explanation');
-          setIsStreaming(false);
-        },
-      })
-      .catch(() => {
-        // Errors are handled in onError callback.
-      });
+          onChunk: (text) => {
+            if (!isCancelled) setStreamedText((prev) => prev + text);
+          },
+
+          onDone: () => {
+            if (!isCancelled) setIsStreaming(false);
+          },
+
+          // BUG 1 FIX: convert upstream error codes to actionable messages
+          onError: (err) => {
+            if (isCancelled) return;
+            setStreamError(friendlyErrorMessage(err?.message));
+            setIsStreaming(false);
+          },
+        })
+        .catch(() => {
+          // Errors are handled via onError above.
+        });
+    }, 600);
 
     return () => {
       isCancelled = true;
       controller.abort();
+      clearTimeout(debounceRef.current);
     };
-  }, [nodeId, jobId]);
+  }, [nodeId, jobId, dispatch]);
 
+  // ─── guard: nothing selected ─────────────────────────────────────────────
   if (!nodeId || !nodeData) return null;
 
   const { deps = [], type, declarations = [], summary } = nodeData;
-  const usedBy = Object.entries(graph)
+
+  const usedBy = Object.entries(graph || {})
     .filter(([, value]) => value.deps?.includes(nodeId))
     .map(([file]) => file);
 
   const impactedFiles = impactState?.data?.affectedFiles || [];
-  const isImpacting = impactState?.status === 'loading';
+  const isImpacting   = impactState?.status === 'loading';
 
-  const handleSimulateImpact = () => {
+  // ─── handlers ────────────────────────────────────────────────────────────
+  function handleRunImpact() {
     if (!jobId || !nodeId) return;
     dispatch(analyzeImpact({ jobId, filePath: nodeId }));
-  };
+  }
 
-  const handleSuggestRefactor = async () => {
+  async function handleSuggestRefactor() {
     if (!jobId || !nodeId || isLoadingRefactor) return;
-
     setIsLoadingRefactor(true);
     setRefactorError('');
-
+    setRefactorSuggestion(null);
     try {
-      const result = await aiService.suggestRefactor({
-        jobId,
-        filePath: nodeId,
-      });
-
+      const result = await aiService.suggestRefactor({ jobId, filePath: nodeId });
       setRefactorSuggestion(result);
-    } catch (error) {
-      setRefactorSuggestion(null);
-      setRefactorError(error?.response?.data?.error || error?.message || 'Failed to load suggestions.');
+    } catch (err) {
+      setRefactorError(friendlyErrorMessage(err?.message));
     } finally {
       setIsLoadingRefactor(false);
     }
-  };
+  }
 
+  // ─── render ──────────────────────────────────────────────────────────────
   return (
-    <div className="w-full rounded-xl border border-border bg-card/95 backdrop-blur-sm p-4 text-xs shadow-xl transition-all">
-      <div className="flex items-start justify-between gap-2 mb-3">
-        <div className="flex items-center gap-1.5 min-w-0">
-          <span className="font-mono font-semibold text-foreground truncate">{nodeId}</span>
+    <div className="relative flex h-full flex-col gap-4 overflow-y-auto rounded-xl border border-border/60 bg-card/80 p-4 shadow-sm backdrop-blur-sm">
+      {/* Header */}
+      <div className="flex items-start justify-between gap-2">
+        <div className="min-w-0">
+          <p className="text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+            Selected Node
+          </p>
+          <p className="truncate font-mono text-sm font-semibold text-foreground">
+            {nodeId}
+          </p>
+          {type && (
+            <span className="mt-1 inline-block rounded-full border border-border/40 bg-muted/40 px-2 py-0.5 text-[10px] text-muted-foreground">
+              {type}
+            </span>
+          )}
         </div>
-        <button
-          onClick={onClose}
-          className="shrink-0 text-muted-foreground hover:text-foreground transition-colors"
-          aria-label="Close"
-        >
-          <X className="size-3.5" />
-        </button>
+        {onClose && (
+          <button
+            onClick={onClose}
+            className="shrink-0 text-muted-foreground transition-colors hover:text-foreground"
+            aria-label="Close panel"
+          >
+            <X className="size-4" />
+          </button>
+        )}
       </div>
 
-      <p className="mb-3 text-muted-foreground">
-        Type: <span className="capitalize text-foreground/80">{type}</span>
-      </p>
-
-      {summary && !streamedText && !isStreaming && !streamError && (
-        <div className="mb-3 rounded-lg border border-border bg-background/40 p-3">
-          <p className="mb-1 text-muted-foreground/60 uppercase tracking-wider text-[10px]">Summary</p>
-          <p className="text-foreground/90 leading-relaxed">{summary}</p>
+      {/* AI Explanation */}
+      <section>
+        <p className="mb-1.5 text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+          AI Explanation
+        </p>
+        <div className="min-h-[60px] rounded-lg border border-border/40 bg-muted/20 p-3 text-xs leading-relaxed text-foreground/80">
+          {isStreaming && !streamedText && (
+            <span className="flex items-center gap-2 text-muted-foreground">
+              <Loader2 className="size-3 animate-spin" />
+              Generating explanation…
+            </span>
+          )}
+          {streamedText && <span>{streamedText}</span>}
+          {isStreaming && streamedText && (
+            <span className="ml-1 inline-block size-1.5 animate-pulse rounded-full bg-primary" />
+          )}
+          {!isStreaming && !streamedText && !streamError && (
+            <span className="text-muted-foreground">No explanation yet.</span>
+          )}
+          {/* BUG 1 FIX: display the friendly error message */}
+          {streamError && (
+            <div className="flex items-start gap-2 text-destructive">
+              <AlertTriangle className="mt-0.5 size-3 shrink-0" />
+              <span>{streamError}</span>
+            </div>
+          )}
         </div>
+      </section>
+
+      {/* Graph metadata */}
+      {summary && (
+        <section>
+          <p className="mb-1 text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+            Summary
+          </p>
+          <p className="text-xs text-foreground/70">{summary}</p>
+        </section>
       )}
 
-      <div className="mb-3 rounded-lg border border-border bg-background/40 p-3">
-        <p className="mb-2 text-muted-foreground/60 uppercase tracking-wider text-[10px] flex items-center gap-1">
-          <Zap className="size-3" /> AI Explanation
-        </p>
-        {isStreaming && (
-          <div className="flex items-center gap-2 text-muted-foreground">
-            <Loader2 className="size-3 animate-spin" />
-            <span>Analyzing...</span>
+      {/* Exports */}
+      {declarations.length > 0 && (
+        <section>
+          <p className="mb-1 text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+            Exports ({declarations.length})
+          </p>
+          <div className="flex flex-wrap gap-1">
+            {declarations.slice(0, 12).map((d) => (
+              <span
+                key={d?.name}
+                className="rounded border border-border/40 bg-muted/30 px-1.5 py-0.5 font-mono text-[10px] text-foreground/70"
+              >
+                {d?.name}
+              </span>
+            ))}
+            {declarations.length > 12 && (
+              <span className="text-[10px] text-muted-foreground">
+                +{declarations.length - 12} more
+              </span>
+            )}
           </div>
-        )}
-        {streamError && (
-          <p className="text-red-400 flex items-center gap-1">
-            <AlertTriangle className="size-3" /> {streamError}
+        </section>
+      )}
+
+      {/* Dependencies */}
+      {deps.length > 0 && (
+        <section>
+          <p className="mb-1 text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+            Imports ({deps.length})
+          </p>
+          <ul className="space-y-0.5">
+            {deps.slice(0, 6).map((dep) => (
+              <li key={dep} className="truncate font-mono text-[10px] text-muted-foreground">
+                {dep}
+              </li>
+            ))}
+            {deps.length > 6 && (
+              <li className="text-[10px] text-muted-foreground">+{deps.length - 6} more</li>
+            )}
+          </ul>
+        </section>
+      )}
+
+      {/* Used by */}
+      {usedBy.length > 0 && (
+        <section>
+          <p className="mb-1 text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+            Used by ({usedBy.length})
+          </p>
+          <ul className="space-y-0.5">
+            {usedBy.slice(0, 6).map((f) => (
+              <li key={f} className="truncate font-mono text-[10px] text-muted-foreground">
+                {f}
+              </li>
+            ))}
+            {usedBy.length > 6 && (
+              <li className="text-[10px] text-muted-foreground">+{usedBy.length - 6} more</li>
+            )}
+          </ul>
+        </section>
+      )}
+
+      {/* Impact analysis */}
+      <section>
+        <div className="mb-2 flex items-center justify-between">
+          <p className="text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+            Impact Analysis
           </p>
+          <button
+            onClick={handleRunImpact}
+            disabled={isImpacting}
+            className="flex items-center gap-1 rounded-md border border-border/40 bg-muted/30 px-2 py-1 text-[10px] text-foreground/70 transition-colors hover:bg-muted/60 disabled:opacity-50"
+          >
+            {isImpacting ? (
+              <Loader2 className="size-2.5 animate-spin" />
+            ) : (
+              <Zap className="size-2.5" />
+            )}
+            {isImpacting ? 'Analysing…' : 'Run'}
+          </button>
+        </div>
+        {impactedFiles.length > 0 && (
+          <ul className="space-y-0.5">
+            {impactedFiles.slice(0, 8).map((f) => (
+              <li key={f} className="truncate font-mono text-[10px] text-muted-foreground">
+                {f}
+              </li>
+            ))}
+            {impactedFiles.length > 8 && (
+              <li className="text-[10px] text-muted-foreground">+{impactedFiles.length - 8} more</li>
+            )}
+          </ul>
         )}
-        {streamedText && (
-          <p className="text-foreground/90 leading-relaxed whitespace-pre-wrap">{streamedText}</p>
+        {impactState?.status === 'failed' && (
+          <p className="text-[10px] text-destructive">{impactState?.error?.message || 'Impact analysis failed.'}</p>
         )}
-      </div>
+      </section>
 
-      <div className="mb-3 rounded-lg border border-border bg-background/40 p-3">
-        <div className="mb-2 flex items-center justify-between gap-2">
-          <p className="text-muted-foreground/60 uppercase tracking-wider text-[10px] flex items-center gap-1">
-            <Wrench className="size-3" /> Refactor Suggestions
+      {/* Refactor suggestions */}
+      <section>
+        <div className="mb-2 flex items-center justify-between">
+          <p className="text-[10px] font-semibold uppercase tracking-widest text-muted-foreground">
+            Refactor Suggestions
           </p>
           <button
-            type="button"
             onClick={handleSuggestRefactor}
-            disabled={!jobId || isLoadingRefactor}
-            className="text-[10px] text-primary/70 hover:text-primary disabled:opacity-40 transition-colors"
+            disabled={isLoadingRefactor}
+            className="flex items-center gap-1 rounded-md border border-border/40 bg-muted/30 px-2 py-1 text-[10px] text-foreground/70 transition-colors hover:bg-muted/60 disabled:opacity-50"
           >
-            {isLoadingRefactor ? 'Analyzing...' : 'Suggest refactor ->'}
+            {isLoadingRefactor ? (
+              <Loader2 className="size-2.5 animate-spin" />
+            ) : (
+              <Wrench className="size-2.5" />
+            )}
+            {isLoadingRefactor ? 'Loading…' : 'Suggest'}
           </button>
         </div>
-
-        {isLoadingRefactor && (
-          <div className="flex items-center gap-2 text-muted-foreground">
-            <Loader2 className="size-3 animate-spin" />
-            <span>Evaluating architecture risk...</span>
-          </div>
-        )}
-
         {refactorError && (
-          <p className="text-red-400 flex items-center gap-1">
-            <AlertTriangle className="size-3" /> {refactorError}
-          </p>
+          <p className="text-[10px] text-destructive">{refactorError}</p>
         )}
-
-        {refactorSuggestion && !isLoadingRefactor && !refactorError && (
-          <div className="space-y-2">
-            <p className="text-foreground/80">
-              Priority: <span className="uppercase">{refactorSuggestion.priority || 'medium'}</span>
-              {' '}· Effort: <span>{refactorSuggestion.estimatedEffort || 'unknown'}</span>
-            </p>
-
+        {refactorSuggestion && (
+          <div className="space-y-2 text-xs">
             {refactorSuggestion.concerns?.length > 0 && (
               <div>
-                <p className="mb-1 text-muted-foreground/60 uppercase tracking-wider text-[10px]">Concerns</p>
-                <ul className="list-disc pl-4 space-y-1 text-foreground/90">
-                  {refactorSuggestion.concerns.map((item, index) => (
-                    <li key={`concern-${index}`}>{item}</li>
-                  ))}
+                <p className="font-medium text-foreground/80">Concerns:</p>
+                <ul className="mt-0.5 list-inside list-disc space-y-0.5 text-muted-foreground">
+                  {refactorSuggestion.concerns.map((c, i) => <li key={i}>{c}</li>)}
                 </ul>
               </div>
             )}
-
             {refactorSuggestion.suggestions?.length > 0 && (
               <div>
-                <p className="mb-1 text-muted-foreground/60 uppercase tracking-wider text-[10px]">Suggestions</p>
-                <ul className="list-disc pl-4 space-y-1 text-foreground/90">
-                  {refactorSuggestion.suggestions.map((item, index) => (
-                    <li key={`suggestion-${index}`}>{item}</li>
-                  ))}
+                <p className="font-medium text-foreground/80">Suggestions:</p>
+                <ul className="mt-0.5 list-inside list-disc space-y-0.5 text-muted-foreground">
+                  {refactorSuggestion.suggestions.map((s, i) => <li key={i}>{s}</li>)}
                 </ul>
               </div>
             )}
+            <p className="text-[10px] text-muted-foreground">
+              Priority: {refactorSuggestion.priority} · Effort: {refactorSuggestion.estimatedEffort}
+            </p>
           </div>
         )}
-      </div>
-
-      {declarations.length > 0 && (
-        <div className="mb-3">
-          <p className="mb-1 text-muted-foreground/60 uppercase tracking-wider text-[10px]">
-            Declarations ({declarations.length})
-          </p>
-          <ul className="flex flex-wrap gap-1">
-            {declarations.map((d) => (
-              <li key={`${d.kind}:${d.name}`} className="bg-muted rounded px-1.5 py-0.5 font-mono text-[10px]">
-                {d.name}
-              </li>
-            ))}
-          </ul>
-        </div>
-      )}
-
-      <div className="mb-3">
-        <div className="flex items-center justify-between mb-1">
-          <p className="text-muted-foreground/60 uppercase tracking-wider text-[10px]">Impact Analysis</p>
-          <button
-            type="button"
-            onClick={handleSimulateImpact}
-            disabled={isImpacting || !jobId}
-            className="text-[10px] text-amber-400/70 hover:text-amber-400 disabled:opacity-40 transition-colors"
-          >
-            {isImpacting ? 'Running...' : 'Simulate change ->'}
-          </button>
-        </div>
-
-        {impactedFiles.length > 0 && (
-          <div className="rounded-lg border border-amber-500/30 bg-amber-500/5 p-2">
-            <ul className="flex flex-col gap-0.5 custom-scrollbar">
-              {impactedFiles.map((file) => (
-                <li key={file} className="font-mono text-amber-200/80 truncate">{file}</li>
-              ))}
-            </ul>
-          </div>
-        )}
-      </div>
-
-      {deps.length > 0 && (
-        <div className="mb-3">
-          <p className="mb-1 text-muted-foreground/60 uppercase tracking-wider text-[10px]">Imports ({deps.length})</p>
-          <ul className="flex flex-col gap-0.5 custom-scrollbar">
-            {deps.map((dep) => (
-              <li key={dep} className="font-mono text-gold/80 truncate">{dep}</li>
-            ))}
-          </ul>
-        </div>
-      )}
-
-      {usedBy.length > 0 && (
-        <div className="mb-3">
-          <p className="mb-1 text-muted-foreground/60 uppercase tracking-wider text-[10px]">Used By ({usedBy.length})</p>
-          <ul className="flex flex-col gap-0.5 custom-scrollbar">
-            {usedBy.map((file) => (
-              <li key={file} className="font-mono text-foreground/70 truncate">{file}</li>
-            ))}
-          </ul>
-        </div>
-      )}
+      </section>
     </div>
   );
 }
diff --git a/client/src/features/dashboard/pages/DashboardPage.jsx b/client/src/features/dashboard/pages/DashboardPage.jsx
index 89f8ffd..013391d 100644
--- a/client/src/features/dashboard/pages/DashboardPage.jsx
+++ b/client/src/features/dashboard/pages/DashboardPage.jsx
@@ -3,7 +3,6 @@ import { Link, useSearchParams, useNavigate } from 'react-router-dom';
 import { useDispatch, useSelector } from 'react-redux';
 import {
   Network,
-  GitBranch,
   Zap,
   ArrowRight,
   Database,
@@ -63,33 +62,6 @@ const QUICK_ACTIONS = [
   },
 ];
 
-const PHASE_ROADMAP = [
-  {
-    phase: 'Phase 1',
-    label: 'Current',
-    status: 'active',
-    items: ['AST parsing (JS/TS)', 'Dependency graph', 'Interactive visualization'],
-  },
-  {
-    phase: 'Phase 2',
-    label: 'Upcoming',
-    status: 'upcoming',
-    items: ['AI code summaries', 'Natural language Q&A', 'Dead code detection'],
-  },
-  {
-    phase: 'Phase 3',
-    label: 'Future',
-    status: 'future',
-    items: ['Impact analysis', 'Refactor suggestions', 'GitHub PR integration'],
-  },
-];
-
-const STATUS_STYLES = {
-  active:   'bg-green-500/20 text-green-400 border-green-500/30',
-  upcoming: 'bg-yellow-500/20 text-yellow-400 border-yellow-500/30',
-  future:   'bg-gray-500/20 text-gray-400 border-gray-500/30',
-};
-
 const SORT_OPTIONS = [
   { value: 'recent', label: 'Most recent first' },
   { value: 'oldest', label: 'Oldest first' },
@@ -131,10 +103,13 @@ const formatDate = (value) => {
   if (!value) return 'Unknown';
   const parsed = new Date(value);
   if (Number.isNaN(parsed.getTime())) return 'Unknown';
-  return new Intl.DateTimeFormat(undefined, {
-    dateStyle: 'medium',
-    timeStyle: 'short',
-  }).format(parsed);
+  
+  const month = parsed.toLocaleString(undefined, { month: 'short' });
+  const day = parsed.getDate();
+  const year = parsed.getFullYear().toString().slice(-2);
+  const time = parsed.toLocaleString(undefined, { hour: 'numeric', minute: '2-digit', hour12: true });
+  
+  return `${month} ${day}, '${year}, ${time}`;
 };
 
 const formatPercent = (value) => {
@@ -173,21 +148,32 @@ const getCacheHealthBadgeStyle = (level) => {
 
 function MetricCard({ icon, title, value, helper, index = 0 }) {
   return (
-    <Card 
-      className="shadow-neu-inset border-none bg-background/60 rounded-2xl animate-in fade-in zoom-in-95 duration-700 fill-mode-both"
-      style={{ animationDelay: `${200 + index * 100}ms` }}
+    <Card
+      className="group relative overflow-hidden shadow-neu-inset border-none bg-background/40 hover:bg-background/60 rounded-2xl transition-all duration-500 animate-in fade-in zoom-in-95 fill-mode-both active:scale-[0.98]"
+      style={{ 
+        animationDelay: `${200 + index * 100}ms`,
+        transitionTimingFunction: 'cubic-bezier(0.23, 1, 0.32, 1)'
+      }}
     >
-      <CardHeader className="pb-3">
-        <div className="flex items-center gap-3 text-xs uppercase tracking-widest font-bold text-muted-foreground/70">
-          <div className="flex size-9 items-center justify-center rounded-xl bg-background/50 shadow-neu-inset border-none">
+      <CardContent className="flex items-center justify-between p-5">
+        <div className="flex items-center gap-4">
+          <div className="flex size-11 items-center justify-center rounded-xl bg-background/50 shadow-neu-inset border border-border/5 group-hover:scale-110 transition-transform duration-500">
             {icon}
           </div>
-          <span>{title}</span>
+          <div className="flex flex-col gap-0.5">
+            <span className="text-[11px] uppercase tracking-[0.2em] font-bold text-muted-foreground/40 group-hover:text-muted-foreground/70 transition-colors duration-300">
+              {title}
+            </span>
+            {helper && (
+              <p className="text-[9px] font-bold uppercase tracking-widest text-muted-foreground/30">
+                {helper}
+              </p>
+            )}
+          </div>
         </div>
-      </CardHeader>
-      <CardContent className="pt-0">
-        <p className="text-3xl font-display font-bold tracking-tight text-foreground">{value}</p>
-        <p className="mt-2 text-[10px] uppercase font-bold tracking-wider text-muted-foreground/50">{helper}</p>
+        <p className="text-xl font-display font-bold tracking-tight text-foreground/80 group-hover:text-foreground transition-colors duration-300 text-right">
+          {value}
+        </p>
       </CardContent>
     </Card>
   );
@@ -252,7 +238,7 @@ export default function DashboardPage() {
   }, [dispatch, user?.id]);
 
   useEffect(() => {
-    if (!user?.id) return undefined;
+    if (!user?.id || import.meta.env.VITE_APP_ENV !== 'development') return undefined;
 
     let cancelled = false;
     cachePollFailureRef.current = 0;
@@ -340,39 +326,46 @@ export default function DashboardPage() {
   }, [searchTerm, setSearchParams, sortBy, sourceFilter]);
 
   const stats = useMemo(
-    () => [
-      {
-        key: 'total',
-        icon: <Database className="size-4 text-primary" />,
-        title: 'Analyzed repositories',
-        value: summary.totalAnalyzed,
-        helper: 'Stored for this user in the analysis history table.',
-      },
-      {
-        key: 'owners',
-        icon: <FolderGit2 className="size-4 text-primary" />,
-        title: 'Unique owners',
-        value: summary.uniqueOwners,
-        helper: 'Distinct repository owners represented in history.',
-      },
-      {
-        key: 'last',
-        icon: <Clock3 className="size-4 text-primary" />,
-        title: 'Last analyzed',
-        value: summary.lastAnalyzedAt ? formatDate(summary.lastAnalyzedAt) : 'No analyses yet',
-        helper: 'Most recent analysis timestamp returned by the backend.',
-      },
-      {
-        key: 'cache-hit-rate',
-        icon: <Zap className="size-4 text-primary" />,
-        title: 'Cache hit rate',
-        value: formatPercent(cacheMetrics.summary.hitRatePercent),
-        helper:
-          cacheMetricsStatus === 'loading'
-            ? 'Refreshing cache metrics...'
-            : `Reads ${cacheMetrics.summary.readsTotal} · Redis ${cacheMetrics.redis.status}`,
-      },
-    ],
+    () => {
+      const items = [
+        {
+          key: 'total',
+          icon: <Database className="size-4 text-primary" />,
+          title: 'Analyzed repositories',
+          value: summary.totalAnalyzed,
+          helper: '',
+        },
+        {
+          key: 'owners',
+          icon: <FolderGit2 className="size-4 text-primary" />,
+          title: 'Unique owners',
+          value: summary.uniqueOwners,
+          helper: '',
+        },
+        {
+          key: 'last',
+          icon: <Clock3 className="size-4 text-primary" />,
+          title: 'Last analyzed',
+          value: summary.lastAnalyzedAt ? formatDate(summary.lastAnalyzedAt) : 'No analyses yet',
+          helper: '',
+        },
+      ];
+
+      if (import.meta.env.VITE_APP_ENV === 'development') {
+        items.push({
+          key: 'cache-hit-rate',
+          icon: <Zap className="size-4 text-primary" />,
+          title: 'Cache hit rate',
+          value: formatPercent(cacheMetrics.summary.hitRatePercent),
+          helper:
+            cacheMetricsStatus === 'loading'
+              ? 'Refreshing cache metrics...'
+              : `Reads ${cacheMetrics.summary.readsTotal} · Redis ${cacheMetrics.redis.status}`,
+        });
+      }
+
+      return items;
+    },
     [
       cacheMetrics.redis.status,
       cacheMetrics.summary.hitRatePercent,
@@ -562,7 +555,9 @@ export default function DashboardPage() {
   const refreshHistory = () => {
     if (!user?.id) return;
     dispatch(fetchAnalyzedRepositories({ userId: user.id, page: 1, limit: 50 }));
-    dispatch(fetchCacheMetrics());
+    if (import.meta.env.VITE_APP_ENV === 'development') {
+      dispatch(fetchCacheMetrics());
+    }
   };
 
   const clearFilters = () => {
@@ -695,22 +690,22 @@ export default function DashboardPage() {
     const config =
       repo.source === 'local'
         ? {
-            source: 'local',
-            localPath: repo.fullName,
-          }
+          source: 'local',
+          localPath: repo.fullName,
+        }
         : {
-            source: 'github',
-            github: {
-              mode:
-                repo.githubMode ||
-                (repo.sourceCategory === 'github-public' ? 'public' : 'owned'),
-              owner: repo.owner,
-              repo: repo.name,
-              branch: repo.branch || 'main',
-            },
-          };
-
-      handleSelectAnalyzeRepository(repo);
+          source: 'github',
+          github: {
+            mode:
+              repo.githubMode ||
+              (repo.sourceCategory === 'github-public' ? 'public' : 'owned'),
+            owner: repo.owner,
+            repo: repo.name,
+            branch: repo.branch || 'main',
+          },
+        };
+
+    handleSelectAnalyzeRepository(repo);
 
     dispatch(analyzeCodebase(config));
     navigate('/graph');
@@ -723,9 +718,6 @@ export default function DashboardPage() {
         <h1 className="text-4xl font-display font-bold tracking-tight text-foreground">
           Welcome back, <span className="text-gold">{displayName}</span>
         </h1>
-        <p className="mt-2 text-sm text-muted-foreground/80 font-medium tracking-wide">
-          CodeGraph <span className="text-gold">AI</span> · Phase 1 Visualization Engine
-        </p>
       </div>
 
       <section className="animate-in fade-in slide-in-from-bottom-4 duration-700 delay-150">
@@ -734,8 +726,8 @@ export default function DashboardPage() {
         </h2>
         <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
           {QUICK_ACTIONS.map((action, idx) => (
-            <Card 
-              key={action.title} 
+            <Card
+              key={action.title}
               className="group rounded-2xl shadow-neu-inset border-none bg-background/40 hover:bg-background/60 transition-all duration-500 animate-in fade-in slide-in-from-bottom-4 fill-mode-both"
               style={{ animationDelay: `${300 + idx * 100}ms` }}
             >
@@ -793,109 +785,111 @@ export default function DashboardPage() {
           ))}
         </div>
 
-        <Card className="mt-4 rounded-2xl shadow-neu-inset border-none bg-background/40">
-          <CardHeader className="pb-3">
-            <div className="flex flex-wrap items-center justify-between gap-2">
-              <div className="flex items-center gap-2">
-                <div className="flex size-8 items-center justify-center rounded-lg bg-background/50 shadow-neu-inset">
-                  <BarChart3 className="size-4 text-primary" />
-                </div>
-                <div>
-                  <CardTitle className="text-sm font-semibold tracking-wide">Cache operations snapshot</CardTitle>
-                  <CardDescription className="text-[11px]">
-                    Rolling session view with adaptive polling and backoff.
-                  </CardDescription>
+        {import.meta.env.VITE_APP_ENV === 'development' && (
+          <Card className="mt-4 rounded-2xl shadow-neu-inset border-none bg-background/40">
+            <CardHeader className="pb-3">
+              <div className="flex flex-wrap items-center justify-between gap-2">
+                <div className="flex items-center gap-2">
+                  <div className="flex size-8 items-center justify-center rounded-lg bg-background/50 shadow-neu-inset">
+                    <BarChart3 className="size-4 text-primary" />
+                  </div>
+                  <div>
+                    <CardTitle className="text-sm font-semibold tracking-wide">Cache operations snapshot</CardTitle>
+                    <CardDescription className="text-[11px]">
+                      Rolling session view with adaptive polling and backoff.
+                    </CardDescription>
+                  </div>
                 </div>
+                <span className="text-[10px] uppercase font-bold tracking-wider text-muted-foreground/70">
+                  {cacheTrendSummary.latest?.generatedAt
+                    ? `Updated ${formatDate(cacheTrendSummary.latest.generatedAt)}`
+                    : 'Awaiting first metrics sample'}
+                </span>
               </div>
-              <span className="text-[10px] uppercase font-bold tracking-wider text-muted-foreground/70">
-                {cacheTrendSummary.latest?.generatedAt
-                  ? `Updated ${formatDate(cacheTrendSummary.latest.generatedAt)}`
-                  : 'Awaiting first metrics sample'}
-              </span>
-            </div>
-            <div className="mt-2 flex items-center justify-between gap-2">
-              <span className={`rounded-full px-2 py-1 text-[10px] font-bold uppercase tracking-wider ${getCacheHealthBadgeStyle(cacheHealth.level)}`}>
-                Cache health: {cacheHealth.level}
-              </span>
-              <span className="text-[10px] text-muted-foreground/70">
-                Warning floor {CACHE_HIT_RATE_WARN_PERCENT}% · Critical floor {CACHE_HIT_RATE_CRITICAL_PERCENT}%
-              </span>
-            </div>
-          </CardHeader>
-          <CardContent className="grid gap-4 md:grid-cols-3">
-            {cacheHealth.alerts.length > 0 ? (
-              <div className="md:col-span-3 rounded-xl border border-amber-500/30 bg-amber-500/10 px-3 py-2">
-                <p className="flex items-center gap-1 text-[11px] font-semibold text-amber-200">
-                  <AlertTriangle className="size-3.5" />
-                  Active cache alerts
-                </p>
-                <ul className="mt-1 space-y-1 text-[11px] text-amber-100/90">
-                  {cacheHealth.alerts.map((alert) => (
-                    <li key={alert.id}>- {alert.message}</li>
-                  ))}
-                </ul>
+              <div className="mt-2 flex items-center justify-between gap-2">
+                <span className={`rounded-full px-2 py-1 text-[10px] font-bold uppercase tracking-wider ${getCacheHealthBadgeStyle(cacheHealth.level)}`}>
+                  Cache health: {cacheHealth.level}
+                </span>
+                <span className="text-[10px] text-muted-foreground/70">
+                  Warning floor {CACHE_HIT_RATE_WARN_PERCENT}% · Critical floor {CACHE_HIT_RATE_CRITICAL_PERCENT}%
+                </span>
               </div>
-            ) : null}
+            </CardHeader>
+            <CardContent className="grid gap-4 md:grid-cols-3">
+              {cacheHealth.alerts.length > 0 ? (
+                <div className="md:col-span-3 rounded-xl border border-amber-500/30 bg-amber-500/10 px-3 py-2">
+                  <p className="flex items-center gap-1 text-[11px] font-semibold text-amber-200">
+                    <AlertTriangle className="size-3.5" />
+                    Active cache alerts
+                  </p>
+                  <ul className="mt-1 space-y-1 text-[11px] text-amber-100/90">
+                    {cacheHealth.alerts.map((alert) => (
+                      <li key={alert.id}>- {alert.message}</li>
+                    ))}
+                  </ul>
+                </div>
+              ) : null}
 
-            <div className="rounded-xl bg-background/50 px-3 py-2 shadow-neu-inset">
-              <p className="text-[10px] uppercase tracking-wider text-muted-foreground/70">Hit rate trend</p>
-              <p className="mt-1 text-xl font-display font-bold text-foreground">
-                {formatPercent(cacheTrendSummary.latest?.hitRatePercent)}
-              </p>
-              <p className="text-[10px] text-muted-foreground/70">
-                {Number.isFinite(cacheTrendSummary.hitRateDelta)
-                  ? `${cacheTrendSummary.hitRateDelta >= 0 ? '+' : ''}${cacheTrendSummary.hitRateDelta.toFixed(2)} pts from previous sample`
-                  : 'Need two samples to compute delta'}
-              </p>
-            </div>
+              <div className="rounded-xl bg-background/50 px-3 py-2 shadow-neu-inset">
+                <p className="text-[10px] uppercase tracking-wider text-muted-foreground/70">Hit rate trend</p>
+                <p className="mt-1 text-xl font-display font-bold text-foreground">
+                  {formatPercent(cacheTrendSummary.latest?.hitRatePercent)}
+                </p>
+                <p className="text-[10px] text-muted-foreground/70">
+                  {Number.isFinite(cacheTrendSummary.hitRateDelta)
+                    ? `${cacheTrendSummary.hitRateDelta >= 0 ? '+' : ''}${cacheTrendSummary.hitRateDelta.toFixed(2)} pts from previous sample`
+                    : 'Need two samples to compute delta'}
+                </p>
+              </div>
 
-            <div className="rounded-xl bg-background/50 px-3 py-2 shadow-neu-inset">
-              <p className="text-[10px] uppercase tracking-wider text-muted-foreground/70">Read throughput</p>
-              <p className="mt-1 text-xl font-display font-bold text-foreground">
-                {formatCompactNumber(cacheTrendSummary.latest?.readsTotal)}
-              </p>
-              <p className="text-[10px] text-muted-foreground/70">
-                {Number.isFinite(cacheTrendSummary.readsDelta)
-                  ? `${cacheTrendSummary.readsDelta >= 0 ? '+' : ''}${cacheTrendSummary.readsDelta} reads since previous sample`
-                  : 'Need two samples to compute delta'}
-              </p>
-            </div>
+              <div className="rounded-xl bg-background/50 px-3 py-2 shadow-neu-inset">
+                <p className="text-[10px] uppercase tracking-wider text-muted-foreground/70">Read throughput</p>
+                <p className="mt-1 text-xl font-display font-bold text-foreground">
+                  {formatCompactNumber(cacheTrendSummary.latest?.readsTotal)}
+                </p>
+                <p className="text-[10px] text-muted-foreground/70">
+                  {Number.isFinite(cacheTrendSummary.readsDelta)
+                    ? `${cacheTrendSummary.readsDelta >= 0 ? '+' : ''}${cacheTrendSummary.readsDelta} reads since previous sample`
+                    : 'Need two samples to compute delta'}
+                </p>
+              </div>
 
-            <div className="rounded-xl bg-background/50 px-3 py-2 shadow-neu-inset">
-              <p className="text-[10px] uppercase tracking-wider text-muted-foreground/70">Read errors</p>
-              <p className="mt-1 text-xl font-display font-bold text-foreground">
-                {formatCompactNumber(cacheTrendSummary.latest?.readError)}
-              </p>
-              <p className="text-[10px] text-muted-foreground/70">
-                {Number.isFinite(cacheTrendSummary.errorDelta)
-                  ? `${cacheTrendSummary.errorDelta >= 0 ? '+' : ''}${cacheTrendSummary.errorDelta} since previous sample`
-                  : 'Need two samples to compute delta'}
-              </p>
-            </div>
+              <div className="rounded-xl bg-background/50 px-3 py-2 shadow-neu-inset">
+                <p className="text-[10px] uppercase tracking-wider text-muted-foreground/70">Read errors</p>
+                <p className="mt-1 text-xl font-display font-bold text-foreground">
+                  {formatCompactNumber(cacheTrendSummary.latest?.readError)}
+                </p>
+                <p className="text-[10px] text-muted-foreground/70">
+                  {Number.isFinite(cacheTrendSummary.errorDelta)
+                    ? `${cacheTrendSummary.errorDelta >= 0 ? '+' : ''}${cacheTrendSummary.errorDelta} since previous sample`
+                    : 'Need two samples to compute delta'}
+                </p>
+              </div>
 
-            <div className="md:col-span-3 rounded-xl bg-background/60 px-3 py-3 shadow-neu-inset">
-              <p className="text-[10px] uppercase tracking-wider text-muted-foreground/70">Session sparkline</p>
-              {cacheTrendBars.length > 0 ? (
-                <div className="mt-2 flex h-20 items-end gap-1">
-                  {cacheTrendBars.map((bar) => (
-                    <div
-                      key={bar.id}
-                      className="group relative h-full flex-1 rounded-sm bg-gold/10"
-                      title={`Hit rate ${bar.label}`}
-                    >
+              <div className="md:col-span-3 rounded-xl bg-background/60 px-3 py-3 shadow-neu-inset">
+                <p className="text-[10px] uppercase tracking-wider text-muted-foreground/70">Session sparkline</p>
+                {cacheTrendBars.length > 0 ? (
+                  <div className="mt-2 flex h-20 items-end gap-1">
+                    {cacheTrendBars.map((bar) => (
                       <div
-                        className="absolute bottom-0 left-0 right-0 rounded-sm bg-gold/70 transition-all duration-300 group-hover:bg-gold"
-                        style={{ height: bar.height }}
-                      />
-                    </div>
-                  ))}
-                </div>
-              ) : (
-                <p className="mt-2 text-xs text-muted-foreground">Collecting cache trend samples...</p>
-              )}
-            </div>
-          </CardContent>
-        </Card>
+                        key={bar.id}
+                        className="group relative h-full flex-1 rounded-sm bg-gold/10"
+                        title={`Hit rate ${bar.label}`}
+                      >
+                        <div
+                          className="absolute bottom-0 left-0 right-0 rounded-sm bg-gold/70 transition-all duration-300 group-hover:bg-gold"
+                          style={{ height: bar.height }}
+                        />
+                      </div>
+                    ))}
+                  </div>
+                ) : (
+                  <p className="mt-2 text-xs text-muted-foreground">Collecting cache trend samples...</p>
+                )}
+              </div>
+            </CardContent>
+          </Card>
+        )}
 
         <div className="mt-4">
           <Card className="mb-4 shadow-neu-inset border-none bg-background/40 rounded-2xl animate-in fade-in slide-in-from-bottom-2 duration-500 delay-300">
@@ -1106,11 +1100,10 @@ export default function DashboardPage() {
                           title={repo.isStarred ? 'Remove from favorites' : 'Add to favorites'}
                         >
                           <Star
-                            className={`size-3.5 ${
-                              repo.isStarred
+                            className={`size-3.5 ${repo.isStarred
                                 ? 'fill-gold text-gold'
                                 : 'text-muted-foreground'
-                            } transition-all`}
+                              } transition-all`}
                           />
                         </Button>
 
@@ -1240,50 +1233,6 @@ export default function DashboardPage() {
           ) : null}
         </div>
       </section>
-
-      <section>
-        <h2 className="text-sm font-semibold text-muted-foreground uppercase tracking-wider mb-3">
-          Roadmap
-        </h2>
-        <div className="grid gap-6 sm:grid-cols-3">
-          {PHASE_ROADMAP.map(({ phase, label, status, items }, idx) => (
-            <Card 
-              key={phase} 
-              className="rounded-2xl shadow-neu-inset border-none bg-background/40 transition-all duration-500 animate-in fade-in slide-in-from-bottom-4 fill-mode-both"
-              style={{ animationDelay: `${500 + idx * 100}ms` }}
-            >
-              <CardHeader className="pb-4">
-                <div className="flex items-center justify-between">
-                  <CardTitle className="text-xs font-bold uppercase tracking-wider opacity-60">{phase}</CardTitle>
-                  <span
-                    className={`inline-flex items-center rounded-full border px-2.5 py-0.5 text-[9px] font-bold uppercase tracking-widest ${STATUS_STYLES[status]}`}
-                  >
-                    {label}
-                  </span>
-                </div>
-              </CardHeader>
-              <CardContent>
-                <ul className="flex flex-col gap-3">
-                  {items.map((item) => (
-                    <li key={item} className="flex items-center gap-3 text-xs font-medium text-foreground/70 group/item">
-                      {status === 'active' ? (
-                        <div className="flex size-5 items-center justify-center rounded-full bg-green-500/10 border border-green-500/20 shadow-sm">
-                          <GitBranch className="size-2.5 text-green-500" />
-                        </div>
-                      ) : (
-                        <div className="flex size-5 items-center justify-center rounded-full bg-muted/50 border border-border/20 shadow-sm">
-                          <Zap className="size-2.5 text-muted-foreground/40" />
-                        </div>
-                      )}
-                      <span className="group-hover/item:text-gold transition-colors">{item}</span>
-                    </li>
-                  ))}
-                </ul>
-              </CardContent>
-            </Card>
-          ))}
-        </div>
-      </section>
     </div>
   );
 }
diff --git a/client/src/features/graph/pages/ImpactPanel.jsx b/client/src/features/graph/pages/ImpactPanel.jsx
index 28f0283..9f59860 100644
--- a/client/src/features/graph/pages/ImpactPanel.jsx
+++ b/client/src/features/graph/pages/ImpactPanel.jsx
@@ -65,32 +65,49 @@ function ImpactGroup({ title, nodes, config }) {
 }
 
 export default function ImpactPanel() {
-  const graphData = useSelector(selectGraphData);
+  const graphData      = useSelector(selectGraphData);
   const selectedNodeId = useSelector(selectSelectedNodeId);
-  const jobId = graphData?.jobId;
+  const jobId          = graphData?.jobId;
 
-  const [impact, setImpact] = useState(null);
+  const [impact,  setImpact]  = useState(null);
   const [loading, setLoading] = useState(false);
-  const [error, setError] = useState('');
+  const [error,   setError]   = useState('');
 
-  const apiBase = import.meta.env.VITE_API_BASE_URL || 'http://localhost:5000';
+  // BUG 2 FIX: use VITE_API_BASE_URL consistently — never hardcode localhost
+  const apiBase = import.meta.env.VITE_API_BASE_URL || '';
 
   async function runImpact() {
     if (!jobId || !selectedNodeId) return;
 
     setLoading(true);
     setError('');
+    setImpact(null);
 
     try {
+      // BUG 2 FIX: credentials:'include' sends the httpOnly JWT cookie.
+      // Without this the request returns 401 silently on every call.
       const response = await fetch(
         `${apiBase}/api/graph/${jobId}/impact?node=${encodeURIComponent(selectedNodeId)}&hops=6`,
+        {
+          credentials: 'include',
+          headers: { 'Content-Type': 'application/json' },
+        },
       );
 
       if (!response.ok) {
-        throw new Error(await response.text());
+        // BUG 10 FIX: parse JSON error body instead of showing raw HTML via response.text()
+        let msg = `Impact analysis failed (HTTP ${response.status})`;
+        try {
+          const body = await response.json();
+          if (body?.error) msg = body.error;
+        } catch {
+          // Non-JSON response — keep the generic message above
+        }
+        throw new Error(msg);
       }
 
-      setImpact(await response.json());
+      const data = await response.json();
+      setImpact(data);
     } catch (err) {
       setError(err.message || 'Impact analysis failed.');
     } finally {
@@ -116,7 +133,7 @@ export default function ImpactPanel() {
             {selectedNodeId}
           </div>
           <Button size="sm" onClick={runImpact} disabled={loading} className="gap-2">
-            {loading ? 'Analysing...' : 'Run Impact Analysis'}
+            {loading ? 'Analysing…' : 'Run Impact Analysis'}
             <Zap className="size-3" />
           </Button>
         </>
@@ -134,10 +151,16 @@ export default function ImpactPanel() {
           <div className="mb-3 flex items-center gap-2 text-xs text-muted-foreground">
             <GitBranch className="size-3" />
             <span>{impact.totalImpacted} total nodes impacted</span>
-            <span className="ml-auto opacity-50">via {impact.source}</span>
+            {impact.source && (
+              <span className="ml-auto opacity-50">via {impact.source}</span>
+            )}
           </div>
 
-          <ImpactGroup title={SEVERITY_CONFIG.direct.label} nodes={impact.direct} config={SEVERITY_CONFIG.direct} />
+          <ImpactGroup
+            title={SEVERITY_CONFIG.direct.label}
+            nodes={impact.direct}
+            config={SEVERITY_CONFIG.direct}
+          />
           <ImpactGroup
             title={SEVERITY_CONFIG.nearTransitive.label}
             nodes={impact.nearTransitive}
diff --git a/docker-compose.yml b/docker-compose.yml
index 781ecb9..285a2e1 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -22,7 +22,9 @@ services:
       - "6379:6379"
 
   backend:
-    build: ./server
+    build:
+      context: ./server
+      dockerfile: Dockerfile
     container_name: codegraph-backend
     depends_on:
       - postgres
diff --git a/docs/codegraph-phase5-complete-bugfix-guide.docx b/docs/codegraph-phase5-complete-bugfix-guide.docx
new file mode 100644
index 0000000..576d1bf
Binary files /dev/null and b/docs/codegraph-phase5-complete-bugfix-guide.docx differ
diff --git a/docs/dynamicDb/Neo4j.md b/docs/dynamicDb/Neo4j.md
new file mode 100644
index 0000000..454e9b8
--- /dev/null
+++ b/docs/dynamicDb/Neo4j.md
@@ -0,0 +1,103 @@
+# Neo4j Migrations Guide
+
+This document explains how Neo4j migrations work in this repository and how to run them safely.
+
+Location
+- Migration runner: `server/src/infrastructure/db/migrate.js`
+- Neo4j driver: `server/src/infrastructure/db/neo4jDriver.js`
+- Migration files directory: `server/src/infrastructure/db/migrations/`
+
+Prerequisites
+- Set Neo4j connection environment variables in `server/.env` (or system env):
+  - `NEO4J_URI` (e.g. `neo4j+s://<your-instance>.databases.neo4j.io`)
+  - `NEO4J_USERNAME` (e.g. `neo4j`)
+  - `NEO4J_PASSWORD`
+- Ensure `neo4j-driver` is installed (it's listed in `server/package.json`).
+- If running inside Docker Compose, the backend container must have network access to the Neo4j host.
+
+Migration file conventions
+- Files live in `server/src/infrastructure/db/migrations/`.
+- File name format: `V001__description.cypher` (version prefix, two underscores, human description).
+- Version token is the portion before the first `__` and must be unique (e.g. `V001`, `V002`).
+- Files must contain valid Cypher statements. Multiple statements may be separated by one or more blank lines.
+- The runner will:
+  1. Create a uniqueness constraint on `:__Neo4jMigration.version` (if missing).
+  2. Read `.cypher` files sorted by filename.
+  3. Skip versions already recorded in the database.
+  4. Apply new files and record them as applied by creating `(:__Neo4jMigration { version, filename, appliedAt })` nodes.
+
+Creating a migration example
+- Path: `server/src/infrastructure/db/migrations/V001__create_constraints.cypher`
+
+Example contents:
+
+```
+CREATE CONSTRAINT IF NOT EXISTS FOR (f:CodeFile) REQUIRE (f.jobId, f.path) IS NODE KEY
+
+CREATE CONSTRAINT IF NOT EXISTS FOR (m:__Neo4jMigration) REQUIRE m.version IS UNIQUE
+```
+
+Running migrations locally (Node)
+1. From the repository root run (Esm dynamic import):
+
+```bash
+node -e "import('./server/src/infrastructure/db/migrate.js').then(m => m.runMigrations()).catch(e=>{console.error(e); process.exit(1)})"
+```
+
+2. Or create an npm script in `server/package.json` (example):
+
+```json
+"scripts": {
+  "neo4j:migrate": "node -e \"import('./src/infrastructure/db/migrate.js').then(m=>m.runMigrations())\""
+}
+```
+
+Running migrations inside Docker Compose
+- If using `docker compose` (backend service name `backend` or `codegraph-backend`), run:
+
+```bash
+# run migrations inside the backend container
+docker compose exec backend node -e "import('./src/infrastructure/db/migrate.js').then(m=>m.runMigrations()).catch(e=>{console.error(e); process.exit(1)})"
+
+# or using the built image/container name
+docker exec -it codegraph-backend node -e "import('./src/infrastructure/db/migrate.js').then(m=>m.runMigrations()).catch(e=>{console.error(e); process.exit(1)})"
+```
+
+Automatic migrations at runtime
+- The `SupervisorAgent` calls `runMigrations()` automatically when a job selects Neo4j as the repository backend. This means migrations are applied before seeding large graphs when required.
+
+Verifying applied migrations
+- Use Cypher to inspect the `__Neo4jMigration` records:
+
+```cypher
+MATCH (m:__Neo4jMigration) RETURN m.version AS version, m.filename AS file, m.appliedAt ORDER BY m.appliedAt;
+```
+
+Troubleshooting
+- **Connection failed with encryption error**: The migration runner now automatically loads `.env` via `dotenv`. Ensure environment variables are set correctly.
+- **"Comment-only statements" parsing error**: Comment lines (`//` and `/*`) are automatically filtered by the runner. No action needed.
+- Unauthorized / authentication failure: verify `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD` and network access.
+- Statement failure: the runner logs which statement failed and throws; fix the Cypher and re-run. Applied migrations are recorded; fix the failing migration file and re-run (runner will skip applied versions).
+- If you need to re-apply a migration for testing, you can delete the corresponding `__Neo4jMigration` node first (use with caution):
+
+```cypher
+MATCH (m:__Neo4jMigration { version: 'V001' }) DETACH DELETE m;
+```
+
+## Status ✅
+
+**Migration System**: OPERATIONAL
+- Environment variables properly loaded via `dotenv`
+- Comment lines automatically filtered from Cypher files
+- Schema successfully created in Neo4j Aura
+- All constraints and indexes in place
+- Integration tests passing (4/4)
+
+Best practices
+- Keep migrations small and idempotent where possible (`CREATE CONSTRAINT IF NOT EXISTS`, `MERGE` instead of `CREATE`).
+- Use explicit version prefixes and increment strictly.
+- Test Cypher statements in the Neo4j Browser or Aura Console before adding them to migration files.
+
+Change Log
+- 2026-04-29: Migrations system operational. Fixed dotenv loading in migrate.js. Added comment filtering for .cypher files. Schema successfully created with 4 constraints and 10 indexes.
+
diff --git a/docs/dynamicDb/VALIDATION.md b/docs/dynamicDb/VALIDATION.md
new file mode 100644
index 0000000..263cbcc
--- /dev/null
+++ b/docs/dynamicDb/VALIDATION.md
@@ -0,0 +1,136 @@
+# Validation Summary - Dynamic Database Switching Implementation
+
+**Date:** April 29, 2026  
+**Status:** ✅ COMPLETE AND VALIDATED
+
+## Test Results
+
+### Dynamic Database Selection Tests
+```
+✔ selectDatabase prefers Postgres for small graphs
+✔ selectDatabase switches to Neo4j for large topology signals  
+✔ selectDatabase respects manual overrides
+✔ createGraphRepository follows the selection result
+
+Tests:  4 passed (4)
+Duration: 1.29s
+```
+
+### Unit Tests (Vitest)
+```
+✓ src/agents/core/__tests__/confidence.test.js (8 tests)
+✓ src/agents/parser/__tests__/ParserAgent.test.js (1 test)
+✓ src/agents/graph/__tests__/GraphBuilderAgent.test.js (1 test)
+✓ src/agents/core/__tests__/SupervisorAgent.test.js (4 tests)
+
+Test Files:  4 passed (4)
+Tests:  14 passed (14)
+Duration: 4.49s
+```
+
+### Code Style & Formatting
+```
+✅ Prettier: All 7 modified files pass formatting check
+✅ No lint errors in backend code
+✅ No type errors
+```
+
+## Implementation Checklist
+
+### Core Changes ✅
+- [x] Database selector logic aligned with documented thresholds
+- [x] Graph topology metrics computation (relationshipTypeCount, largestCycleSize)
+- [x] Neo4j repository constructor flexibility
+- [x] Postgres connection pool configuration
+- [x] Infrastructure bootstrap probe
+
+### Files Modified (7)
+1. `server/src/infrastructure/db/dbSelector.js` - Selector logic
+2. `server/src/agents/graph/GraphBuilderAgent.js` - Topology metrics
+3. `server/src/infrastructure/db/Neo4jGraphRepository.js` - Constructor flexibility
+4. `server/src/infrastructure/connections.js` - Pool configuration
+5. `server/src/infrastructure/db/startup.js` - Bootstrap probe (NEW)
+6. `server/index.js` - Server initialization
+7. `server/test/dynamic-db-selection.test.js` - Regression tests (NEW)
+
+### Files Created (2)
+1. `server/src/infrastructure/db/startup.js` - Infrastructure bootstrap
+2. `server/test/dynamic-db-selection.test.js` - Regression test suite
+
+### Files Documented (2)
+1. `docs/dynamicDb/graph_infrastructure.md` - Architecture documentation
+2. `docs/dynamicDb/implementation.md` - Implementation report (NEW)
+
+## Key Guarantees
+
+✅ **No Breaking Changes**
+- Backward compatible with existing Postgres-only deployments
+- All persistence methods remain identical
+- Topology aliases support gradual migration
+
+✅ **Safety & Reliability**
+- Neo4j is optional, not a blocker
+- Non-blocking fallback to Postgres on Neo4j unavailability
+- Bootstrap probe catches misconfigurations at startup
+- Data never splits between stores
+
+✅ **Code Quality**
+- All tests pass
+- All code passes Prettier formatting
+- No lint errors or type errors
+- Safe parsing with Number.isFinite() guards
+
+## Decision Logic
+
+The selector uses these thresholds to choose Neo4j:
+
+| Metric | Threshold | Impact |
+|--------|-----------|--------|
+| nodeCount | ≥ 500 | Large codebases |
+| edgeCount | ≥ 2,000 | Dense graphs |
+| density | ≥ 0.05 | Highly connected modules |
+| cyclesDetected | ≥ 20 | Circular dependencies |
+| largestCycleSize | > 50 | Large cycles |
+| relationshipTypeCount | > 3 | Multiple edge types |
+| impactAnalysisDepth | > 5 | Deep impact analysis |
+
+## Deployment Notes
+
+### For Operations
+```env
+# Required (always)
+DATABASE_URL=postgres://postgres:postgres@localhost:5433/codegraph
+
+# Optional (for large repos)
+NEO4J_URI=neo4j+s://<your-instance>.databases.neo4j.io
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=your-password
+
+# Tuning (optional)
+PG_POOL_MAX=20
+```
+
+### Startup Output
+```
+[GraphInfrastructure] Postgres OK
+[GraphInfrastructure] Neo4j connected
+```
+or
+```
+[GraphInfrastructure] Postgres OK
+[GraphInfrastructure] Neo4j unavailable - falling back to Postgres
+```
+
+## What's Working
+
+1. **Automatic Selection**: Graph size automatically selects best database
+2. **Manual Overrides**: Testing can force Postgres or Neo4j if needed
+3. **Backward Compatibility**: Topology aliases support legacy code
+4. **Flexible Dependency**: Neo4j repository auto-imports pgPool if needed
+5. **Bootstrap Verification**: Infrastructure health checked at startup
+6. **Connection Pooling**: Postgres pool size configurable for production
+
+## Sign-Off
+
+All changes implemented, tested, formatted, and documented.
+Ready for production deployment.
diff --git a/docs/dynamicDb/codegraph-neo4j-setup-bugfix-guide.docx b/docs/dynamicDb/codegraph-neo4j-setup-bugfix-guide.docx
new file mode 100644
index 0000000..e934979
Binary files /dev/null and b/docs/dynamicDb/codegraph-neo4j-setup-bugfix-guide.docx differ
diff --git a/docs/dynamicDb/graph_infrastructure.md b/docs/dynamicDb/graph_infrastructure.md
new file mode 100644
index 0000000..01da0cd
--- /dev/null
+++ b/docs/dynamicDb/graph_infrastructure.md
@@ -0,0 +1,222 @@
+# Dynamic Database Switching & Graph Infrastructure
+
+## 1 — Dynamic Database Switching
+
+### 1.1 The Core Problem
+Your `GraphBuilderAgent` produces a graph in memory, then two agents persist it:
+
+- `PersistenceAgent` → PostgreSQL (always available)
+- `Neo4jGraphRepository` → Neo4j (cloud, optional)
+
+The goal is to dynamically decide when Neo4j (graph DB) should be used instead of PostgreSQL (relational DB).
+
+---
+
+### 1.2 Decision Thresholds
+
+Base the decision on metrics computed by `GraphBuilderAgent`:
+
+| Metric | Postgres Suitable | Neo4j Preferred |
+|------|------------------|----------------|
+| nodeCount | < 500 | ≥ 500 |
+| edgeCount | < 2,000 | ≥ 2,000 |
+| Graph density | < 0.05 | ≥ 0.05 |
+| cyclesDetected | < 20 | ≥ 20 |
+| Max traversal depth | ≤ 3 hops | > 3 hops |
+
+#### Hard Overrides (Always Use Neo4j)
+- Impact analysis > 5 hops
+- Circular dependency cycles > 50 nodes
+- More than 3 relationship types
+
+```js
+const density = topology.edgeCount / (topology.nodeCount * (topology.nodeCount - 1) || 1);
+```
+
+---
+
+### 1.3 Database Interface Abstraction
+
+```js
+export class IGraphRepository {
+  async persistGraph(params)              { throw new Error("Not implemented"); }
+  async getGraph(jobId)                   { throw new Error("Not implemented"); }
+  async getDependencies(jobId, path, n)   { throw new Error("Not implemented"); }
+  async getImpactedFiles(jobId, path, n)  { throw new Error("Not implemented"); }
+  async healthCheck()                     { throw new Error("Not implemented"); }
+  async deleteJob(jobId)                  { throw new Error("Not implemented"); }
+}
+```
+
+---
+
+### 1.4 Runtime Database Selection
+
+```js
+const THRESHOLDS = {
+  NODE_COUNT: 500,
+  EDGE_COUNT: 2000,
+  DENSITY: 0.05,
+  CYCLES: 20,
+};
+
+export function selectDatabase(topology, options = {}) {
+  if (options.forceNeo4j) return { db: "neo4j", reasons: ["manual override"] };
+  if (options.forcePostgres) return { db: "postgres", reasons: ["manual override"] };
+
+  const { nodeCount = 0, edgeCount = 0, cyclesDetected = 0 } = topology;
+  const density = edgeCount / (nodeCount * (nodeCount - 1) || 1);
+
+  const reasons = [];
+
+  if (nodeCount >= THRESHOLDS.NODE_COUNT) reasons.push("nodeCount");
+  if (edgeCount >= THRESHOLDS.EDGE_COUNT) reasons.push("edgeCount");
+  if (density >= THRESHOLDS.DENSITY) reasons.push("density");
+  if (cyclesDetected >= THRESHOLDS.CYCLES) reasons.push("cycles");
+
+  return { db: reasons.length ? "neo4j" : "postgres", reasons };
+}
+```
+
+---
+
+### 1.5 Factory Pattern
+
+```js
+import { selectDatabase } from "./dbSelector.js";
+import { PostgresGraphRepository } from "./PostgresGraphRepository.js";
+import { Neo4jGraphRepository } from "./Neo4jGraphRepository.js";
+import { pgPool } from "../connections.js";
+import { getNeo4jDriver } from "./neo4jDriver.js";
+
+export function createGraphRepository(topology, options = {}) {
+  const { db } = selectDatabase(topology, options);
+
+  if (db === "neo4j") {
+    return new Neo4jGraphRepository(getNeo4jDriver());
+  }
+
+  return new PostgresGraphRepository(pgPool);
+}
+```
+
+---
+
+## 2 — Neo4j Implementation (Cloud - Aura)
+
+### 2.1 Neo4j Aura Setup
+
+1. Go to https://console.neo4j.io  
+2. Create AuraDB instance (Free or Pro)  
+3. Download credentials  
+4. Add to `.env`
+
+```env
+NEO4J_URI=neo4j+s://<your-instance>.databases.neo4j.io
+NEO4J_USER=neo4j
+NEO4J_PASSWORD=your-password
+```
+
+---
+
+### 2.2 Singleton Driver Pattern
+
+```js
+import neo4j from "neo4j-driver";
+let _driver = null;
+
+export function getNeo4jDriver() {
+  if (_driver) return _driver;
+
+  _driver = neo4j.driver(
+    process.env.NEO4J_URI,
+    neo4j.auth.basic(process.env.NEO4J_USER, process.env.NEO4J_PASSWORD),
+    {
+      maxConnectionPoolSize: 50,
+      connectionTimeout: 10000,
+    }
+  );
+
+  return _driver;
+}
+```
+
+---
+
+## 3 — PostgreSQL (Local / Docker Only)
+
+### 3.1 Environment Configuration
+
+```env
+DATABASE_URL=postgres://postgres:postgres@localhost:5433/codegraph
+PG_POOL_MAX=10
+```
+
+---
+
+### 3.2 PostgreSQL Connection
+
+```js
+import { Pool } from "pg";
+
+export const pgPool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: parseInt(process.env.PG_POOL_MAX ?? "10", 10),
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 10000,
+});
+```
+
+---
+
+### 3.3 Docker Setup
+
+```yaml
+version: "3.9"
+
+services:
+  postgres:
+    image: ankane/pgvector:latest
+    ports:
+      - "5433:5432"
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: codegraph
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+
+  backend:
+    build: ./server
+    depends_on:
+      - postgres
+      - redis
+    environment:
+      DATABASE_URL: postgres://postgres:postgres@postgres:5432/codegraph
+    command: sh -c "npm run migrate && npm run dev"
+```
+
+---
+
+## 4 — Startup Logic
+
+```js
+async function startServer() {
+  await pgPool.query("SELECT 1");
+  console.log("Postgres OK");
+
+  if (process.env.NEO4J_URI) {
+    try {
+      await getNeo4jDriver().verifyConnectivity();
+      console.log("Neo4j Aura connected");
+    } catch {
+      console.warn("Neo4j unavailable — fallback to Postgres");
+    }
+  }
+
+  app.listen(PORT);
+}
+```
diff --git a/docs/dynamicDb/implementation.md b/docs/dynamicDb/implementation.md
new file mode 100644
index 0000000..53ec4b2
--- /dev/null
+++ b/docs/dynamicDb/implementation.md
@@ -0,0 +1,293 @@
+# Dynamic Database Switching - Implementation Report
+
+**Date:** April 29, 2026
+
+## Overview
+
+Implemented dynamic graph storage selection logic that automatically routes analysis job graphs to either PostgreSQL (relational) or Neo4j (graph) based on topology metrics. This allows the system to handle both small and large codebases efficiently without requiring manual configuration per job.
+
+---
+
+## Changes Summary
+
+### 1. Database Selector Logic ([dbSelector.js](../../server/src/infrastructure/db/dbSelector.js))
+
+**What Changed:**
+- Aligned selector with documented thresholds from [graph_infrastructure.md](graph_infrastructure.md)
+- Added three new threshold constants: `IMPACT_HOPS: 5`, `LARGE_CYCLE_SIZE: 50`, `RELATIONSHIP_TYPES: 3`
+- Removed hard environment check (`NEO4J_URI/PASSWORD`) so Neo4j is optional, not a blocker
+- Changed reason strings to be machine-readable tokens (`'nodeCount'`, `'edgeCount'`, etc.) instead of verbose messages
+- Added support for backward-compatible topology field aliases (`distinctRelationshipTypes`, `maxCycleSize`)
+
+**Why:**
+- Makes Neo4j truly optional—Postgres works even if Neo4j is not configured
+- Decisions are now pure data-driven: topology metrics → boolean → repository type
+- Standardized reason format for logging and observability
+
+**Formula:**
+```js
+const density = edgeCount / (nodeCount * (nodeCount - 1) || 1);
+```
+
+**Decision Table:**
+| Signal | Postgres | Neo4j |
+|--------|----------|-------|
+| `nodeCount` | < 500 | ≥ 500 |
+| `edgeCount` | < 2,000 | ≥ 2,000 |
+| `density` | < 0.05 | ≥ 0.05 |
+| `cyclesDetected` | < 20 | ≥ 20 |
+| `largestCycleSize` | ≤ 50 | > 50 |
+| `relationshipTypeCount` | ≤ 3 | > 3 |
+| `impactAnalysisDepth` | ≤ 5 | > 5 |
+
+---
+
+### 2. Graph Topology Metrics ([GraphBuilderAgent.js](../../server/src/agents/graph/GraphBuilderAgent.js#L199))
+
+**What Changed:**
+- Added computation of `relationshipTypeCount` (distinct edge types in the graph)
+- Added computation of `largestCycleSize` (size of the largest strongly connected component)
+- Exported both as primary names and backward-compatible aliases
+
+**Output Shape:**
+```js
+const topology = {
+  nodeCount,
+  edgeCount,
+  cyclesDetected,
+  cycles,
+  relationshipTypeCount,
+  distinctRelationshipTypes: relationshipTypeCount,  // alias
+  largestCycleSize,
+  maxCycleSize: largestCycleSize,  // alias
+  // ... existing fields ...
+};
+```
+
+**Why:**
+- Enables precise Neo4j/Postgres routing decisions based on actual graph complexity
+- Aliases allow gradual migration of downstream consumers
+
+---
+
+### 3. Graph Repository Flexibility ([Neo4jGraphRepository.js](../../server/src/infrastructure/db/Neo4jGraphRepository.js#L28))
+
+**What Changed:**
+- Constructor now accepts both a driver instance or an options object
+- Defaults to importing `pgPool` from connections if not provided
+- Maintains backward compatibility with existing call sites
+
+**Constructor Signatures:**
+```js
+// Old style (still works)
+new Neo4jGraphRepository({ driver, pgPool })
+
+// New style (more flexible)
+new Neo4jGraphRepository(driver)
+```
+
+**Why:**
+- Simplifies testing and dependency injection
+- Allows the factory to pass just the driver without reimporting pgPool
+
+---
+
+### 4. Connection Pool Configuration ([connections.js](../../server/src/infrastructure/connections.js#L4))
+
+**What Changed:**
+- Made pool size configurable via `PG_POOL_MAX` environment variable
+- Added `connectionTimeoutMillis: 10000` to prevent indefinite hangs
+- Used safe parsing: `Number.isFinite(pgPoolMax) ? pgPoolMax : 10`
+
+**Config:**
+```env
+PG_POOL_MAX=10
+DATABASE_URL=postgres://postgres:postgres@localhost:5433/codegraph
+```
+
+**Why:**
+- Production deployments can tune pool size for their workload
+- Connection timeout prevents zombie connections from accumulating
+
+---
+
+### 5. Startup Probe ([startup.js](../../server/src/infrastructure/db/startup.js))
+
+**What Changed:**
+- Created new `bootstrapGraphInfrastructure()` async function
+- Probes Postgres connectivity at startup (required)
+- Probes Neo4j connectivity at startup (optional, non-blocking)
+- Logs connectivity status and fallback behavior
+
+**Behavior:**
+```js
+await bootstrapGraphInfrastructure();
+// Logs:
+// [GraphInfrastructure] Postgres OK
+// [GraphInfrastructure] Neo4j connected  OR
+// [GraphInfrastructure] Neo4j unavailable - falling back to Postgres
+```
+
+**Why:**
+- Catches infrastructure misconfigurations at boot time
+- Provides clear diagnostic messages for deployment troubleshooting
+- Non-blocking fallback means deployments don't fail if Neo4j is down
+
+---
+
+### 6. Server Initialization ([index.js](../../server/index.js#L27))
+
+**What Changed:**
+- Added import of `bootstrapGraphInfrastructure`
+- Await bootstrap probe before starting worker or listening
+
+**Sequence:**
+```js
+await bootstrapGraphInfrastructure();  // Check databases
+startAnalysisWorker();                  // Start async work processor
+startCacheMetricsPersistence();         // Start cache housekeeping
+app.listen(PORT);                       // Start HTTP server
+```
+
+**Why:**
+- Infrastructure failures are caught before the server starts accepting traffic
+- Provides observability into connection state at startup
+
+---
+
+## Testing
+
+### Regression Test Suite ([dynamic-db-selection.test.js](../../server/test/dynamic-db-selection.test.js))
+
+Four test cases cover the selector behavior:
+
+1. **Small graph → Postgres**
+   - nodeCount: 10, edgeCount: 1 → selects Postgres
+   - reason: all thresholds below trigger point
+
+2. **Large graph → Neo4j**
+   - nodeCount: 500, edgeCount: 12,475, density: 0.05+, cyclesDetected: 20, largestCycleSize: 51, relationshipTypeCount: 4
+   - reason: every threshold triggers
+   - verifies all seven decision signals work together
+
+3. **Manual overrides**
+   - `forcePostgres: true` overrides any large topology
+   - `forceNeo4j: true` overrides any small topology
+
+4. **Factory integration**
+   - Small topology → PostgresGraphRepository instance
+   - Large topology → Neo4jGraphRepository instance
+
+**Status:** All 4 tests pass ✅
+
+---
+
+## Migration Path
+
+### For Existing Codebases
+
+No action needed. The system automatically selects the right backend:
+- Existing small repos use Postgres (faster, simpler)
+- Large repos added in the future use Neo4j (better for deep traversals)
+
+### For Operations/Deployment
+
+1. **Keep Neo4j Optional:**
+   ```env
+   # Minimal: Postgres only
+   DATABASE_URL=postgres://...
+   # Optional: add Neo4j for large repos
+   NEO4J_URI=neo4j+s://...
+   NEO4J_USER=neo4j
+   NEO4J_PASSWORD=...
+   ```
+
+2. **Monitor Connectivity:**
+   - Check logs for `[GraphInfrastructure]` messages at startup
+   - Confirm either "Postgres OK" or "Neo4j connected"
+   - If "Neo4j unavailable", system gracefully falls back to Postgres
+
+3. **Tune Pool Size (Optional):**
+   ```env
+   PG_POOL_MAX=20  # for high-concurrency deployments
+   ```
+
+---
+
+## Implementation Safety Guarantees
+
+1. **No Breaking Changes**
+   - Existing Postgres-only deployments work unchanged
+   - SupervisorAgent still receives `createGraphRepository(topology, options)` from the same call site
+   - All persistence methods remain identical
+
+2. **Backward Compatibility**
+   - Topology payload includes field aliases (`distinctRelationshipTypes`, `maxCycleSize`)
+   - Neo4j constructor accepts both driver and options object
+   - Reason array maintains previous semantic meaning
+
+3. **Optional Features**
+   - Neo4j unavailability is logged but not fatal
+   - Postgres always available and used as fallback
+   - Manual overrides available for testing and special cases
+
+4. **Data Consistency**
+   - Neo4jGraphRepository always writes Postgres first (atomic fallback)
+   - Graph and metadata never split between stores
+   - shareToken, job status, and analytics remain in Postgres always
+
+---
+
+## Code Locations
+
+| File | Purpose |
+|------|---------|
+| [dbSelector.js](../../server/src/infrastructure/db/dbSelector.js) | Threshold-based database selection |
+| [graphRepositoryFactory.js](../../server/src/infrastructure/db/graphRepositoryFactory.js) | Factory pattern for repository creation |
+| [GraphBuilderAgent.js](../../server/src/agents/graph/GraphBuilderAgent.js#L199) | Topology metric computation |
+| [Neo4jGraphRepository.js](../../server/src/infrastructure/db/Neo4jGraphRepository.js) | Neo4j persistence implementation |
+| [PostgresGraphRepository.js](../../server/src/infrastructure/db/PostgresGraphRepository.js) | Postgres persistence (unchanged) |
+| [connections.js](../../server/src/infrastructure/connections.js) | Connection pool configuration |
+| [startup.js](../../server/src/infrastructure/db/startup.js) | Infrastructure bootstrap probe |
+| [index.js](../../server/index.js) | Server entry point (bootstrap integration) |
+| [dynamic-db-selection.test.js](../../server/test/dynamic-db-selection.test.js) | Regression tests |
+
+---
+
+## Validation
+
+### Unit Tests
+```bash
+npm run test dynamic-db-selection.test.js
+# Result: ✔ 4/4 tests pass
+```
+
+### Type Checking
+All files pass ESLint and have no type errors.
+
+### Integration
+- Selector logic matches documented decision table exactly
+- Topology metrics computed in GraphBuilder
+- Factory creates correct repository type based on selection
+- Bootstrap probe runs at startup and logs results
+
+---
+
+## Future Enhancements
+
+1. **Observability:**
+   - Add Prometheus metrics: `graph_repository_selection_total{type=["postgres","neo4j"]}`
+   - Track repository type per job in analysis_jobs table
+
+2. **Dynamic Adjustment:**
+   - Allow mid-job repository migration if topology changes during enrichment
+   - Implement read-from-cache / write-to-new pattern for zero-downtime transitions
+
+3. **Cost Optimization:**
+   - Lower density threshold if Neo4j is billed per query
+   - Implement Neo4j connection pooling per request for shared instances
+
+4. **Advanced Heuristics:**
+   - Consider file count and language mix in decision
+   - Account for historical query latencies per repository
+   - Implement A/B testing for threshold tuning
diff --git a/neo4j-docker.yml b/neo4j-docker.yml
new file mode 100644
index 0000000..597c473
--- /dev/null
+++ b/neo4j-docker.yml
@@ -0,0 +1,103 @@
+# docker-compose.yml
+# Optional FIX: Neo4j service added. Previously missing, causing local full-stack
+# start to fail for any job that triggers the Neo4j threshold.
+
+services:
+
+  # ── PostgreSQL with pgvector ──────────────────────────────────────────────
+  postgres:
+    image: ankane/pgvector
+    container_name: codegraph-postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER:     postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB:       codegraph
+    ports:
+      - "5433:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d codegraph"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  # ── Redis ─────────────────────────────────────────────────────────────────
+  redis:
+    image: redis:7
+    container_name: codegraph-redis
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  # ── Neo4j Community Edition ───────────────────────────────────────────────
+  # Browser UI:    http://localhost:7474  (login: neo4j / devpassword)
+  # Bolt protocol: bolt://localhost:7687  (used by the driver)
+  neo4j:
+    image: neo4j:5.20-community
+    container_name: codegraph-neo4j
+    restart: unless-stopped
+    ports:
+      - "7474:7474"   # Browser UI
+      - "7687:7687"   # Bolt protocol
+    environment:
+      # Format: neo4j/<password>  — override NEO4J_PASSWORD in your .env
+      NEO4J_AUTH: neo4j/${NEO4J_PASSWORD:-devpassword}
+      # Memory tuning — adjust for your machine (heap = 25-50% of RAM)
+      NEO4J_server_memory_heap_initial__size: "512m"
+      NEO4J_server_memory_heap_max__size:     "1G"
+      NEO4J_server_memory_pagecache__size:    "512m"
+      # Increase transaction timeout for large graph seeds
+      NEO4J_db_transaction_timeout:           "60s"
+    volumes:
+      - neo4jdata:/data
+      - neo4jlogs:/logs
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:7474"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+
+  # ── Backend ───────────────────────────────────────────────────────────────
+  backend:
+    build:
+      context: ./server
+      dockerfile: Dockerfile
+    container_name: codegraph-backend
+    restart: unless-stopped
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      neo4j:
+        condition: service_healthy   # BUG 13 FIX: wait for Neo4j to be ready
+    environment:
+      DATABASE_URL:    postgres://postgres:postgres@postgres:5432/codegraph
+      REDIS_URL:       redis://redis:6379
+      # Neo4j — uses the internal Docker network hostname "neo4j"
+      NEO4J_URI:       bolt://neo4j:7687
+      NEO4J_USERNAME:  neo4j
+      NEO4J_PASSWORD:  ${NEO4J_PASSWORD:-devpassword}
+    ports:
+      - "5000:5000"
+    volumes:
+      - ./server:/app
+      - /app/node_modules
+    command: >
+      sh -c "
+        until pg_isready -h postgres -p 5432; do sleep 1; done;
+        npm run migrate;
+        npm run dev
+      "
+
+volumes:
+  pgdata:
+  neo4jdata:
+  neo4jlogs:
\ No newline at end of file
diff --git a/server/.env.example b/server/.env.example
index 2c37b2b..9285f55 100644
--- a/server/.env.example
+++ b/server/.env.example
@@ -97,11 +97,35 @@ ENRICHMENT_CONCURRENCY=4
 CONTRACT_CONCURRENCY=3
 GRAPH_CACHE_TTL_SECONDS=300
 
+# ===============================
+# Database - PostgreSQL
+# ===============================
 DATABASE_URL=postgres://postgres:postgres@localhost:5432/polyglot
+PG_POOL_MAX=10
 
-NEO4J_URI=bolt://localhost:7687
-NEO4J_USER=neo4j
+# ===============================
+# Database - Neo4j (Optional)
+# ===============================
+# Neo4j is optional. Leave commented out for Postgres-only deployments.
+# For cloud Neo4j Aura, get credentials from https://console.neo4j.io
+NEO4J_URI=neo4j+s://<your-instance>.databases.neo4j.io
+NEO4J_USERNAME=neo4j
 NEO4J_PASSWORD=your_neo4j_password
+NEO4J_DATABASE=<your-id>
+AURA_INSTANCEID=<your-id>
+AURA_INSTANCENAME=CodeGraph
+
+# This is for local docker setup (Optional)
+# NEO4J_URI=bolt://localhost:7687
+# NEO4J_USERNAME=neo4j
+# NEO4J_PASSWORD=your_neo4j_password
+
+# Neo4j Selection Thresholds (Graph Topology)
+# If any threshold is met, the system switches from Postgres to Neo4j.
+NEO4J_THRESHOLD_NODES=500
+NEO4J_THRESHOLD_EDGES=2000
+NEO4J_THRESHOLD_DENSITY=0.05
+NEO4J_THRESHOLD_CYCLES=20
 
 # ===============================
 # Observability (Sentry)
diff --git a/server/app.js b/server/app.js
index ae7d42e..7036046 100644
--- a/server/app.js
+++ b/server/app.js
@@ -20,6 +20,8 @@ import prCommentRouter                       from './src/api/webhooks/pr-comment
 import { requestLogger }  from './src/utils/logger.js';
 import { notFound }       from './src/middleware/notFound.middleware.js';
 import { errorHandler }   from './src/middleware/errorHandler.middleware.js';
+import { pgPool, redisClient } from './src/infrastructure/connections.js';
+import { createChatClient } from './src/services/ai/llmProvider.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname  = path.dirname(__filename);
@@ -45,7 +47,26 @@ app.use(requestLogger);
 app.use(passport.initialize());
 configureGitHubPassport();
 
-app.get('/health', (_req, res) => res.json({ status: 'ok' }));
+app.get('/health', async (_req, res) => {
+  const checks = {};
+  try { await pgPool.query('SELECT 1'); checks.postgres = 'ok'; }
+  catch { checks.postgres = 'error'; }
+
+  try { await redisClient.ping(); checks.redis = 'ok'; }
+  catch { checks.redis = 'unavailable'; }
+
+  if (process.env.NEO4J_URI) {
+    try {
+      const { getNeo4jDriver } = await import('./src/infrastructure/db/neo4jDriver.js');
+      await getNeo4jDriver().verifyConnectivity(); checks.neo4j = 'ok';
+    } catch { checks.neo4j = 'unavailable'; }
+  } else { checks.neo4j = 'disabled'; }
+
+  checks.aiProvider = createChatClient().isConfigured() ? 'configured' : 'not configured';
+
+  const allOk = checks.postgres === 'ok';
+  return res.status(allOk ? 200 : 503).json({ status: allOk ? 'ok' : 'degraded', checks });
+});
 
 app.use('/api/auth', authRouter);
 
diff --git a/server/index.js b/server/index.js
index 5040dc5..cd7b74f 100644
--- a/server/index.js
+++ b/server/index.js
@@ -4,16 +4,19 @@ import { fileURLToPath } from 'url';
 import * as Sentry from '@sentry/node';
 import { startAnalysisWorker } from './src/queue/analysisQueue.js';
 import { startCacheMetricsPersistence } from './src/infrastructure/cache.js';
+import { bootstrapGraphInfrastructure } from './src/infrastructure/db/startup.js';
+import { pgPool, redisClient } from './src/infrastructure/connections.js';
+import { closeNeo4jDriver } from './src/infrastructure/db/neo4jDriver.js'; // BUG FIX
 
 const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+const __dirname  = path.dirname(__filename);
 
 dotenv.config({ path: path.join(__dirname, '.env') });
 
 if (process.env.SENTRY_DSN) {
   Sentry.init({
-    dsn: process.env.SENTRY_DSN,
-    environment: process.env.NODE_ENV || 'development',
+    dsn:              process.env.SENTRY_DSN,
+    environment:      process.env.NODE_ENV || 'development',
     tracesSampleRate: Number(process.env.SENTRY_TRACES_SAMPLE_RATE || 0.1),
   });
 }
@@ -22,9 +25,43 @@ const { default: app } = await import('./app.js');
 
 const PORT = process.env.PORT || 5000;
 
+// ── Graceful shutdown ─────────────────────────────────────────────────────
+// BUG FIX: Neo4j driver must be closed on SIGTERM/SIGINT to avoid
+// connection pool leaks. All three resources close in parallel.
+
+let isShuttingDown = false;
+
+async function shutdown(signal) {
+  if (isShuttingDown) return;
+  isShuttingDown = true;
+
+  console.log(`[Shutdown] Received ${signal} — closing connections gracefully...`);
+
+  await Promise.allSettled([
+    pgPool.end().then(() => console.log('[Shutdown] Postgres pool closed')),
+    redisClient.quit().then(() => console.log('[Shutdown] Redis client closed')),
+    closeNeo4jDriver().then(() => console.log('[Shutdown] Neo4j driver closed')),
+  ]);
+
+  console.log('[Shutdown] Done.');
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT',  () => shutdown('SIGINT'));
+
+// ── Startup ───────────────────────────────────────────────────────────────
+// bootstrapGraphInfrastructure():
+//   1. Verifies Postgres connectivity (fatal if down)
+//   2. Verifies Neo4j connectivity (non-fatal — falls back to Postgres)
+//   3. Runs Neo4j migrations at startup (BUG 8 FIX — not inside per-job pipeline)
+await bootstrapGraphInfrastructure();
+
 startAnalysisWorker();
 startCacheMetricsPersistence();
 
 app.listen(PORT, () => {
-  console.log(`[server] Running on http://localhost:${PORT} (${process.env.NODE_ENV || 'development'})`);
+  console.log(
+    `[Server] Running on http://localhost:${PORT} (${process.env.NODE_ENV || 'development'})`,
+  );
 });
diff --git a/server/package-lock.json b/server/package-lock.json
index 8026669..c6d3ef2 100644
--- a/server/package-lock.json
+++ b/server/package-lock.json
@@ -23,7 +23,7 @@
         "express-rate-limit": "^7.1.5",
         "ioredis": "^5.10.1",
         "jsonwebtoken": "^9.0.3",
-        "neo4j-driver": "^5.28.1",
+        "neo4j-driver": "^5.28.3",
         "openai": "^6.33.0",
         "p-limit": "^5.0.0",
         "passport": "^0.7.0",
@@ -36,6 +36,7 @@
       },
       "devDependencies": {
         "@vitest/coverage-v8": "^4.0.8",
+        "dotenv-cli": "^11.0.0",
         "eslint": "^9.39.2",
         "nodemon": "^3.1.11",
         "prettier": "^3.7.4",
@@ -131,6 +132,7 @@
       "dev": true,
       "license": "MIT",
       "optional": true,
+      "peer": true,
       "dependencies": {
         "tslib": "^2.4.0"
       }
@@ -608,7 +610,6 @@
       "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.1.tgz",
       "integrity": "sha512-gLyJlPHPZYdAk1JENA9LeHejZe1Ti77/pTeFm/nMXmQH/HFZlcS/O2XJB+L8fkbrNSqhdtlvjBVjxwUYanNH5Q==",
       "license": "Apache-2.0",
-      "peer": true,
       "engines": {
         "node": ">=8.0.0"
       }
@@ -630,7 +631,6 @@
       "resolved": "https://registry.npmjs.org/@opentelemetry/context-async-hooks/-/context-async-hooks-2.6.1.tgz",
       "integrity": "sha512-XHzhwRNkBpeP8Fs/qjGrAf9r9PRv67wkJQ/7ZPaBQQ68DYlTBBx5MF9LvPx7mhuXcDessKK2b+DcxqwpgkcivQ==",
       "license": "Apache-2.0",
-      "peer": true,
       "engines": {
         "node": "^18.19.0 || >=20.6.0"
       },
@@ -643,7 +643,6 @@
       "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-2.6.1.tgz",
       "integrity": "sha512-8xHSGWpJP9wBxgBpnqGL0R3PbdWQndL1Qp50qrg71+B28zK5OQmUgcDKLJgzyAAV38t4tOyLMGDD60LneR5W8g==",
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "@opentelemetry/semantic-conventions": "^1.29.0"
       },
@@ -1052,7 +1051,6 @@
       "resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-2.6.1.tgz",
       "integrity": "sha512-lID/vxSuKWXM55XhAKNoYXu9Cutoq5hFdkbTdI/zDKQktXzcWBVhNsOkiZFTMU9UtEWuGRNe0HUgmsFldIdxVA==",
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "@opentelemetry/core": "2.6.1",
         "@opentelemetry/semantic-conventions": "^1.29.0"
@@ -1069,7 +1067,6 @@
       "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace-base/-/sdk-trace-base-2.6.1.tgz",
       "integrity": "sha512-r86ut4T1e8vNwB35CqCcKd45yzqH6/6Wzvpk2/cZB8PsPLlZFTvrh8yfOS3CYZYcUmAx4hHTZJ8AO8Dj8nrdhw==",
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "@opentelemetry/core": "2.6.1",
         "@opentelemetry/resources": "2.6.1",
@@ -1087,7 +1084,6 @@
       "resolved": "https://registry.npmjs.org/@opentelemetry/semantic-conventions/-/semantic-conventions-1.40.0.tgz",
       "integrity": "sha512-cifvXDhcqMwwTlTK04GBNeIe7yyo28Mfby85QXFe1Yk8nmi36Ab/5UQwptOx84SsoGNRg+EVSjwzfSZMy6pmlw==",
       "license": "Apache-2.0",
-      "peer": true,
       "engines": {
         "node": ">=14"
       }
@@ -1894,7 +1890,6 @@
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -2558,6 +2553,51 @@
         "url": "https://dotenvx.com"
       }
     },
+    "node_modules/dotenv-cli": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/dotenv-cli/-/dotenv-cli-11.0.0.tgz",
+      "integrity": "sha512-r5pA8idbk7GFWuHEU7trSTflWcdBpQEK+Aw17UrSHjS6CReuhrrPcyC3zcQBPQvhArRHnBo/h6eLH1fkCvNlww==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cross-spawn": "^7.0.6",
+        "dotenv": "^17.1.0",
+        "dotenv-expand": "^12.0.0",
+        "minimist": "^1.2.6"
+      },
+      "bin": {
+        "dotenv": "cli.js"
+      }
+    },
+    "node_modules/dotenv-expand": {
+      "version": "12.0.3",
+      "resolved": "https://registry.npmjs.org/dotenv-expand/-/dotenv-expand-12.0.3.tgz",
+      "integrity": "sha512-uc47g4b+4k/M/SeaW1y4OApx+mtLWl92l5LMPP0GNXctZqELk+YGgOPIIC5elYmUH4OuoK3JLhuRUYegeySiFA==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "dotenv": "^16.4.5"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://dotenvx.com"
+      }
+    },
+    "node_modules/dotenv-expand/node_modules/dotenv": {
+      "version": "16.6.1",
+      "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz",
+      "integrity": "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://dotenvx.com"
+      }
+    },
     "node_modules/dunder-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz",
@@ -4153,6 +4193,16 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "node_modules/minimist": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
+      "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
     "node_modules/module-details-from-path": {
       "version": "1.0.4",
       "resolved": "https://registry.npmjs.org/module-details-from-path/-/module-details-from-path-1.0.4.tgz",
@@ -4656,7 +4706,6 @@
       "resolved": "https://registry.npmjs.org/pg/-/pg-8.20.0.tgz",
       "integrity": "sha512-ldhMxz2r8fl/6QkXnBD3CR9/xg694oT6DZQ2s6c/RI28OjtSOpxnPrUCGOBJ46RCUxcWdx3p6kw/xnDHjKvaRA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "pg-connection-string": "^2.12.0",
         "pg-pool": "^3.13.0",
@@ -5449,7 +5498,6 @@
       "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -5707,7 +5755,6 @@
       "integrity": "sha512-xjR1dMTVHlFLh98JE3i/f/WePqJsah4A0FK9cc8Ehp9Udk0AZk6ccpIZhh1qJ/yxVWRZ+Q54ocnD8TXmkhspGg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@vitest/expect": "4.1.2",
         "@vitest/mocker": "4.1.2",
diff --git a/server/package.json b/server/package.json
index ff843d3..c48fc50 100644
--- a/server/package.json
+++ b/server/package.json
@@ -9,12 +9,13 @@
   "scripts": {
     "start": "node index.js",
     "dev": "nodemon index.js",
-    "migrate": "psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/001_initial.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/002_function_nodes.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/003_share_tokens.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/004_analysis_jobs_metadata.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/005_polyglot_statuses.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/006_contracts.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/007_hot_query_indexes.sql",
+    "migrate": "psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/001_initial.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/002_function_nodes.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/003_share_tokens.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/004_analysis_jobs_metadata.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/005_polyglot_statuses.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/006_contracts.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/007_hot_query_indexes.sql && psql \"$DATABASE_URL\" -v ON_ERROR_STOP=1 -f ./src/infrastructure/migrations/008_db_type_column.sql",
     "db:migrate": "npm run migrate",
     "test": "node --test test/cache.metrics.test.js test/cacheMetricsPersistence.test.js test/repositories.cache-metrics.test.js test/ai.queries.test.js test/ai.snippet-impact.test.js test/ai.suggest-refactor.test.js test/graph.heatmap.test.js test/jobs.stream.auth.test.js test/github.webhook.test.js test/parser.multilang.test.js test/pr-comment.test.js test/snippet.analyzer.confidence.test.js",
     "test:ai-queries": "node --test test/ai.queries.test.js",
     "test:unit": "vitest run --configLoader native --pool threads",
-    "test:coverage": "vitest run --coverage --configLoader native --pool threads"
+    "test:coverage": "vitest run --coverage --configLoader native --pool threads",
+    "neo4j:migrate": "node -e \"import('./src/infrastructure/db/migrate.js').then(m=>m.runMigrations()).catch(e=>{console.error(e); process.exit(1)})\""
   },
   "dependencies": {
     "@babel/parser": "^7.23.6",
@@ -31,7 +32,7 @@
     "express-rate-limit": "^7.1.5",
     "ioredis": "^5.10.1",
     "jsonwebtoken": "^9.0.3",
-    "neo4j-driver": "^5.28.1",
+    "neo4j-driver": "^5.28.3",
     "openai": "^6.33.0",
     "p-limit": "^5.0.0",
     "passport": "^0.7.0",
@@ -44,6 +45,7 @@
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.8",
+    "dotenv-cli": "^11.0.0",
     "eslint": "^9.39.2",
     "nodemon": "^3.1.11",
     "prettier": "^3.7.4",
diff --git a/server/src/agents/analysis/ImpactAnalysisAgent.js b/server/src/agents/analysis/ImpactAnalysisAgent.js
index 3060e94..d18d8b3 100644
--- a/server/src/agents/analysis/ImpactAnalysisAgent.js
+++ b/server/src/agents/analysis/ImpactAnalysisAgent.js
@@ -1,79 +1,86 @@
-import neo4j from 'neo4j-driver';
+/**
+ * ImpactAnalysisAgent
+ * Finds all files that are impacted (i.e., depend on) a changed file.
+ *
+ * FIXES applied:
+ *  Bug 1 — env var: NEO4J_USER → NEO4J_USERNAME
+ *  Bug 2 — uses singleton getNeo4jDriver(), never calls driver.close()
+ *  Bug 3 — BFS direction fixed: inbound (impacted → start) not outbound
+ *  Bug 4 — relationship type scoped to [:IMPORTS] only, not wildcard [*]
+ *  Bug 11 — reads db_type from analysis_jobs to skip unnecessary Neo4j attempts
+ */
+
 import { pgPool } from '../../infrastructure/connections.js';
+import { getNeo4jDriver } from '../../infrastructure/db/neo4jDriver.js'; // BUG 2 FIX: singleton
 import { BaseAgent } from '../core/BaseAgent.js';
 import { scoreAnalysis } from '../core/confidence.js';
 
 const MAX_HOPS = 6;
 
-function getNeo4jDriver() {
-  const uri = process.env.NEO4J_URI || 'bolt://localhost:7687';
-  const user = process.env.NEO4J_USER || 'neo4j';
-  const pass = process.env.NEO4J_PASSWORD || 'neo4j';
-  return neo4j.driver(uri, neo4j.auth.basic(user, pass));
-}
-
 function toNumber(value, fallback = 0) {
-  if (typeof value === 'number' && Number.isFinite(value)) {
-    return value;
-  }
-
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
   if (typeof value?.toNumber === 'function') {
     try {
-      const converted = value.toNumber();
-      return Number.isFinite(converted) ? converted : fallback;
+      const n = value.toNumber();
+      return Number.isFinite(n) ? n : fallback;
     } catch {
       return fallback;
     }
   }
-
   return fallback;
 }
 
+/**
+ * Inbound BFS via Cypher.
+ *
+ * BUG 3 FIX: direction is now (impacted)-[:IMPORTS*]->(start), not (start)-[*]->(impacted).
+ * BUG 4 FIX: relationship type is [:IMPORTS], not wildcard [*].
+ * BUG 2 FIX: uses module singleton driver — never closes the driver.
+ */
 async function bfsNeo4j(jobId, startNode, maxHops) {
-  const driver = getNeo4jDriver();
+  const driver = getNeo4jDriver(); // BUG 2 FIX: singleton from module
   const session = driver.session();
 
   try {
     const result = await session.run(
-      `
-      MATCH path = (start { jobId: $jobId, path: $startNode })-[*1..${maxHops}]->(impacted)
-      WHERE impacted.jobId = $jobId
-      RETURN
-        impacted.path AS path,
-        length(path) AS depth,
-        labels(impacted)[0] AS nodeType
-      ORDER BY depth ASC
-      `,
+      // BUG 3+4 FIX: inbound IMPORTS traversal only
+      `MATCH path = (impacted:CodeFile { jobId: $jobId })
+                    -[:IMPORTS*1..${maxHops}]->
+                    (start:CodeFile { jobId: $jobId, path: $startNode })
+       RETURN DISTINCT
+         impacted.path       AS path,
+         length(path)        AS depth,
+         labels(impacted)[0] AS nodeType
+       ORDER BY depth ASC`,
       { jobId, startNode },
     );
 
-    const nodes = [];
-    for (const record of result.records) {
-      nodes.push({
-        path: String(record.get('path') || ''),
-        depth: toNumber(record.get('depth'), 0),
-        nodeType: String(record.get('nodeType') || 'Node'),
-      });
-    }
+    const nodes = result.records.map((record) => ({
+      path:     String(record.get('path') || ''),
+      depth:    toNumber(record.get('depth'), 0),
+      nodeType: String(record.get('nodeType') || 'CodeFile'),
+    }));
 
     return { nodes, source: 'neo4j' };
   } finally {
-    await session.close();
-    await driver.close();
+    await session.close(); // BUG 2 FIX: close session only, NOT driver
   }
 }
 
+/**
+ * Inbound BFS via Postgres adjacency table.
+ * Loads all edges once and traverses in-memory — suitable for repos ≤ 500 files.
+ */
 async function bfsPostgres(jobId, startNode, maxHops) {
   const edgeResult = await pgPool.query(
     'SELECT source_path, target_path FROM graph_edges WHERE job_id = $1',
     [jobId],
   );
 
+  // Reverse map: target → [sources that import it]
   const reverseMap = new Map();
   for (const row of edgeResult.rows) {
-    if (!reverseMap.has(row.target_path)) {
-      reverseMap.set(row.target_path, []);
-    }
+    if (!reverseMap.has(row.target_path)) reverseMap.set(row.target_path, []);
     reverseMap.get(row.target_path).push(row.source_path);
   }
 
@@ -85,30 +92,39 @@ async function bfsPostgres(jobId, startNode, maxHops) {
   while (current.length > 0 && depth < maxHops) {
     depth += 1;
     const next = [];
-
     for (const node of current) {
       for (const dep of reverseMap.get(node) || []) {
-        if (visited.has(dep)) {
-          continue;
-        }
-
+        if (visited.has(dep)) continue;
         visited.add(dep);
         nodes.push({ path: dep, depth, nodeType: 'CodeFile' });
         next.push(dep);
       }
     }
-
     current = next;
   }
 
   return { nodes, source: 'postgres' };
 }
 
+/**
+ * Reads which DB backed a job from the analysis_jobs table.
+ * Returns 'postgres' as default if unknown.
+ */
+async function getJobDbType(jobId) {
+  try {
+    const result = await pgPool.query(
+      "SELECT db_type FROM analysis_jobs WHERE id = $1 LIMIT 1",
+      [jobId],
+    );
+    return result.rows[0]?.db_type || 'postgres';
+  } catch {
+    return 'postgres';
+  }
+}
+
 export class ImpactAnalysisAgent extends BaseAgent {
   agentId = 'impact-analysis-agent';
-
   maxRetries = 1;
-
   timeoutMs = 30_000;
 
   async process(input, context) {
@@ -135,20 +151,41 @@ export class ImpactAnalysisAgent extends BaseAgent {
     const warnings = [];
     let result;
 
-    try {
-      result = await bfsNeo4j(jobId, nodePath, maxHops);
-    } catch (neo4jErr) {
-      warnings.push(`Neo4j BFS unavailable (${neo4jErr.message}), falling back to Postgres.`);
+    // BUG 11 FIX: read db_type to choose the right BFS strategy directly,
+    // avoiding a wasted Neo4j connection attempt for Postgres-backed jobs.
+    const dbType = await getJobDbType(jobId);
 
+    if (dbType === 'neo4j' && process.env.NEO4J_URI) {
+      try {
+        result = await bfsNeo4j(jobId, nodePath, maxHops);
+      } catch (neo4jErr) {
+        warnings.push(`Neo4j BFS failed (${neo4jErr.message}), falling back to Postgres.`);
+        try {
+          result = await bfsPostgres(jobId, nodePath, Math.min(maxHops, 3));
+        } catch (pgErr) {
+          return this.buildResult({
+            jobId,
+            status: 'failed',
+            confidence: 0,
+            data: {},
+            errors: [{ code: 500, message: `Both BFS strategies failed: ${pgErr.message}` }],
+            warnings,
+            metrics: {},
+            processingTimeMs: Date.now() - start,
+          });
+        }
+      }
+    } else {
+      // Postgres job — go straight to Postgres BFS, no Neo4j attempt
       try {
-        result = await bfsPostgres(jobId, nodePath, Math.min(maxHops, 3));
+        result = await bfsPostgres(jobId, nodePath, maxHops);
       } catch (pgErr) {
         return this.buildResult({
           jobId,
           status: 'failed',
           confidence: 0,
           data: {},
-          errors: [{ code: 500, message: `Both BFS strategies failed: ${pgErr.message}` }],
+          errors: [{ code: 500, message: `Postgres BFS failed: ${pgErr.message}` }],
           warnings,
           metrics: {},
           processingTimeMs: Date.now() - start,
@@ -156,31 +193,32 @@ export class ImpactAnalysisAgent extends BaseAgent {
       }
     }
 
-    const direct = result.nodes.filter((node) => node.depth === 1);
-    const nearTransitive = result.nodes.filter((node) => node.depth >= 2 && node.depth <= 3);
-    const farTransitive = result.nodes.filter((node) => node.depth >= 4);
+    const direct        = result.nodes.filter((n) => n.depth === 1);
+    const nearTransitive = result.nodes.filter((n) => n.depth >= 2 && n.depth <= 3);
+    const farTransitive  = result.nodes.filter((n) => n.depth >= 4);
 
     return this.buildResult({
       jobId,
       status: 'success',
       confidence: scoreAnalysis(),
       data: {
-        startNode: nodePath,
+        startNode:     nodePath,
         impactedNodes: result.nodes,
         direct,
         nearTransitive,
         farTransitive,
         totalImpacted: result.nodes.length,
-        maxDepth: Math.max(0, ...result.nodes.map((node) => node.depth)),
-        source: result.source,
+        maxDepth:      Math.max(0, ...result.nodes.map((n) => n.depth)),
+        source:        result.source,
+        dbType,
       },
       errors: [],
       warnings,
       metrics: {
-        totalImpacted: result.nodes.length,
-        directCount: direct.length,
-        transitiveCount: nearTransitive.length + farTransitive.length,
-        source: result.source,
+        totalImpacted:    result.nodes.length,
+        directCount:      direct.length,
+        transitiveCount:  nearTransitive.length + farTransitive.length,
+        source:           result.source,
       },
       processingTimeMs: Date.now() - start,
     });
diff --git a/server/src/agents/core/SupervisorAgent.js b/server/src/agents/core/SupervisorAgent.js
index 27f3458..582d576 100644
--- a/server/src/agents/core/SupervisorAgent.js
+++ b/server/src/agents/core/SupervisorAgent.js
@@ -3,11 +3,13 @@ import { ScannerAgent } from '../scanner/ScannerAgent.js';
 import { PolyglotParserAgent } from '../parser/PolyglotParserAgent.js';
 import { GraphBuilderAgent } from '../graph/GraphBuilderAgent.js';
 import { RelationshipExtractorAgent } from '../graph/RelationshipExtractorAgent.js';
-import { Neo4jSeedAgent } from '../graph/Neo4jSeedAgent.js';
+// BUG 7 FIX: Neo4jSeedAgent REMOVED — Neo4jGraphRepository.persistGraph() handles seeding internally
 import { EnrichmentAgent } from '../enrichment/EnrichmentAgent.js';
 import { ContractInferenceAgent } from '../enrichment/ContractInferenceAgent.js';
 import { EmbeddingAgent } from '../embedding/EmbeddingAgent.js';
 import { PersistenceAgent } from '../persistence/PersistenceAgent.js';
+import { createGraphRepository } from '../../infrastructure/db/graphRepositoryFactory.js';
+// BUG 8 FIX: runMigrations() is NO LONGER called here — it runs in bootstrapGraphInfrastructure()
 import { AuditLogger } from './AuditLogger.js';
 import { JobStatusEmitter } from './JobStatusEmitter.js';
 import { decideConfidence, computeOverallConfidence } from './confidence.js';
@@ -22,39 +24,41 @@ import {
 
 export class SupervisorAgent {
   constructor({ db, redis } = {}) {
-    this.db = db;
+    this.db    = db;
     this.redis = redis;
 
-    this.logger = new AuditLogger(db);
+    this.logger  = new AuditLogger(db);
     this.emitter = new JobStatusEmitter(redis);
 
     this.agents = {
-      ingestion: new IngestionAgent(),
-      scanner: new ScannerAgent(),
-      parser: new PolyglotParserAgent(),
-      graphBuilder: new GraphBuilderAgent(),
+      ingestion:             new IngestionAgent(),
+      scanner:               new ScannerAgent(),
+      parser:                new PolyglotParserAgent(),
+      graphBuilder:          new GraphBuilderAgent(),
       relationshipExtractor: new RelationshipExtractorAgent(),
-      enrichment: new EnrichmentAgent(),
-      contractInference: new ContractInferenceAgent(),
-      embedding: new EmbeddingAgent(),
-      neo4jSeed: new Neo4jSeedAgent(),
-      persistence: new PersistenceAgent({ db }),
+      // BUG 7 FIX: neo4jSeed REMOVED from agents map
+      enrichment:            new EnrichmentAgent(),
+      contractInference:     new ContractInferenceAgent(),
+      embedding:             new EmbeddingAgent(),
+      persistence:           new PersistenceAgent({ db }),
     };
   }
 
   async runPipeline(jobId, input) {
-    const context = { jobId, startedAt: Date.now() };
-    const agentTrace = [];
+    const context      = { jobId, startedAt: Date.now() };
+    const agentTrace   = [];
     const pipelineData = {};
 
     await this._updateJobStatus(jobId, 'ingesting');
 
     try {
+      // ── 1. Ingestion ────────────────────────────────────────────────────
       const ingestionResult = await this._runWithSupervision(this.agents.ingestion, input, context);
       agentTrace.push(ingestionResult);
       if (ingestionResult.status === 'failed') return this._abort(jobId, ingestionResult, agentTrace);
       Object.assign(pipelineData, ingestionResult.data);
 
+      // ── 2. Scanning ─────────────────────────────────────────────────────
       await this._updateJobStatus(jobId, 'scanning');
       const scanResult = await this._runWithSupervision(
         this.agents.scanner,
@@ -65,6 +69,7 @@ export class SupervisorAgent {
       if (scanResult.status === 'failed') return this._abort(jobId, scanResult, agentTrace);
       Object.assign(pipelineData, scanResult.data);
 
+      // ── 3. Parsing ──────────────────────────────────────────────────────
       await this._updateJobStatus(jobId, 'parsing');
       const parseResult = await this._runWithSupervision(
         this.agents.parser,
@@ -75,6 +80,7 @@ export class SupervisorAgent {
       if (parseResult.status === 'failed') return this._abort(jobId, parseResult, agentTrace);
       Object.assign(pipelineData, parseResult.data);
 
+      // ── 4. Graph Building ───────────────────────────────────────────────
       await this._updateJobStatus(jobId, 'building');
       const graphResult = await this._runWithSupervision(
         this.agents.graphBuilder,
@@ -85,11 +91,14 @@ export class SupervisorAgent {
       if (graphResult.status === 'failed') return this._abort(jobId, graphResult, agentTrace);
       Object.assign(pipelineData, graphResult.data);
 
+      // ── 5. Relationship Extraction ──────────────────────────────────────
+      // BUG 10 FIX: graphRepo creation moved to AFTER this step so dbSelector
+      // receives full topology including typedEdges + distinctRelationshipTypes.
       await this._updateJobStatus(jobId, 'extracting-relationships');
       const relationshipResult = await this._runWithSupervision(
         this.agents.relationshipExtractor,
         {
-          graph: pipelineData.graph,
+          graph:         pipelineData.graph,
           functionNodes: pipelineData.functionNodes,
           extractedPath: pipelineData.extractedPath,
         },
@@ -99,19 +108,32 @@ export class SupervisorAgent {
       agentTrace.push(relationshipResult);
       Object.assign(pipelineData, relationshipResult.data);
 
+      // ── 6. Dynamic DB selection ─────────────────────────────────────────
+      // BUG 10 FIX: topology now includes typedEdges + distinctRelationshipTypes
+      context.graphRepo = createGraphRepository(pipelineData.topology, {
+        impactAnalysisDepth: input?.maxDepth || 3,
+        forceNeo4j:          input?.forceNeo4j,
+        forcePostgres:       input?.forcePostgres,
+      });
+
+      // BUG 11 FIX: record which DB was chosen so ImpactAnalysisAgent can use it
+      const dbType = context.graphRepo.constructor.name === 'Neo4jGraphRepository'
+        ? 'neo4j'
+        : 'postgres';
+      await this._recordDbType(jobId, dbType);
+
+      // ── 7. Enrichment ───────────────────────────────────────────────────
       await this._updateJobStatus(jobId, 'enriching');
       const enrichmentResult = await this._runWithSupervision(
         this.agents.enrichment,
-        {
-          graph: pipelineData.graph,
-          extractedPath: pipelineData.extractedPath,
-        },
+        { graph: pipelineData.graph, extractedPath: pipelineData.extractedPath },
         context,
         { abortOnCritical: false },
       );
       agentTrace.push(enrichmentResult);
       Object.assign(pipelineData, enrichmentResult.data);
 
+      // ── 8. Contract Inference ───────────────────────────────────────────
       await this._updateJobStatus(jobId, 'inferring-contracts');
       const contractResult = await this._runWithSupervision(
         this.agents.contractInference,
@@ -122,48 +144,36 @@ export class SupervisorAgent {
       agentTrace.push(contractResult);
       Object.assign(pipelineData, contractResult.data);
 
+      // ── 9. Embedding ────────────────────────────────────────────────────
       await this._updateJobStatus(jobId, 'embedding');
       const embeddingResult = await this._runWithSupervision(
         this.agents.embedding,
-        {
-          graph: pipelineData.graph,
-          enriched: pipelineData.enriched,
-          jobId,
-        },
+        { graph: pipelineData.graph, enriched: pipelineData.enriched, jobId },
         context,
         { abortOnCritical: false },
       );
       agentTrace.push(embeddingResult);
       Object.assign(pipelineData, embeddingResult.data);
 
-      await this._updateJobStatus(jobId, 'seeding-neo4j');
-      const neo4jResult = await this._runWithSupervision(
-        this.agents.neo4jSeed,
-        {
-          jobId,
-          typedEdges: pipelineData.typedEdges || [],
-          graph: pipelineData.graph,
-        },
-        context,
-        { abortOnCritical: false },
-      );
-      agentTrace.push(neo4jResult);
-      Object.assign(pipelineData, neo4jResult.data);
+      // BUG 7 FIX: Neo4jSeedAgent step REMOVED.
+      // Neo4jGraphRepository.persistGraph() seeds Neo4j internally as part of step 10.
+      // Postgres jobs never touch Neo4j at all.
 
+      // ── 10. Persistence ─────────────────────────────────────────────────
       await this._updateJobStatus(jobId, 'persisting');
       const persistenceResult = await this._runWithSupervision(
         this.agents.persistence,
         {
           jobId,
-          repositoryId: input?.repositoryId,
-          graph: pipelineData.graph,
-          typedEdges: pipelineData.typedEdges,
-          edges: pipelineData.edges,
+          repositoryId:  input?.repositoryId,
+          graph:         pipelineData.graph,
+          typedEdges:    pipelineData.typedEdges,
+          edges:         pipelineData.edges,
           functionNodes: pipelineData.functionNodes,
-          enriched: pipelineData.enriched,
-          contracts: pipelineData.contracts,
-          embeddings: pipelineData.embeddings,
-          topology: pipelineData.topology,
+          enriched:      pipelineData.enriched,
+          contracts:     pipelineData.contracts,
+          embeddings:    pipelineData.embeddings,
+          topology:      pipelineData.topology,
         },
         context,
       );
@@ -181,15 +191,9 @@ export class SupervisorAgent {
       });
 
       await this._tryPostPRComment(jobId, input);
-
       await this.agents.ingestion.cleanup(pipelineData.tempRoot);
 
-      return {
-        jobId,
-        status: 'completed',
-        overallConfidence,
-        agentTrace,
-      };
+      return { jobId, status: 'completed', overallConfidence, agentTrace };
     } catch (error) {
       await this._abort(jobId, { errors: [{ message: error.message }] }, agentTrace);
       await this.agents.ingestion.cleanup(pipelineData.tempRoot).catch(() => {});
@@ -197,8 +201,24 @@ export class SupervisorAgent {
     }
   }
 
+  /**
+   * BUG 11 FIX: Writes the chosen db_type to analysis_jobs.
+   * ImpactAnalysisAgent reads this to route BFS to the correct backend.
+   */
+  async _recordDbType(jobId, dbType) {
+    if (!this.db || typeof this.db.query !== 'function') return;
+    try {
+      await this.db.query(
+        `UPDATE analysis_jobs SET db_type = $1 WHERE id = $2`,
+        [dbType, jobId],
+      );
+    } catch (err) {
+      console.warn('[SupervisorAgent] Could not write db_type:', err.message);
+    }
+  }
+
   async _runWithSupervision(agent, input, context, opts = { abortOnCritical: true }) {
-    let attempt = 0;
+    let attempt  = 0;
     let lastResult;
 
     while (attempt <= agent.maxRetries) {
@@ -206,11 +226,7 @@ export class SupervisorAgent {
       const result = await this._runWithTimeout(agent, input, context);
       result.retryCount = attempt - 1;
 
-      await this.logger.log({
-        ...result,
-        attempt,
-        jobId: context.jobId,
-      });
+      await this.logger.log({ ...result, attempt, jobId: context.jobId });
 
       const decision = decideConfidence(result.confidence);
 
@@ -231,16 +247,10 @@ export class SupervisorAgent {
 
       if (opts.abortOnCritical) {
         result.status = 'failed';
-        result.errors = [
-          ...(result.errors || []),
-          { message: confidenceMessage },
-        ];
+        result.errors = [...(result.errors || []), { message: confidenceMessage }];
       } else {
-        result.status = 'partial';
-        result.warnings = [
-          ...(result.warnings || []),
-          `${confidenceMessage} Proceeding in degraded mode.`,
-        ];
+        result.status   = 'partial';
+        result.warnings = [...(result.warnings || []), `${confidenceMessage} Proceeding in degraded mode.`];
       }
       return result;
     }
@@ -259,13 +269,13 @@ export class SupervisorAgent {
       }),
     ]).catch((error) =>
       agent.buildResult({
-        jobId: context.jobId,
-        status: 'failed',
-        confidence: 0,
-        data: {},
-        errors: [{ message: error.message }],
-        warnings: [],
-        metrics: {},
+        jobId:            context.jobId,
+        status:           'failed',
+        confidence:       0,
+        data:             {},
+        errors:           [{ message: error.message }],
+        warnings:         [],
+        metrics:          {},
         processingTimeMs: agent.timeoutMs,
       }),
     );
@@ -273,62 +283,41 @@ export class SupervisorAgent {
 
   async _abort(jobId, result, agentTrace) {
     const summary = result.errors?.map((e) => e.message).join('; ') || 'Agent failed';
-    await this._updateJobStatus(jobId, 'failed', {
-      errorSummary: summary,
-      agentTrace,
-    });
-
-    return {
-      jobId,
-      status: 'failed',
-      error: summary,
-      agentTrace,
-    };
+    await this._updateJobStatus(jobId, 'failed', { errorSummary: summary, agentTrace });
+    return { jobId, status: 'failed', error: summary, agentTrace };
   }
 
   async _updateJobStatus(jobId, status, extra = {}) {
     if (this.db && typeof this.db.query === 'function') {
       try {
         await this.db.query(
-          `
-            UPDATE analysis_jobs
-            SET
-              status = $1::job_status,
-              overall_confidence = COALESCE($2, overall_confidence),
-              file_count = COALESCE($3, file_count),
-              node_count = COALESCE($4, node_count),
-              edge_count = COALESCE($5, edge_count),
-              error_summary = COALESCE($6, error_summary),
-              started_at = CASE
-                WHEN $1::job_status = 'ingesting'::job_status AND started_at IS NULL
-                  THEN NOW()
-                ELSE started_at
-              END,
-              completed_at = CASE
-                WHEN $1::job_status IN (
-                  'completed'::job_status,
-                  'failed'::job_status,
-                  'partial'::job_status
-                )
-                  THEN NOW()
-                ELSE completed_at
-              END,
-              agent_trace = COALESCE($7::jsonb, agent_trace)
-            WHERE id = $8
-          `,
+          `UPDATE analysis_jobs
+           SET status             = $1::job_status,
+               overall_confidence = COALESCE($2, overall_confidence),
+               file_count         = COALESCE($3, file_count),
+               node_count         = COALESCE($4, node_count),
+               edge_count         = COALESCE($5, edge_count),
+               error_summary      = COALESCE($6, error_summary),
+               started_at         = CASE
+                 WHEN $1::job_status = 'ingesting'::job_status AND started_at IS NULL THEN NOW()
+                 ELSE started_at END,
+               completed_at       = CASE
+                 WHEN $1::job_status IN ('completed'::job_status,'failed'::job_status,'partial'::job_status)
+                 THEN NOW() ELSE completed_at END,
+               agent_trace        = COALESCE($7::jsonb, agent_trace)
+           WHERE id = $8`,
           [
             status,
             extra.overallConfidence ?? null,
-            extra.fileCount ?? null,
-            extra.nodeCount ?? null,
-            extra.edgeCount ?? null,
-            extra.errorSummary ?? null,
+            extra.fileCount         ?? null,
+            extra.nodeCount         ?? null,
+            extra.edgeCount         ?? null,
+            extra.errorSummary      ?? null,
             extra.agentTrace ? JSON.stringify(extra.agentTrace) : null,
             jobId,
           ],
         );
       } catch (error) {
-        // Status emission still proceeds even if DB status update fails.
         console.error('[SupervisorAgent] Failed to update analysis_jobs status:', error.message);
       }
     }
@@ -347,12 +336,7 @@ export class SupervisorAgent {
       if (!this.db || typeof this.db.query !== 'function') return;
 
       const jobResult = await this.db.query(
-        `
-          SELECT user_id
-          FROM analysis_jobs
-          WHERE id = $1
-          LIMIT 1
-        `,
+        'SELECT user_id FROM analysis_jobs WHERE id = $1 LIMIT 1',
         [jobId],
       );
 
@@ -369,9 +353,9 @@ export class SupervisorAgent {
   async _tryPostPRComment(jobId, input) {
     try {
       const prNumber = input?.github?.prNumber;
-      const owner = input?.github?.owner;
-      const repo = input?.github?.repo;
-      const sha = input?.github?.headSha;
+      const owner    = input?.github?.owner;
+      const repo     = input?.github?.repo;
+      const sha      = input?.github?.headSha;
 
       if (!prNumber || !owner || !repo) return;
       if (!GitHubPRService.isConfigured()) {
@@ -392,7 +376,7 @@ export class SupervisorAgent {
 
       const { impactedFiles } = await ImpactAnalysisService.findImpactedFiles(jobId, changedFiles, 3);
       const graphUrl = `${process.env.CLIENT_URL || 'http://localhost:5173'}/graph?jobId=${jobId}`;
-      const comment = GitHubPRService.formatImpactComment(
+      const comment  = GitHubPRService.formatImpactComment(
         changedFiles,
         Array.from(impactedFiles).sort(),
         graphUrl,
@@ -407,18 +391,16 @@ export class SupervisorAgent {
 
       console.log(`[SupervisorAgent] PR comment posted to ${owner}/${repo}#${prNumber}`);
 
-      // Create a check run for PR status
       if (sha) {
         const conclusion = impactedFiles.size > 10 ? 'failure' : 'neutral';
         await GitHubPRService.createCheckRun(owner, repo, sha, {
           conclusion,
-          title: `${impactedFiles.size} files potentially impacted`,
-          summary: `${changedFiles.length} changed files affect ${impactedFiles.size} dependent files.`,
+          title:      `${impactedFiles.size} files potentially impacted`,
+          summary:    `${changedFiles.length} changed files affect ${impactedFiles.size} dependent files.`,
           detailsUrl: graphUrl,
         });
       }
     } catch (err) {
-      // PR comment failure must never abort the main pipeline.
       console.error('[SupervisorAgent] Failed to post PR comment:', err.message);
     }
   }
diff --git a/server/src/agents/graph/GraphBuilderAgent.js b/server/src/agents/graph/GraphBuilderAgent.js
index 8c6d987..5979837 100644
--- a/server/src/agents/graph/GraphBuilderAgent.js
+++ b/server/src/agents/graph/GraphBuilderAgent.js
@@ -1,30 +1,34 @@
-import path from 'path';
-import { existsSync } from 'fs';
-import { BaseAgent } from '../core/BaseAgent.js';
-import { scoreGraphBuilder } from '../core/confidence.js';
+import path from "path";
+import { existsSync } from "fs";
+import { BaseAgent } from "../core/BaseAgent.js";
+import { scoreGraphBuilder } from "../core/confidence.js";
 
-const RESOLVE_EXTS = ['.js', '.ts', '.jsx', '.tsx', '.py', '.go'];
+const RESOLVE_EXTS = [".js", ".ts", ".jsx", ".tsx", ".py", ".go"];
 
 function inferFileType(relPath) {
-  const normalized = relPath.replace(/\\/g, '/').toLowerCase();
-  const segments = normalized.split('/');
-  const filename = segments[segments.length - 1] || '';
-
-  if (segments.some((s) => s === 'components' || s === 'component')) return 'component';
-  if (segments.some((s) => s === 'pages' || s === 'views' || s === 'screens')) return 'page';
-  if (segments.some((s) => s === 'hooks')) return 'hook';
-  if (segments.some((s) => s === 'services' || s === 'api' || s === 'apis')) return 'service';
-  if (segments.some((s) => s === 'utils' || s === 'helpers' || s === 'lib')) return 'util';
-  if (/config|\.conf\.|\.rc\./.test(filename)) return 'config';
-  return 'module';
+  const normalized = relPath.replace(/\\/g, "/").toLowerCase();
+  const segments = normalized.split("/");
+  const filename = segments[segments.length - 1] || "";
+
+  if (segments.some((s) => s === "components" || s === "component"))
+    return "component";
+  if (segments.some((s) => s === "pages" || s === "views" || s === "screens"))
+    return "page";
+  if (segments.some((s) => s === "hooks")) return "hook";
+  if (segments.some((s) => s === "services" || s === "api" || s === "apis"))
+    return "service";
+  if (segments.some((s) => s === "utils" || s === "helpers" || s === "lib"))
+    return "util";
+  if (/config|\.conf\.|\.rc\./.test(filename)) return "config";
+  return "module";
 }
 
 function normalizeRelative(filePath, rootDir) {
-  return path.relative(rootDir, filePath).replace(/\\/g, '/');
+  return path.relative(rootDir, filePath).replace(/\\/g, "/");
 }
 
 function resolveToAbsolute(fromFile, specifier) {
-  if (!specifier.startsWith('.') && !specifier.startsWith('/')) return null;
+  if (!specifier.startsWith(".") && !specifier.startsWith("/")) return null;
 
   const base = path.resolve(path.dirname(fromFile), specifier);
 
@@ -36,7 +40,7 @@ function resolveToAbsolute(fromFile, specifier) {
   }
 
   for (const ext of RESOLVE_EXTS) {
-    const candidate = path.join(base, 'index' + ext);
+    const candidate = path.join(base, "index" + ext);
     if (existsSync(candidate)) return candidate;
   }
 
@@ -44,7 +48,10 @@ function resolveToAbsolute(fromFile, specifier) {
 }
 
 function isLocalSpecifier(specifier) {
-  return typeof specifier === 'string' && (specifier.startsWith('.') || specifier.startsWith('/'));
+  return (
+    typeof specifier === "string" &&
+    (specifier.startsWith(".") || specifier.startsWith("/"))
+  );
 }
 
 function findStronglyConnectedComponents(adjacency) {
@@ -92,7 +99,7 @@ function findStronglyConnectedComponents(adjacency) {
 }
 
 export class GraphBuilderAgent extends BaseAgent {
-  agentId = 'graph-builder-agent';
+  agentId = "graph-builder-agent";
   maxRetries = 1;
   timeoutMs = 180_000;
 
@@ -102,15 +109,23 @@ export class GraphBuilderAgent extends BaseAgent {
     const warnings = [];
 
     const rootDir = input?.extractedPath || input?.rootDir;
-    const parsedFiles = Array.isArray(input?.parsedFiles) ? input.parsedFiles : [];
+    const parsedFiles = Array.isArray(input?.parsedFiles)
+      ? input.parsedFiles
+      : [];
 
     if (!rootDir || parsedFiles.length === 0) {
       return this.buildResult({
         jobId: context?.jobId,
-        status: 'failed',
+        status: "failed",
         confidence: 0,
         data: {},
-        errors: [{ code: 400, message: 'GraphBuilderAgent requires extractedPath/rootDir and parsedFiles.' }],
+        errors: [
+          {
+            code: 400,
+            message:
+              "GraphBuilderAgent requires extractedPath/rootDir and parsedFiles.",
+          },
+        ],
         warnings,
         metrics: {},
         processingTimeMs: Date.now() - start,
@@ -172,7 +187,9 @@ export class GraphBuilderAgent extends BaseAgent {
         },
       };
 
-      functionNodes[source] = Array.isArray(parsed.functionNodes) ? parsed.functionNodes : [];
+      functionNodes[source] = Array.isArray(parsed.functionNodes)
+        ? parsed.functionNodes
+        : [];
 
       adjacency.set(source, deps);
       if (!reverse.has(source)) reverse.set(source, []);
@@ -184,7 +201,7 @@ export class GraphBuilderAgent extends BaseAgent {
         edges.push({
           source,
           target: dep,
-          type: 'import',
+          type: "import",
         });
       }
     }
@@ -196,12 +213,23 @@ export class GraphBuilderAgent extends BaseAgent {
 
     const sccs = findStronglyConnectedComponents(adjacency);
     const cycles = sccs.filter((component) => component.length > 1);
+    const relationshipTypeCount = new Set(
+      edges.map((edge) => edge.type).filter(Boolean),
+    ).size;
+    const largestCycleSize = cycles.reduce(
+      (max, component) => Math.max(max, component.length),
+      0,
+    );
 
     const topology = {
       nodeCount: Object.keys(graph).length,
       edgeCount: edges.length,
       cyclesDetected: cycles.length,
       cycles,
+      relationshipTypeCount,
+      distinctRelationshipTypes: relationshipTypeCount,
+      largestCycleSize,
+      maxCycleSize: largestCycleSize,
       unresolvedImports: unresolvedLocalImports,
       localImportSpecifiers,
       externalImportSpecifiers,
@@ -220,7 +248,7 @@ export class GraphBuilderAgent extends BaseAgent {
 
     return this.buildResult({
       jobId: context?.jobId,
-      status: 'success',
+      status: "success",
       confidence,
       data: { graph, edges, topology, functionNodes },
       errors,
diff --git a/server/src/agents/graph/Neo4jSeedAgent.js b/server/src/agents/graph/Neo4jSeedAgent.js
index 2c6f85f..2912edb 100644
--- a/server/src/agents/graph/Neo4jSeedAgent.js
+++ b/server/src/agents/graph/Neo4jSeedAgent.js
@@ -1,13 +1,6 @@
-import neo4j from 'neo4j-driver';
 import { BaseAgent } from '../core/BaseAgent.js';
 import { scoreNeo4jSeed } from '../core/confidence.js';
-
-function getNeo4jDriver() {
-  const uri = process.env.NEO4J_URI || 'bolt://localhost:7687';
-  const user = process.env.NEO4J_USER || 'neo4j';
-  const pass = process.env.NEO4J_PASSWORD || 'neo4j';
-  return neo4j.driver(uri, neo4j.auth.basic(user, pass));
-}
+import { getNeo4jDriver } from '../../infrastructure/db/neo4jDriver.js';
 
 const VALID_TYPES = new Set([
   'IMPORTS',
@@ -61,6 +54,7 @@ export class Neo4jSeedAgent extends BaseAgent {
       });
     }
 
+    // Use the singleton driver
     const driver = getNeo4jDriver();
     const session = driver.session();
 
@@ -69,6 +63,7 @@ export class Neo4jSeedAgent extends BaseAgent {
     let failed = 0;
 
     try {
+      // Ensure constraints are in place (already handled by migrations, but kept for robustness)
       await session.run(`
         CREATE CONSTRAINT file_node_id IF NOT EXISTS
         FOR (f:CodeFile) REQUIRE (f.jobId, f.path) IS UNIQUE
@@ -132,7 +127,7 @@ export class Neo4jSeedAgent extends BaseAgent {
       errors.push({ code: 500, message: error.message });
     } finally {
       await session.close();
-      await driver.close();
+      // Note: We DO NOT close the driver here as it is a singleton managed by the driver module.
     }
 
     const confidence = scoreNeo4jSeed({
diff --git a/server/src/agents/persistence/PersistenceAgent.js b/server/src/agents/persistence/PersistenceAgent.js
index b8ab706..8c33c25 100644
--- a/server/src/agents/persistence/PersistenceAgent.js
+++ b/server/src/agents/persistence/PersistenceAgent.js
@@ -1,22 +1,5 @@
 import { BaseAgent } from '../core/BaseAgent.js';
 import { scorePersistence } from '../core/confidence.js';
-import { pgPool } from '../../infrastructure/connections.js';
-
-function toJson(value, fallback) {
-  if (value === undefined || value === null) return JSON.stringify(fallback);
-  return JSON.stringify(value);
-}
-
-function toVectorLiteral(embedding) {
-  if (!Array.isArray(embedding) || embedding.length === 0) return null;
-
-  const normalized = embedding
-    .map((value) => Number(value))
-    .filter((value) => Number.isFinite(value));
-
-  if (normalized.length === 0) return null;
-  return `[${normalized.join(',')}]`;
-}
 
 export class PersistenceAgent extends BaseAgent {
   agentId = 'persistence-agent';
@@ -25,299 +8,58 @@ export class PersistenceAgent extends BaseAgent {
 
   constructor({ db } = {}) {
     super();
-    this.db = db || pgPool;
+    this.db = db; // Legacy, kept for compatibility if needed elsewhere
   }
 
   async process(input, context) {
     const start = Date.now();
-    const errors = [];
-    const warnings = [];
-
     const jobId = input?.jobId || context?.jobId;
-    const graph = input?.graph || {};
-    const typedEdges = Array.isArray(input?.typedEdges) ? input.typedEdges : [];
-    const edges = Array.isArray(input?.edges) ? input.edges : [];
-    const functionNodes = input?.functionNodes || {};
-    const embeddings = input?.embeddings || {};
-    const enriched = input?.enriched || {};
-    const contracts = input?.contracts || {};
-    const topology = input?.topology || {};
 
     if (!jobId) {
       return this.buildResult({
-        jobId: context?.jobId,
+        jobId,
         status: 'failed',
         confidence: 0,
-        data: {},
         errors: [{ code: 400, message: 'PersistenceAgent requires a jobId.' }],
-        warnings,
-        metrics: {},
         processingTimeMs: Date.now() - start,
       });
     }
 
-    const deadCodeSet = new Set(Array.isArray(topology.deadCodeCandidates) ? topology.deadCodeCandidates : []);
-
-    const nodeEntries = Object.entries(graph);
-
-    const nodePaths = [];
-    const nodeTypes = [];
-    const nodeDeclarations = [];
-    const nodeMetrics = [];
-    const nodeSummaries = [];
-    const nodeDeadFlags = [];
-
-    for (const [filePath, node] of nodeEntries) {
-      nodePaths.push(filePath);
-      nodeTypes.push(node?.type || 'module');
-      nodeDeclarations.push(toJson(node?.declarations, []));
-      nodeMetrics.push(toJson(node?.metrics, {}));
-      nodeSummaries.push(enriched?.[filePath]?.summary || null);
-      nodeDeadFlags.push(deadCodeSet.has(filePath));
-    }
-
-    const edgeSourcePaths = [];
-    const edgeTargetPaths = [];
-    const edgeTypes = [];
-
-    const edgesToPersist = typedEdges.length > 0 ? typedEdges : edges;
-
-    for (const edge of edgesToPersist) {
-      if (!edge?.source || !edge?.target) continue;
-      edgeSourcePaths.push(edge.source);
-      edgeTargetPaths.push(edge.target);
-      edgeTypes.push(edge.type || 'import');
-    }
-
-    const embeddingPaths = [];
-    const embeddingVectors = [];
-
-    for (const [filePath, vector] of Object.entries(embeddings)) {
-      const vectorLiteral = toVectorLiteral(vector);
-      if (!vectorLiteral) continue;
-
-      embeddingPaths.push(filePath);
-      embeddingVectors.push(vectorLiteral);
-    }
-
-    const functionNodePaths = [];
-    const functionNodeNames = [];
-    const functionNodeKinds = [];
-    const functionNodeCalls = [];
-    const functionNodeLocs = [];
-
-    for (const [filePath, declarations] of Object.entries(functionNodes)) {
-      if (!Array.isArray(declarations)) continue;
-
-      for (const declaration of declarations) {
-        if (!declaration?.name) continue;
-
-        functionNodePaths.push(filePath);
-        functionNodeNames.push(declaration.name);
-        functionNodeKinds.push(declaration.kind || 'function');
-        functionNodeCalls.push(toJson(Array.isArray(declaration.calls) ? declaration.calls : [], []));
-        functionNodeLocs.push(Number.isFinite(declaration.loc) ? Number(declaration.loc) : null);
-      }
-    }
-
-    const contractPaths = [];
-    const contractRoutes = [];
-    const contractEnvDeps = [];
-    const contractExtServices = [];
-    const contractCaching = [];
-
-    for (const [filePath, contract] of Object.entries(contracts)) {
-      contractPaths.push(filePath);
-      contractRoutes.push(toJson(contract?.routes, []));
-      contractEnvDeps.push(toJson(contract?.envDependencies, []));
-      contractExtServices.push(toJson(contract?.externalServices, []));
-      contractCaching.push(toJson(contract?.cachingPatterns, []));
+    const { graphRepo } = context;
+    if (!graphRepo) {
+      return this.buildResult({
+        jobId,
+        status: 'failed',
+        confidence: 0,
+        errors: [{ code: 500, message: 'No graphRepo provided in context.' }],
+        processingTimeMs: Date.now() - start,
+      });
     }
 
-    const recordsAttempted =
-      nodePaths.length +
-      edgeSourcePaths.length +
-      embeddingPaths.length +
-      functionNodePaths.length +
-      contractPaths.length;
-    let recordsWritten = 0;
-
-    let client;
     try {
-      client = await this.db.connect();
-      await client.query('BEGIN');
-
-      if (nodePaths.length > 0) {
-        const nodeResult = await client.query(
-          `
-            INSERT INTO graph_nodes (
-              job_id,
-              file_path,
-              file_type,
-              declarations,
-              metrics,
-              summary,
-              is_dead_code
-            )
-            SELECT
-              $1,
-              unnest($2::text[]),
-              unnest($3::text[]),
-              unnest($4::jsonb[]),
-              unnest($5::jsonb[]),
-              unnest($6::text[]),
-              unnest($7::boolean[])
-            ON CONFLICT (job_id, file_path) DO UPDATE
-            SET file_type = EXCLUDED.file_type,
-                declarations = EXCLUDED.declarations,
-                metrics = EXCLUDED.metrics,
-                summary = EXCLUDED.summary,
-                is_dead_code = EXCLUDED.is_dead_code
-          `,
-          [
-            jobId,
-            nodePaths,
-            nodeTypes,
-            nodeDeclarations,
-            nodeMetrics,
-            nodeSummaries,
-            nodeDeadFlags,
-          ],
-        );
-
-        recordsWritten += nodeResult.rowCount || 0;
-      }
-
-      await client.query('SAVEPOINT after_nodes');
-
-      if (edgeSourcePaths.length > 0) {
-        const edgeResult = await client.query(
-          `
-            INSERT INTO graph_edges (
-              job_id,
-              source_path,
-              target_path,
-              edge_type
-            )
-            SELECT
-              $1,
-              unnest($2::text[]),
-              unnest($3::text[]),
-              unnest($4::text[])
-            ON CONFLICT (job_id, source_path, target_path, edge_type) DO NOTHING
-          `,
-          [jobId, edgeSourcePaths, edgeTargetPaths, edgeTypes],
-        );
-
-        recordsWritten += edgeResult.rowCount || 0;
-      }
-
-      await client.query('SAVEPOINT after_edges');
-
-      if (embeddingPaths.length > 0) {
-        const embeddingResult = await client.query(
-          `
-            INSERT INTO file_embeddings (
-              job_id,
-              file_path,
-              embedding
-            )
-            SELECT
-              $1,
-              t.file_path,
-              t.embedding::vector
-            FROM unnest($2::text[], $3::text[]) AS t(file_path, embedding)
-            ON CONFLICT (job_id, file_path) DO UPDATE
-            SET embedding = EXCLUDED.embedding
-          `,
-          [jobId, embeddingPaths, embeddingVectors],
-        );
-
-        recordsWritten += embeddingResult.rowCount || 0;
-      }
-
-      await client.query('SAVEPOINT after_embeddings');
-
-      if (functionNodePaths.length > 0) {
-        const functionNodeResult = await client.query(
-          `
-            INSERT INTO function_nodes (
-              job_id,
-              file_path,
-              name,
-              kind,
-              calls,
-              loc
-            )
-            SELECT
-              $1,
-              unnest($2::text[]),
-              unnest($3::text[]),
-              unnest($4::text[]),
-              unnest($5::jsonb[]),
-              unnest($6::integer[])
-            ON CONFLICT (job_id, file_path, name) DO UPDATE
-            SET kind = EXCLUDED.kind,
-                calls = EXCLUDED.calls,
-                loc = EXCLUDED.loc
-          `,
-          [
-            jobId,
-            functionNodePaths,
-            functionNodeNames,
-            functionNodeKinds,
-            functionNodeCalls,
-            functionNodeLocs,
-          ],
-        );
-
-        recordsWritten += functionNodeResult.rowCount || 0;
-      }
-
-      await client.query('SAVEPOINT after_function_nodes');
-
-      if (contractPaths.length > 0) {
-        const contractResult = await client.query(
-          `
-            INSERT INTO api_contracts (
-              job_id,
-              file_path,
-              routes,
-              env_deps,
-              ext_services,
-              caching
-            )
-            SELECT
-              $1,
-              unnest($2::text[]),
-              unnest($3::jsonb[]),
-              unnest($4::jsonb[]),
-              unnest($5::jsonb[]),
-              unnest($6::jsonb[])
-            ON CONFLICT (job_id, file_path) DO UPDATE
-            SET routes = EXCLUDED.routes,
-                env_deps = EXCLUDED.env_deps,
-                ext_services = EXCLUDED.ext_services,
-                caching = EXCLUDED.caching
-          `,
-          [
-            jobId,
-            contractPaths,
-            contractRoutes,
-            contractEnvDeps,
-            contractExtServices,
-            contractCaching,
-          ],
-        );
-
-        recordsWritten += contractResult.rowCount || 0;
-      }
-
-      await client.query('COMMIT');
-
+      // 1. Prepare persistence payload
+      const persistParams = {
+        jobId,
+        repositoryId: input?.repositoryId,
+        graph: input?.graph,
+        typedEdges: input?.typedEdges,
+        edges: input?.edges,
+        functionNodes: input?.functionNodes,
+        enriched: input?.enriched,
+        contracts: input?.contracts,
+        embeddings: input?.embeddings,
+        topology: input?.topology,
+      };
+
+      // 2. Delegate to the repository implementation
+      await graphRepo.persistGraph(persistParams);
+
+      // 3. Compute simple confidence score
+      // (Since logic is delegated, we assume success means high confidence here, 
+      // but in a production app we'd get granular metrics from the repo)
       const confidence = scorePersistence({
-        recordsAttempted,
-        recordsWritten,
+        recordsAttempted: Object.keys(persistParams.graph || {}).length,
+        recordsWritten: Object.keys(persistParams.graph || {}).length, 
       });
 
       return this.buildResult({
@@ -325,47 +67,23 @@ export class PersistenceAgent extends BaseAgent {
         status: 'success',
         confidence,
         data: {
-          written: {
-            nodes: nodePaths.length,
-            edges: edgeSourcePaths.length,
-            embeddings: embeddingPaths.length,
-            functionNodes: functionNodePaths.length,
-            contracts: contractPaths.length,
-          },
           durationMs: Date.now() - start,
+          mode: graphRepo.constructor.name,
         },
-        errors,
-        warnings,
         metrics: {
-          recordsAttempted,
-          recordsWritten,
+          nodeCount: Object.keys(persistParams.graph || {}).length,
         },
         processingTimeMs: Date.now() - start,
       });
     } catch (error) {
-      if (client) {
-        try {
-          await client.query('ROLLBACK');
-        } catch {
-          warnings.push('Rollback failed after persistence error.');
-        }
-      }
-
+      console.error('[PersistenceAgent] Storage error:', error.message);
       return this.buildResult({
         jobId,
         status: 'failed',
         confidence: 0,
-        data: {},
         errors: [{ code: error.statusCode || 500, message: error.message }],
-        warnings,
-        metrics: {
-          recordsAttempted,
-          recordsWritten,
-        },
         processingTimeMs: Date.now() - start,
       });
-    } finally {
-      if (client) client.release();
     }
   }
 }
diff --git a/server/src/agents/query/QueryAgent.js b/server/src/agents/query/QueryAgent.js
index cf2870f..81c01a5 100644
--- a/server/src/agents/query/QueryAgent.js
+++ b/server/src/agents/query/QueryAgent.js
@@ -185,15 +185,6 @@ export class QueryAgent extends BaseAgent {
     try {
       const cached = await this._readCache(cacheKey);
       if (cached) {
-        await this._saveQuery({
-          userId,
-          jobId,
-          question,
-          answer: cached.answer,
-          highlightedFiles: cached.highlightedFiles,
-          confidence: cached.confidence,
-        });
-
         return this.buildResult({
           jobId,
           status: 'success',
diff --git a/server/src/analyze/controllers/analyze.controller.js b/server/src/analyze/controllers/analyze.controller.js
index 6fec481..c416935 100644
--- a/server/src/analyze/controllers/analyze.controller.js
+++ b/server/src/analyze/controllers/analyze.controller.js
@@ -178,6 +178,9 @@ export async function analyzeController(req, res, next) {
       repositoryId,
       userId,
       githubToken: req.cookies?.github_token,
+      // optional forcing source for manual testing
+      // forceNeo4j: true,
+      // forcePostgres: true,
     };
 
     await enqueueAnalysisJob({
diff --git a/server/src/api/ai/routes/ai.routes.js b/server/src/api/ai/routes/ai.routes.js
index cec3526..69051fc 100644
--- a/server/src/api/ai/routes/ai.routes.js
+++ b/server/src/api/ai/routes/ai.routes.js
@@ -1,5 +1,6 @@
 import { Router } from 'express';
 import jwt from 'jsonwebtoken';
+import crypto from 'node:crypto';
 import rateLimit from 'express-rate-limit';
 import { QueryAgent } from '../../../agents/query/QueryAgent.js';
 import { AnalysisAgent } from '../../../agents/analysis/AnalysisAgent.js';
@@ -13,23 +14,36 @@ const router = Router();
 const chatClient = createChatClient();
 const defaultChatModel = process.env.AI_MODEL || process.env.OPENAI_MODEL || 'gpt-4o-mini';
 
+// BUG 5 FIX: Redis cache for streamed explanations
+const STREAM_CACHE_TTL = 60 * 60; // 1 hour
+
+function streamCacheKey(jobId, question) {
+  const hash = crypto
+    .createHash('sha256')
+    .update(`${jobId}:${question}`)
+    .digest('hex');
+  return `stream:explain:${hash}`;
+}
+
+// BUG 8 FIX: safe positive integer parser — returns undefined (not NaN) on invalid input
+function toSafePositiveInt(value) {
+  const n = Number.parseInt(value, 10);
+  return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+
 const aiLimiter = rateLimit({
   windowMs: 60 * 1000,
   max: Number(process.env.AI_RATE_LIMIT_PER_MINUTE || 30),
   keyGenerator: (req) => {
     const token = req.cookies?.token || req.headers.authorization?.replace('Bearer ', '');
-
     if (token && process.env.JWT_SECRET) {
       try {
         const decoded = jwt.verify(token, process.env.JWT_SECRET);
-        if (decoded?.id) {
-          return `user:${decoded.id}`;
-        }
+        if (decoded?.id) return `user:${decoded.id}`;
       } catch {
-        // Fall back to IP key if JWT is not available or invalid.
+        // Fall back to IP key if JWT is invalid.
       }
     }
-
     return req.ip;
   },
   standardHeaders: true,
@@ -39,14 +53,11 @@ const aiLimiter = rateLimit({
 
 function toGraphFromRows(nodeRows = [], edgeRows = []) {
   const depsBySource = new Map();
-
   for (const row of edgeRows) {
     if (!depsBySource.has(row.source_path)) depsBySource.set(row.source_path, []);
     depsBySource.get(row.source_path).push(row.target_path);
   }
-
   const graph = {};
-
   for (const node of nodeRows) {
     graph[node.file_path] = {
       deps: depsBySource.get(node.file_path) || [],
@@ -56,28 +67,31 @@ function toGraphFromRows(nodeRows = [], edgeRows = []) {
       summary: node.summary || null,
     };
   }
-
   return graph;
 }
 
 router.use(aiLimiter);
 
+// ── POST /suggest-refactor ──────────────────────────────────────────────────
 router.post('/suggest-refactor', requirePlan(), async (req, res, next) => {
-  const jobId = String(req.body?.jobId || '').trim();
+  const jobId    = String(req.body?.jobId    || '').trim();
   const filePath = String(req.body?.filePath || '').trim();
 
   if (!jobId || !filePath) {
     return res.status(400).json({ error: 'jobId and filePath are required.' });
   }
 
+  // BUG 4.2: basic path traversal guard
+  if (filePath.includes('../') || filePath.includes('..\\')) {
+    return res.status(400).json({ error: 'Invalid file path.' });
+  }
+
   try {
     const nodeResult = await pgPool.query(
-      `
-        SELECT file_path, file_type, declarations, metrics, summary
-        FROM graph_nodes
-        WHERE job_id = $1 AND file_path = $2
-        LIMIT 1
-      `,
+      `SELECT file_path, file_type, declarations, metrics, summary
+       FROM graph_nodes
+       WHERE job_id = $1 AND file_path = $2
+       LIMIT 1`,
       [jobId, filePath],
     );
 
@@ -90,7 +104,7 @@ router.post('/suggest-refactor', requirePlan(), async (req, res, next) => {
     }
 
     const node = nodeResult.rows[0];
-    const exportsList = (node.declarations || []).map((declaration) => declaration?.name).filter(Boolean);
+    const exportsList = (node.declarations || []).map((d) => d?.name).filter(Boolean);
 
     const prompt = `You are a senior software architect reviewing a file in a dependency graph analysis.
 
@@ -119,94 +133,72 @@ Only respond with the JSON object.`;
     });
 
     const content = completion?.content?.trim() || '';
-
     let parsed;
     try {
       parsed = JSON.parse(content);
     } catch {
-      parsed = {
-        concerns: [],
-        suggestions: content ? [content] : [],
-        priority: 'medium',
-        estimatedEffort: 'unknown',
-      };
+      parsed = { concerns: [], suggestions: content ? [content] : [], priority: 'medium', estimatedEffort: 'unknown' };
     }
 
     return res.status(200).json({
       filePath,
-      concerns: Array.isArray(parsed?.concerns) ? parsed.concerns : [],
-      suggestions: Array.isArray(parsed?.suggestions) ? parsed.suggestions : [],
-      priority: ['high', 'medium', 'low'].includes(parsed?.priority) ? parsed.priority : 'medium',
-      estimatedEffort:
-        typeof parsed?.estimatedEffort === 'string' && parsed.estimatedEffort.trim()
-          ? parsed.estimatedEffort.trim()
-          : 'unknown',
+      concerns:        Array.isArray(parsed?.concerns)     ? parsed.concerns     : [],
+      suggestions:     Array.isArray(parsed?.suggestions)  ? parsed.suggestions  : [],
+      priority:        ['high','medium','low'].includes(parsed?.priority) ? parsed.priority : 'medium',
+      estimatedEffort: typeof parsed?.estimatedEffort === 'string' && parsed.estimatedEffort.trim()
+        ? parsed.estimatedEffort.trim()
+        : 'unknown',
     });
   } catch (error) {
     return next(error);
   }
 });
 
+// ── GET /queries ────────────────────────────────────────────────────────────
 router.get('/queries', async (req, res, next) => {
   const authUser = getAuthUser(req);
-  if (!authUser?.id) {
-    return res.status(401).json({ error: 'Authentication required.' });
-  }
+  if (!authUser?.id) return res.status(401).json({ error: 'Authentication required.' });
 
-  const jobId = String(req.query?.jobId || '').trim();
-  const page = Math.max(1, Number.parseInt(req.query?.page, 10) || 1);
-  const limit = Math.min(50, Math.max(1, Number.parseInt(req.query?.limit, 10) || 20));
+  const jobId  = String(req.query?.jobId || '').trim();
+  const page   = Math.max(1, Number.parseInt(req.query?.page, 10)  || 1);
+  const limit  = Math.min(50, Math.max(1, Number.parseInt(req.query?.limit, 10) || 20));
   const offset = (page - 1) * limit;
 
   try {
     const userId = await resolveDatabaseUserId(authUser);
-    if (!userId) {
-      return res.status(500).json({ error: 'Failed to resolve authenticated user.' });
-    }
+    if (!userId) return res.status(500).json({ error: 'Failed to resolve authenticated user.' });
 
     if (jobId) {
       const ownership = await pgPool.query(
-        `
-          SELECT 1
-          FROM analysis_jobs
-          WHERE id = $1 AND user_id = $2
-          LIMIT 1
-        `,
+        `SELECT 1 FROM analysis_jobs WHERE id = $1 AND user_id = $2 LIMIT 1`,
         [jobId, userId],
       );
-
       if (ownership.rowCount === 0) {
         return res.status(404).json({ error: 'Analysis job not found for this user.' });
       }
     }
 
     const queryText = jobId
-      ? `
-          SELECT id, question, answer, highlights, confidence, created_at
-          FROM saved_queries
-          WHERE user_id = $1 AND job_id = $2
-          ORDER BY created_at DESC
-          LIMIT $3 OFFSET $4
-        `
-      : `
-          SELECT id, question, answer, highlights, confidence, created_at
-          FROM saved_queries
-          WHERE user_id = $1
-          ORDER BY created_at DESC
-          LIMIT $2 OFFSET $3
-        `;
+      ? `SELECT id, question, answer, highlights, confidence, created_at
+         FROM saved_queries
+         WHERE user_id = $1 AND job_id = $2
+         ORDER BY created_at DESC LIMIT $3 OFFSET $4`
+      : `SELECT id, question, answer, highlights, confidence, created_at
+         FROM saved_queries
+         WHERE user_id = $1
+         ORDER BY created_at DESC LIMIT $2 OFFSET $3`;
 
     const params = jobId ? [userId, jobId, limit, offset] : [userId, limit, offset];
     const result = await pgPool.query(queryText, params);
 
     return res.status(200).json({
       queries: result.rows.map((row) => ({
-        id: row.id,
-        question: row.question,
-        answer: row.answer,
+        id:         row.id,
+        question:   row.question,
+        answer:     row.answer,
         highlights: Array.isArray(row.highlights) ? row.highlights : [],
         confidence: row.confidence || null,
-        createdAt: row.created_at,
+        createdAt:  row.created_at,
       })),
       page,
       limit,
@@ -216,26 +208,28 @@ router.get('/queries', async (req, res, next) => {
   }
 });
 
+// ── POST /query ─────────────────────────────────────────────────────────────
 router.post('/query', async (req, res, next) => {
   const authUser = getAuthUser(req);
-  if (!authUser?.id) {
-    return res.status(401).json({ error: 'Authentication required.' });
-  }
+  if (!authUser?.id) return res.status(401).json({ error: 'Authentication required.' });
 
   const question = String(req.body?.question || '').trim();
-  const jobId = String(req.body?.jobId || '').trim();
+  const jobId    = String(req.body?.jobId    || '').trim();
 
   if (!question || !jobId) {
     return res.status(400).json({ error: 'question and jobId are required.' });
   }
 
+  // BUG 4.2 FIX: question length guard
+  if (question.length > 2000) {
+    return res.status(400).json({ error: 'Question must be 2000 characters or fewer.' });
+  }
+
   try {
     const userId = await resolveDatabaseUserId(authUser);
-    if (!userId) {
-      return res.status(500).json({ error: 'Failed to resolve authenticated user.' });
-    }
+    if (!userId) return res.status(500).json({ error: 'Failed to resolve authenticated user.' });
 
-    const agent = new QueryAgent({ db: pgPool, redis: redisClient });
+    const agent  = new QueryAgent({ db: pgPool, redis: redisClient });
     const result = await agent.process({ question, jobId, userId }, { jobId });
 
     if (result.status === 'failed') {
@@ -251,14 +245,13 @@ router.post('/query', async (req, res, next) => {
   }
 });
 
+// ── POST /explain/stream ────────────────────────────────────────────────────
 router.post('/explain/stream', async (req, res, next) => {
   const authUser = getAuthUser(req);
-  if (!authUser?.id) {
-    return res.status(401).json({ error: 'Authentication required.' });
-  }
+  if (!authUser?.id) return res.status(401).json({ error: 'Authentication required.' });
 
   const question = String(req.body?.question || '').trim();
-  const jobId = String(req.body?.jobId || '').trim();
+  const jobId    = String(req.body?.jobId    || '').trim();
 
   if (!question || !jobId) {
     return res.status(400).json({ error: 'question and jobId are required.' });
@@ -268,51 +261,58 @@ router.post('/explain/stream', async (req, res, next) => {
     return res.status(503).json({ error: 'AI provider is not configured for streaming.' });
   }
 
-  let clientClosed = false;
+  let clientClosed  = false;
   let streamSession = null;
 
-  const closeStream = () => {
-    streamSession?.cancel?.();
-  };
-
-  const writeEvent = (payload) => {
+  const closeStream = () => { streamSession?.cancel?.(); };
+  const writeEvent  = (payload) => {
     if (clientClosed || res.writableEnded) return;
     res.write(`data: ${JSON.stringify(payload)}\n\n`);
   };
 
-  req.on('close', () => {
-    clientClosed = true;
-    closeStream();
-  });
+  req.on('close', () => { clientClosed = true; closeStream(); });
 
   try {
     const userId = await resolveDatabaseUserId(authUser);
-    if (!userId) {
-      return res.status(500).json({ error: 'Failed to resolve authenticated user.' });
-    }
+    if (!userId) return res.status(500).json({ error: 'Failed to resolve authenticated user.' });
 
     const ownership = await pgPool.query(
-      `
-        SELECT 1
-        FROM analysis_jobs
-        WHERE id = $1 AND user_id = $2
-        LIMIT 1
-      `,
+      `SELECT 1 FROM analysis_jobs WHERE id = $1 AND user_id = $2 LIMIT 1`,
       [jobId, userId],
     );
-
     if (ownership.rowCount === 0) {
       return res.status(404).json({ error: 'Analysis job not found for this user.' });
     }
 
+    // BUG 5 FIX: check Redis cache before hitting the AI provider
+    const cacheKey = streamCacheKey(jobId, question);
+    let cachedText = null;
+    try { cachedText = await redisClient.get(cacheKey); } catch { /* cache miss */ }
+
+    if (cachedText) {
+      // Serve from cache as a single SSE chunk — instant, zero API calls
+      res.status(200);
+      res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
+      res.setHeader('Cache-Control', 'no-cache, no-transform');
+      res.setHeader('Connection', 'keep-alive');
+      res.setHeader('X-Cache', 'HIT');
+      if (typeof res.flushHeaders === 'function') res.flushHeaders();
+      res.write(`data: ${JSON.stringify({ text: cachedText })}\n\n`);
+      res.write('data: [DONE]\n\n');
+      res.end();
+      return;
+    }
+
+    // Cache miss — stream from AI provider
     res.status(200);
     res.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
     res.setHeader('Cache-Control', 'no-cache, no-transform');
     res.setHeader('Connection', 'keep-alive');
     res.setHeader('X-Accel-Buffering', 'no');
-    if (typeof res.flushHeaders === 'function') {
-      res.flushHeaders();
-    }
+    res.setHeader('X-Cache', 'MISS');
+    if (typeof res.flushHeaders === 'function') res.flushHeaders();
+
+    let fullText = '';
 
     streamSession = await chatClient.createStream({
       model: defaultChatModel,
@@ -321,12 +321,18 @@ router.post('/explain/stream', async (req, res, next) => {
       onText: (text) => {
         if (!clientClosed) {
           writeEvent({ text });
+          fullText += text;
         }
       },
     });
 
     await streamSession.consume();
 
+    // Save to Redis after a successful stream (non-blocking)
+    if (fullText && redisClient) {
+      try { await redisClient.setex(cacheKey, STREAM_CACHE_TTL, fullText); } catch { /* best-effort */ }
+    }
+
     if (!clientClosed) {
       res.write('data: [DONE]\n\n');
       res.end();
@@ -335,7 +341,6 @@ router.post('/explain/stream', async (req, res, next) => {
     return undefined;
   } catch (error) {
     closeStream();
-
     if (res.headersSent) {
       if (!clientClosed && !res.writableEnded) {
         writeEvent({ error: error.message || 'Streaming failed.' });
@@ -343,18 +348,16 @@ router.post('/explain/stream', async (req, res, next) => {
       }
       return undefined;
     }
-
     return next(error);
   }
 });
 
+// ── POST /impact ────────────────────────────────────────────────────────────
 router.post('/impact', async (req, res, next) => {
   const authUser = getAuthUser(req);
-  if (!authUser?.id) {
-    return res.status(401).json({ error: 'Authentication required.' });
-  }
+  if (!authUser?.id) return res.status(401).json({ error: 'Authentication required.' });
 
-  const jobId = String(req.body?.jobId || '').trim();
+  const jobId    = String(req.body?.jobId    || '').trim();
   const filePath = String(req.body?.filePath || '').trim();
 
   if (!jobId || !filePath) {
@@ -364,19 +367,12 @@ router.post('/impact', async (req, res, next) => {
   try {
     const [nodesResult, edgesResult] = await Promise.all([
       pgPool.query(
-        `
-          SELECT file_path, file_type, declarations, metrics, summary
-          FROM graph_nodes
-          WHERE job_id = $1
-        `,
+        `SELECT file_path, file_type, declarations, metrics, summary
+         FROM graph_nodes WHERE job_id = $1`,
         [jobId],
       ),
       pgPool.query(
-        `
-          SELECT source_path, target_path
-          FROM graph_edges
-          WHERE job_id = $1
-        `,
+        `SELECT source_path, target_path FROM graph_edges WHERE job_id = $1`,
         [jobId],
       ),
     ]);
@@ -407,66 +403,63 @@ router.post('/impact', async (req, res, next) => {
 
     return res.status(200).json({
       filePath,
-      affectedFiles: result.data?.impactedFiles || [],
-      deadCodeCandidates: result.data?.deadCodeCandidates || [],
+      affectedFiles:       result.data?.impactedFiles       || [],
+      deadCodeCandidates:  result.data?.deadCodeCandidates  || [],
     });
   } catch (error) {
     return next(error);
   }
 });
 
+// ── POST /snippet-impact ────────────────────────────────────────────────────
 router.post('/snippet-impact', async (req, res, next) => {
   const authUser = getAuthUser(req);
-  if (!authUser?.id) {
-    return res.status(401).json({ error: 'Authentication required.' });
-  }
+  if (!authUser?.id) return res.status(401).json({ error: 'Authentication required.' });
 
-  const jobId = String(req.body?.jobId || '').trim();
+  const jobId    = String(req.body?.jobId    || '').trim();
   const filePath = String(req.body?.filePath || '').trim();
-  const snippet = String(req.body?.snippet || '').trim();
-  const lineStart = Number.parseInt(req.body?.lineStart, 10);
-  const lineEnd = Number.parseInt(req.body?.lineEnd, 10);
+  const snippet  = String(req.body?.snippet  || '').trim();
 
   if (!jobId || !filePath || !snippet) {
     return res.status(400).json({ error: 'jobId, filePath, and snippet are required.' });
   }
 
+  // BUG 4.2 FIX: snippet length guard
+  if (snippet.length > 8000) {
+    return res.status(400).json({ error: 'Snippet must be 8000 characters or fewer.' });
+  }
+
+  // BUG 8 FIX: safe integer parsing — never pass NaN to the agent
+  const lineStart = toSafePositiveInt(req.body?.lineStart);
+  const lineEnd   = toSafePositiveInt(req.body?.lineEnd);
+
+  // BUG 8 FIX: validate range consistency
+  if (lineStart !== undefined && lineEnd !== undefined && lineEnd < lineStart) {
+    return res.status(400).json({ error: 'lineEnd must be greater than or equal to lineStart.' });
+  }
+
   try {
     const userId = await resolveDatabaseUserId(authUser);
-    if (!userId) {
-      return res.status(500).json({ error: 'Failed to resolve authenticated user.' });
-    }
+    if (!userId) return res.status(500).json({ error: 'Failed to resolve authenticated user.' });
 
     const ownership = await pgPool.query(
-      `
-        SELECT 1
-        FROM analysis_jobs
-        WHERE id = $1 AND user_id = $2
-        LIMIT 1
-      `,
+      `SELECT 1 FROM analysis_jobs WHERE id = $1 AND user_id = $2 LIMIT 1`,
       [jobId, userId],
     );
-
     if (ownership.rowCount === 0) {
       return res.status(404).json({ error: 'Analysis job not found for this user.' });
     }
 
-    const agent = new SnippetAnalyzerAgent({ db: pgPool });
+    const agent  = new SnippetAnalyzerAgent({ db: pgPool });
     const result = await agent.process(
-      {
-        jobId,
-        filePath,
-        snippet,
-        lineStart,
-        lineEnd,
-      },
+      { jobId, filePath, snippet, lineStart, lineEnd },
       { jobId },
     );
 
     if (result.status === 'failed') {
       const statusCode = Number(result.errors?.[0]?.code) || 400;
       return res.status(statusCode).json({
-        error: result.errors?.[0]?.message || 'Unable to analyze snippet impact.',
+        error:   result.errors?.[0]?.message || 'Unable to analyze snippet impact.',
         details: result.errors || [],
       });
     }
diff --git a/server/src/api/graph/routes/graph.routes.js b/server/src/api/graph/routes/graph.routes.js
index 60be2f1..0c39146 100644
--- a/server/src/api/graph/routes/graph.routes.js
+++ b/server/src/api/graph/routes/graph.routes.js
@@ -55,6 +55,11 @@ async function ensureOwnedJobAccess(req, res) {
 
   const jobId = String(req.params?.jobId || '').trim();
 
+  if (!isUuid(jobId)) {
+    res.status(404).json({ error: 'Analysis job not found.' });
+    return null;
+  }
+
   const jobCheck = await pgPool.query(
     `
       SELECT id
@@ -86,6 +91,10 @@ router.get('/:jobId/functions/*filePath', functionNodesLimiter, async (req, res,
     return res.status(400).json({ error: 'filePath is required.' });
   }
 
+  if (rawFilePath.includes('../') || rawFilePath.includes('..\\')) {
+    return res.status(400).json({ error: 'Invalid file path.' });
+  }
+
   let filePath = rawFilePath;
 
   try {
@@ -235,7 +244,8 @@ router.get('/:jobId/heatmap', async (req, res, next) => {
     const result = await pgPool.query(
       `
         SELECT file_path, file_type, metrics,
-               (metrics->>'inDegree')::int * COALESCE((metrics->>'complexity')::numeric, 1) AS risk_score
+               COALESCE((metrics->>'inDegree')::numeric, 0)
+                 * COALESCE((metrics->>'complexity')::numeric, 1.0) AS risk_score
         FROM graph_nodes
         WHERE job_id = $1
         ORDER BY risk_score DESC
diff --git a/server/src/infrastructure/connections.js b/server/src/infrastructure/connections.js
index dd2ef29..97c3e45 100644
--- a/server/src/infrastructure/connections.js
+++ b/server/src/infrastructure/connections.js
@@ -1,53 +1,58 @@
-import { Pool } from 'pg';
-import Redis from 'ioredis';
+import { Pool } from "pg";
+import Redis from "ioredis";
 
-const databaseUrl = process.env.DATABASE_URL || 'postgres://postgres:postgres@localhost:5433/codegraph';
+const databaseUrl =
+  process.env.DATABASE_URL ||
+  "postgres://postgres:postgres@localhost:5433/codegraph";
+const pgPoolMax = Number.parseInt(process.env.PG_POOL_MAX || "10", 10);
 
 export const pgPool = new Pool({
-	connectionString: databaseUrl,
-	max: 10,
-	idleTimeoutMillis: 30000,
+  connectionString: databaseUrl,
+  max: Number.isFinite(pgPoolMax) ? pgPoolMax : 10,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 10000,
 });
 
-pgPool.on('connect', () => {
-	console.log('Connected to Postgres');
+pgPool.on("connect", () => {
+  console.log("Connected to Postgres");
 });
 
-pgPool.on('error', (err) => {
-	console.error('Postgres pool error:', err);
+pgPool.on("error", (err) => {
+  console.error("Postgres pool error:", err);
 });
 
-const redisHost = process.env.REDIS_HOST || '127.0.0.1';
+const redisHost = process.env.REDIS_HOST || "127.0.0.1";
 const redisPort = Number(process.env.REDIS_PORT || 6379);
-const isTestRuntime = process.argv.includes('--test') || Boolean(process.env.VITEST);
+const isTestRuntime =
+  process.argv.includes("--test") || Boolean(process.env.VITEST);
 
 const redisOptions = {
-	maxRetriesPerRequest: null,
-	lazyConnect: true,
-	...(isTestRuntime
-		? {
-			retryStrategy: () => null,
-		}
-		: {}),
+  maxRetriesPerRequest: null,
+  lazyConnect: true,
+  ...(isTestRuntime
+    ? {
+        retryStrategy: () => null,
+      }
+    : {}),
 };
 
 export const redisClient = process.env.REDIS_URL
-	? new Redis(process.env.REDIS_URL, redisOptions)
-	: new Redis({
-			host: redisHost,
-			port: redisPort,
-			...redisOptions,
-		});
-
-redisClient.on('connect', () => {
-	console.log('Connected to Redis');
+  ? new Redis(process.env.REDIS_URL, redisOptions)
+  : new Redis({
+      host: redisHost,
+      port: redisPort,
+      ...redisOptions,
+    });
+
+redisClient.on("connect", () => {
+  console.log("Connected to Redis");
 });
 
-redisClient.on('error', (err) => {
-	console.error('Redis error:', err);
+redisClient.on("error", (err) => {
+  console.error("Redis error:", err);
 });
 
 export default {
-	pgPool,
-	redisClient,
+  pgPool,
+  redisClient,
 };
diff --git a/server/src/infrastructure/db/IGraphRepository.js b/server/src/infrastructure/db/IGraphRepository.js
new file mode 100644
index 0000000..6dc2463
--- /dev/null
+++ b/server/src/infrastructure/db/IGraphRepository.js
@@ -0,0 +1,56 @@
+/**
+ * Interface for Graph Repositories.
+ * All graph storage backends (Postgres, Neo4j, etc.) must implement this.
+ */
+export class IGraphRepository {
+  /**
+   * Persists the entire graph and associated metadata.
+   * @param {Object} params - The data to persist (graph, edges, embeddings, functionNodes, contracts, topology, jobId).
+   */
+  async persistGraph(params) {
+    throw new Error('Method persistGraph() must be implemented');
+  }
+
+  /**
+   * Retrieves the full graph for a given jobId.
+   * @param {string} jobId
+   */
+  async getGraph(jobId) {
+    throw new Error('Method getGraph() must be implemented');
+  }
+
+  /**
+   * Gets N-hop dependencies (outbound) for a file.
+   * @param {string} jobId
+   * @param {string} filePath
+   * @param {number} n - Number of hops.
+   */
+  async getDependencies(jobId, filePath, n) {
+    throw new Error('Method getDependencies() must be implemented');
+  }
+
+  /**
+   * Gets N-hop impacted files (inbound) for a file.
+   * @param {string} jobId
+   * @param {string} filePath
+   * @param {number} n - Number of hops.
+   */
+  async getImpactedFiles(jobId, filePath, n) {
+    throw new Error('Method getImpactedFiles() must be implemented');
+  }
+
+  /**
+   * Checks the health/connectivity of the database.
+   */
+  async healthCheck() {
+    throw new Error('Method healthCheck() must be implemented');
+  }
+
+  /**
+   * Deletes all records associated with a jobId.
+   * @param {string} jobId
+   */
+  async deleteJob(jobId) {
+    throw new Error('Method deleteJob() must be implemented');
+  }
+}
diff --git a/server/src/infrastructure/db/Neo4jGraphRepository.js b/server/src/infrastructure/db/Neo4jGraphRepository.js
new file mode 100644
index 0000000..0ddadb7
--- /dev/null
+++ b/server/src/infrastructure/db/Neo4jGraphRepository.js
@@ -0,0 +1,247 @@
+import { IGraphRepository } from './IGraphRepository.js';
+import { PostgresGraphRepository } from './PostgresGraphRepository.js';
+import { pgPool as defaultPgPool } from '../connections.js';
+
+const VALID_RELATIONSHIPS = new Set([
+  'IMPORTS',
+  'CALLS',
+  'EXPOSES_API',
+  'CONSUMES_API',
+  'USES_TABLE',
+  'USES_FIELD',
+  'EMITS_EVENT',
+  'LISTENS_EVENT',
+]);
+
+const LABEL_MAP = {
+  EXPOSES_API:   'ApiEndpoint',
+  CONSUMES_API:  'ApiEndpoint',
+  USES_TABLE:    'DatabaseTable',
+  USES_FIELD:    'DatabaseField',
+  EMITS_EVENT:   'EventChannel',
+  LISTENS_EVENT: 'EventChannel',
+  IMPORTS:       'CodeFile',
+  CALLS:         'Symbol',
+};
+
+export class Neo4jGraphRepository extends IGraphRepository {
+  constructor(driverOrOptions = {}) {
+    super();
+    const options =
+      driverOrOptions &&
+      typeof driverOrOptions === 'object' &&
+      'session' in driverOrOptions
+        ? { driver: driverOrOptions }
+        : driverOrOptions;
+
+    this.driver = options.driver;
+    this.pgRepo =
+      options.pgRepo ||
+      new PostgresGraphRepository(options.pgPool || defaultPgPool);
+  }
+
+  // ── Internal helper: open a session, run fn, always close session ───────
+  async _withSession(fn, { write = true } = {}) {
+    const session = this.driver.session();
+    try {
+      return await fn(session);
+    } finally {
+      await session.close();
+    }
+  }
+
+  // ── persistGraph ─────────────────────────────────────────────────────────
+  async persistGraph(params) {
+    const { jobId, graph = {}, typedEdges = [], topology = {} } = params;
+
+    // 1. Write everything to Postgres first (write-through — always the source of truth)
+    await this.pgRepo.persistGraph(params);
+
+    // 2. Seed Neo4j graph structure
+    await this._withSession(async (session) => {
+      // 2.1 AnalysisJob node
+      await session.run(
+        `MERGE (j:AnalysisJob { jobId: $jobId })
+         SET j.repositoryId = $repositoryId,
+             j.status       = $status,
+             j.nodeCount    = $nodeCount,
+             j.edgeCount    = $edgeCount,
+             j.updatedAt    = datetime()`,
+        {
+          jobId,
+          repositoryId: params.repositoryId || 'unknown',
+          status:       'completed',
+          nodeCount:    topology.nodeCount || 0,
+          edgeCount:    topology.edgeCount || 0,
+        },
+      );
+
+      // 2.2 CodeFile nodes in batches of 100
+      const fileEntries = Object.entries(graph);
+      const deadCodeSet = new Set(topology.deadCodeCandidates || []);
+      const FILE_BATCH  = 100;
+
+      for (let i = 0; i < fileEntries.length; i += FILE_BATCH) {
+        const batch = fileEntries.slice(i, i + FILE_BATCH).map(([filePath, node]) => ({
+          path:     filePath,
+          type:     node?.type     || 'module',
+          language: node?.language || 'unknown',
+          isDead:   deadCodeSet.has(filePath),
+          jobId,
+        }));
+
+        await session.run(
+          `UNWIND $batch AS item
+           MERGE (f:CodeFile { jobId: item.jobId, path: item.path })
+           SET f.type     = item.type,
+               f.language = item.language,
+               f.isDead   = item.isDead`,
+          { batch },
+        );
+      }
+
+      // 2.3 Typed relationships in batches of 200
+      const edges      = typedEdges.filter((e) => VALID_RELATIONSHIPS.has(e.type));
+      const EDGE_BATCH = 200;
+
+      for (let i = 0; i < edges.length; i += EDGE_BATCH) {
+        const batch  = edges.slice(i, i + EDGE_BATCH);
+        const byType = {};
+        for (const edge of batch) {
+          (byType[edge.type] = byType[edge.type] || []).push(edge);
+        }
+
+        for (const [relType, typeEdges] of Object.entries(byType)) {
+          const targetLabel = LABEL_MAP[relType] || 'Node';
+
+          // Handle CALLS relationships (Symbol nodes) with special constraint properties
+          if (relType === 'CALLS') {
+            const processedEdges = typeEdges.map((e) => {
+              const [prefix, name] = e.target.split(':');
+              return {
+                source: e.source,
+                target: e.target,
+                symbolName: name || e.target,
+                symbolKind: 'function',
+              };
+            });
+
+            await session.run(
+              `UNWIND $edges AS e
+               MERGE (src:CodeFile { jobId: $jobId, path: e.source })
+               MERGE (tgt:Symbol { jobId: $jobId, filePath: e.source, name: e.symbolName, kind: e.symbolKind })
+               MERGE (src)-[:\`${relType}\` { jobId: $jobId }]->(tgt)`,
+              { edges: processedEdges, jobId },
+            );
+          } else {
+            // For other relationships, use the original path-based merge
+            await session.run(
+              `UNWIND $edges AS e
+               MERGE (src:CodeFile { jobId: $jobId, path: e.source })
+               MERGE (tgt:\`${targetLabel}\` { jobId: $jobId, path: e.target })
+               MERGE (src)-[:\`${relType}\` { jobId: $jobId }]->(tgt)`,
+              { edges: typeEdges, jobId },
+            );
+          }
+        }
+      }
+    });
+  }
+
+  // ── getGraph ─────────────────────────────────────────────────────────────
+  // BUG 9 FIX: this method was missing — threw "Method getGraph() must be implemented"
+  async getGraph(jobId) {
+    return this._withSession(async (session) => {
+      const result = await session.run(
+        `MATCH (f:CodeFile { jobId: $jobId })
+         OPTIONAL MATCH (f)-[:IMPORTS]->(dep:CodeFile { jobId: $jobId })
+         RETURN
+           f.path     AS src,
+           f.type     AS type,
+           f.isDead   AS isDead,
+           f.language AS language,
+           collect(dep.path) AS deps`,
+        { jobId },
+      );
+
+      const nodes = [];
+      const edges = [];
+
+      for (const rec of result.records) {
+        const src = rec.get('src');
+        nodes.push({
+          id:       src,
+          type:     rec.get('type'),
+          isDead:   rec.get('isDead'),
+          language: rec.get('language'),
+        });
+        for (const dep of rec.get('deps') || []) {
+          if (dep) edges.push({ source: src, target: dep, type: 'IMPORTS' });
+        }
+      }
+
+      return { nodes, edges };
+    }, { write: false });
+  }
+
+  // ── getDependencies ───────────────────────────────────────────────────────
+  // Outbound: files that filePath imports (directly or transitively)
+  async getDependencies(jobId, filePath, n = 5) {
+    return this._withSession(async (session) => {
+      const result = await session.run(
+        `MATCH path = (start:CodeFile { jobId: $jobId, path: $filePath })
+                      -[:IMPORTS*1..${n}]->(dep:CodeFile { jobId: $jobId })
+         RETURN DISTINCT dep.path AS path, length(path) AS depth
+         ORDER BY depth, dep.path`,
+        { jobId, filePath },
+      );
+      return result.records.map((r) => ({
+        path:  String(r.get('path')),
+        depth: r.get('depth')?.toNumber?.() ?? r.get('depth'),
+      }));
+    }, { write: false });
+  }
+
+  // ── getImpactedFiles ──────────────────────────────────────────────────────
+  // Inbound: files that depend on filePath (directly or transitively)
+  async getImpactedFiles(jobId, filePath, n = 5) {
+    return this._withSession(async (session) => {
+      const result = await session.run(
+        `MATCH path = (dep:CodeFile { jobId: $jobId })
+                      -[:IMPORTS*1..${n}]->
+                      (changed:CodeFile { jobId: $jobId, path: $filePath })
+         RETURN DISTINCT dep.path AS path, length(path) AS depth
+         ORDER BY depth, dep.path`,
+        { jobId, filePath },
+      );
+      return result.records.map((r) => ({
+        path:  String(r.get('path')),
+        depth: r.get('depth')?.toNumber?.() ?? r.get('depth'),
+      }));
+    }, { write: false });
+  }
+
+  // ── healthCheck ───────────────────────────────────────────────────────────
+  async healthCheck() {
+    try {
+      await this.driver.verifyConnectivity();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // ── deleteJob ─────────────────────────────────────────────────────────────
+  async deleteJob(jobId) {
+    // Remove all Neo4j nodes associated with this job
+    await this._withSession(async (session) => {
+      await session.run(
+        `MATCH (n { jobId: $jobId }) DETACH DELETE n`,
+        { jobId },
+      );
+    });
+
+    // Also delete from Postgres (write-through parity)
+    await this.pgRepo.deleteJob(jobId);
+  }
+}
diff --git a/server/src/infrastructure/db/PostgresGraphRepository.js b/server/src/infrastructure/db/PostgresGraphRepository.js
new file mode 100644
index 0000000..0504e06
--- /dev/null
+++ b/server/src/infrastructure/db/PostgresGraphRepository.js
@@ -0,0 +1,224 @@
+import { IGraphRepository } from './IGraphRepository.js';
+
+function toJson(value, fallback) {
+  if (value === undefined || value === null) return JSON.stringify(fallback);
+  return JSON.stringify(value);
+}
+
+function toVectorLiteral(embedding) {
+  if (!Array.isArray(embedding) || embedding.length === 0) return null;
+  const normalized = embedding
+    .map((v) => Number(v))
+    .filter((v) => Number.isFinite(v));
+  if (normalized.length === 0) return null;
+  return `[${normalized.join(',')}]`;
+}
+
+export class PostgresGraphRepository extends IGraphRepository {
+  constructor(pgPool) {
+    super();
+    this.pgPool = pgPool;
+  }
+
+  async persistGraph(params) {
+    const { jobId, graph = {}, typedEdges = [], edges = [], embeddings = {}, functionNodes = {}, contracts = {}, topology = {} } = params;
+    
+    if (!jobId) throw new Error('PostgresGraphRepository.persistGraph requires a jobId.');
+
+    const client = await this.pgPool.connect();
+    try {
+      await client.query('BEGIN');
+
+      // 1. Nodes
+      const nodePaths = [], nodeTypes = [], nodeDeclarations = [], nodeMetrics = [], nodeSummaries = [], nodeDeadFlags = [];
+      const deadCodeSet = new Set(Array.isArray(topology.deadCodeCandidates) ? topology.deadCodeCandidates : []);
+      
+      for (const [path, node] of Object.entries(graph)) {
+        nodePaths.push(path);
+        nodeTypes.push(node?.type || 'module');
+        nodeDeclarations.push(toJson(node?.declarations, []));
+        nodeMetrics.push(toJson(node?.metrics, {}));
+        nodeSummaries.push(params.enriched?.[path]?.summary || null);
+        nodeDeadFlags.push(deadCodeSet.has(path));
+      }
+
+      if (nodePaths.length > 0) {
+        await client.query(
+          `INSERT INTO graph_nodes (job_id, file_path, file_type, declarations, metrics, summary, is_dead_code)
+           SELECT $1, unnest($2::text[]), unnest($3::text[]), unnest($4::jsonb[]), unnest($5::jsonb[]), unnest($6::text[]), unnest($7::boolean[])
+           ON CONFLICT (job_id, file_path) DO UPDATE SET file_type = EXCLUDED.file_type, declarations = EXCLUDED.declarations, metrics = EXCLUDED.metrics, summary = EXCLUDED.summary, is_dead_code = EXCLUDED.is_dead_code`,
+          [jobId, nodePaths, nodeTypes, nodeDeclarations, nodeMetrics, nodeSummaries, nodeDeadFlags]
+        );
+      }
+
+      // 2. Edges
+      const edgeSourcePaths = [], edgeTargetPaths = [], edgeTypes = [];
+      const edgesToPersist = typedEdges.length > 0 ? typedEdges : edges;
+      for (const edge of edgesToPersist) {
+        if (!edge?.source || !edge?.target) continue;
+        edgeSourcePaths.push(edge.source);
+        edgeTargetPaths.push(edge.target);
+        edgeTypes.push(edge.type || 'import');
+      }
+
+      if (edgeSourcePaths.length > 0) {
+        await client.query(
+          `INSERT INTO graph_edges (job_id, source_path, target_path, edge_type)
+           SELECT $1, unnest($2::text[]), unnest($3::text[]), unnest($4::text[])
+           ON CONFLICT (job_id, source_path, target_path, edge_type) DO NOTHING`,
+          [jobId, edgeSourcePaths, edgeTargetPaths, edgeTypes]
+        );
+      }
+
+      // 3. Embeddings
+      const embeddingPaths = [], embeddingVectors = [];
+      for (const [path, vector] of Object.entries(embeddings)) {
+        const literal = toVectorLiteral(vector);
+        if (literal) {
+          embeddingPaths.push(path);
+          embeddingVectors.push(literal);
+        }
+      }
+
+      if (embeddingPaths.length > 0) {
+        await client.query(
+          `INSERT INTO file_embeddings (job_id, file_path, embedding)
+           SELECT $1, t.file_path, t.embedding::vector FROM unnest($2::text[], $3::text[]) AS t(file_path, embedding)
+           ON CONFLICT (job_id, file_path) DO UPDATE SET embedding = EXCLUDED.embedding`,
+          [jobId, embeddingPaths, embeddingVectors]
+        );
+      }
+
+      // 4. Function Nodes
+      const fnPaths = [], fnNames = [], fnKinds = [], fnCalls = [], fnLocs = [];
+      for (const [path, declarations] of Object.entries(functionNodes)) {
+        if (!Array.isArray(declarations)) continue;
+        for (const dec of declarations) {
+          if (!dec.name) continue;
+          fnPaths.push(path);
+          fnNames.push(dec.name);
+          fnKinds.push(dec.kind || 'function');
+          fnCalls.push(toJson(dec.calls, []));
+          fnLocs.push(dec.loc ?? null);
+        }
+      }
+
+      if (fnPaths.length > 0) {
+        await client.query(
+          `INSERT INTO function_nodes (job_id, file_path, name, kind, calls, loc)
+           SELECT $1, unnest($2::text[]), unnest($3::text[]), unnest($4::text[]), unnest($5::jsonb[]), unnest($6::integer[])
+           ON CONFLICT (job_id, file_path, name) DO UPDATE SET kind = EXCLUDED.kind, calls = EXCLUDED.calls, loc = EXCLUDED.loc`,
+          [jobId, fnPaths, fnNames, fnKinds, fnCalls, fnLocs]
+        );
+      }
+
+      // 5. Contracts
+      const cPaths = [], cRoutes = [], cEnvDeps = [], cExtServices = [], cCaching = [];
+      for (const [path, contract] of Object.entries(contracts)) {
+        cPaths.push(path);
+        cRoutes.push(toJson(contract?.routes, []));
+        cEnvDeps.push(toJson(contract?.envDependencies, []));
+        cExtServices.push(toJson(contract?.externalServices, []));
+        cCaching.push(toJson(contract?.cachingPatterns, []));
+      }
+
+      if (cPaths.length > 0) {
+        await client.query(
+          `INSERT INTO api_contracts (job_id, file_path, routes, env_deps, ext_services, caching)
+           SELECT $1, unnest($2::text[]), unnest($3::jsonb[]), unnest($4::jsonb[]), unnest($5::jsonb[]), unnest($6::jsonb[])
+           ON CONFLICT (job_id, file_path) DO UPDATE SET routes = EXCLUDED.routes, env_deps = EXCLUDED.env_deps, ext_services = EXCLUDED.ext_services, caching = EXCLUDED.caching`,
+          [jobId, cPaths, cRoutes, cEnvDeps, cExtServices, cCaching]
+        );
+      }
+
+      await client.query('COMMIT');
+    } catch (err) {
+      await client.query('ROLLBACK');
+      throw err;
+    } finally {
+      client.release();
+    }
+  }
+
+  async getDependencies(jobId, filePath, n = 3) {
+    const result = await this.pgPool.query(
+      `SELECT source_path, target_path FROM graph_edges WHERE job_id = $1`,
+      [jobId]
+    );
+
+    const adj = new Map();
+    for (const row of result.rows) {
+      if (!adj.has(row.source_path)) adj.set(row.source_path, []);
+      adj.get(row.source_path).push(row.target_path);
+    }
+
+    const dependencies = new Set();
+    const visited = new Set([filePath]);
+    let current = [filePath];
+    let depth = 0;
+
+    while (current.length > 0 && depth < n) {
+      const next = [];
+      for (const file of current) {
+        for (const dep of adj.get(file) || []) {
+          if (!visited.has(dep)) {
+            visited.add(dep);
+            dependencies.add(dep);
+            next.push(dep);
+          }
+        }
+      }
+      current = next;
+      depth++;
+    }
+
+    return Array.from(dependencies);
+  }
+
+  async getImpactedFiles(jobId, filePath, n = 3) {
+    const result = await this.pgPool.query(
+      `SELECT source_path, target_path FROM graph_edges WHERE job_id = $1`,
+      [jobId]
+    );
+
+    const reverseAdj = new Map();
+    for (const row of result.rows) {
+      if (!reverseAdj.has(row.target_path)) reverseAdj.set(row.target_path, []);
+      reverseAdj.get(row.target_path).push(row.source_path);
+    }
+
+    const impacted = new Set();
+    const visited = new Set([filePath]);
+    let current = [filePath];
+    let depth = 0;
+
+    while (current.length > 0 && depth < n) {
+      const next = [];
+      for (const file of current) {
+        for (const dep of reverseAdj.get(file) || []) {
+          if (!visited.has(dep)) {
+            visited.add(dep);
+            impacted.add(dep);
+            next.push(dep);
+          }
+        }
+      }
+      current = next;
+      depth++;
+    }
+
+    return Array.from(impacted);
+  }
+
+  async healthCheck() {
+    await this.pgPool.query('SELECT 1');
+    return true;
+  }
+
+  async deleteJob(jobId) {
+    const tables = ['graph_nodes', 'graph_edges', 'file_embeddings', 'function_nodes', 'api_contracts'];
+    for (const table of tables) {
+      await this.pgPool.query(`DELETE FROM ${table} WHERE job_id = $1`, [jobId]);
+    }
+  }
+}
diff --git a/server/src/infrastructure/db/dbSelector.js b/server/src/infrastructure/db/dbSelector.js
new file mode 100644
index 0000000..8711794
--- /dev/null
+++ b/server/src/infrastructure/db/dbSelector.js
@@ -0,0 +1,75 @@
+/**
+ * Thresholds for choosing Neo4j over Postgres as the primary graph store.
+ */
+const THRESHOLDS = {
+  NODE_COUNT: Number.parseInt(process.env.NEO4J_THRESHOLD_NODES ?? "500", 10),
+  EDGE_COUNT: Number.parseInt(process.env.NEO4J_THRESHOLD_EDGES ?? "2000", 10),
+  DENSITY: Number.parseFloat(process.env.NEO4J_THRESHOLD_DENSITY ?? "0.05"),
+  CYCLES: Number.parseInt(process.env.NEO4J_THRESHOLD_CYCLES ?? "20", 10),
+  IMPACT_HOPS: 5,
+  LARGE_CYCLE_SIZE: 50,
+  RELATIONSHIP_TYPES: 3,
+};
+
+/**
+ * Dynamically selects the database backend based on graph topology metrics.
+ *
+ * @param {Object} topology - Metrics from GraphBuilderAgent.
+ * @param {Object} options - Manual overrides (forceNeo4j, forcePostgres).
+ * @returns {Object} { db: 'neo4j' | 'postgres', reasons: string[] }
+ */
+export function selectDatabase(topology, options = {}) {
+  const reasons = [];
+  const safeTopology = topology && typeof topology === "object" ? topology : {};
+
+  if (options.forceNeo4j) return { db: "neo4j", reasons: ["manual override"] };
+  if (options.forcePostgres)
+    return { db: "postgres", reasons: ["manual override"] };
+
+  const {
+    nodeCount = 0,
+    edgeCount = 0,
+    cyclesDetected = 0,
+    relationshipTypeCount = 0,
+    distinctRelationshipTypes = 0,
+    largestCycleSize = 0,
+    maxCycleSize = 0,
+  } = safeTopology;
+
+  const density = edgeCount / (nodeCount * (nodeCount - 1) || 1);
+  const resolvedRelationshipTypeCount = Math.max(
+    Number(relationshipTypeCount) || 0,
+    Number(distinctRelationshipTypes) || 0,
+  );
+  const resolvedLargestCycleSize = Math.max(
+    Number(largestCycleSize) || 0,
+    Number(maxCycleSize) || 0,
+  );
+
+  if (nodeCount >= THRESHOLDS.NODE_COUNT) {
+    reasons.push("nodeCount");
+  }
+  if (edgeCount >= THRESHOLDS.EDGE_COUNT) {
+    reasons.push("edgeCount");
+  }
+  if (density >= THRESHOLDS.DENSITY) {
+    reasons.push("density");
+  }
+  if (cyclesDetected >= THRESHOLDS.CYCLES) {
+    reasons.push("cyclesDetected");
+  }
+  if (Number(options.impactAnalysisDepth) > THRESHOLDS.IMPACT_HOPS) {
+    reasons.push("impactAnalysisDepth");
+  }
+  if (resolvedLargestCycleSize > THRESHOLDS.LARGE_CYCLE_SIZE) {
+    reasons.push("largestCycleSize");
+  }
+  if (resolvedRelationshipTypeCount > THRESHOLDS.RELATIONSHIP_TYPES) {
+    reasons.push("relationshipTypeCount");
+  }
+
+  return {
+    db: reasons.length > 0 ? "neo4j" : "postgres",
+    reasons,
+  };
+}
diff --git a/server/src/infrastructure/db/graphRepositoryFactory.js b/server/src/infrastructure/db/graphRepositoryFactory.js
new file mode 100644
index 0000000..721967b
--- /dev/null
+++ b/server/src/infrastructure/db/graphRepositoryFactory.js
@@ -0,0 +1,27 @@
+import { selectDatabase } from './dbSelector.js';
+import { PostgresGraphRepository } from './PostgresGraphRepository.js';
+import { Neo4jGraphRepository } from './Neo4jGraphRepository.js';
+import { pgPool } from '../connections.js';
+import { getNeo4jDriver } from './neo4jDriver.js';
+
+/**
+ * Creates a repository instance based on topology metrics and database availability.
+ *
+ * @param {Object} topology - Metrics from GraphBuilderAgent.
+ * @param {Object} options - Manual overrides and additional settings.
+ * @returns {IGraphRepository}
+ */
+export function createGraphRepository(topology, options = {}) {
+  const { db, reasons } = selectDatabase(topology, options);
+
+  console.log(`[GraphRepositoryFactory] Selecting database: ${db}`, reasons);
+
+  if (db === 'neo4j') {
+    return new Neo4jGraphRepository({
+      driver: getNeo4jDriver(),
+      pgPool, // metadata still goes to Postgres
+    });
+  }
+
+  return new PostgresGraphRepository(pgPool);
+}
diff --git a/server/src/infrastructure/db/migrate.js b/server/src/infrastructure/db/migrate.js
new file mode 100644
index 0000000..2b9e301
--- /dev/null
+++ b/server/src/infrastructure/db/migrate.js
@@ -0,0 +1,159 @@
+import path from 'path';
+import { promises as fs } from 'fs';
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'url';
+import { getNeo4jDriver } from './neo4jDriver.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: path.join(__dirname, '../../../.env') });
+
+const MIGRATIONS_DIR = path.join(process.cwd(), 'src/infrastructure/db/migrations');
+
+/**
+ * Ensures the migration tracking constraint exists.
+ */
+async function ensureMigrationConstraint(session) {
+  await session.run(`
+    CREATE CONSTRAINT neo4j_migration_version IF NOT EXISTS
+    FOR (m:__Neo4jMigration) REQUIRE m.version IS UNIQUE
+  `);
+}
+
+/**
+ * Returns a Set of already-applied migration version strings (e.g. "V001").
+ */
+async function getAppliedMigrations(session) {
+  const result = await session.run(`
+    MATCH (m:__Neo4jMigration)
+    RETURN m.version AS version
+  `);
+  return new Set(result.records.map((r) => r.get('version')));
+}
+
+/**
+ * Marks a migration version as applied in Neo4j.
+ */
+async function markApplied(session, version, filename) {
+  await session.run(
+    `MERGE (m:__Neo4jMigration { version: $version })
+     SET m.filename = $filename, m.appliedAt = datetime()`,
+    { version, filename },
+  );
+}
+
+/**
+ * Splits a Cypher migration file into individual executable statements.
+ *
+ * Strategy:
+ *  1. Strip // and /* line comments per line.
+ *  2. Split on semicolons (with optional trailing whitespace/newline).
+ *  3. Fall back to splitting on two-or-more consecutive blank lines.
+ *  4. Trim and discard empty fragments.
+ *
+ * This handles both semicolon-terminated files AND the legacy blank-line style.
+ */
+function splitStatements(cypher) {
+  // Strip single-line comments (// ...) — preserve the newline
+  const stripped = cypher
+    .split('\n')
+    .map((line) => {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*')) {
+        return '';
+      }
+      return line;
+    })
+    .join('\n');
+
+  // Try semicolon splitting first (preferred)
+  if (stripped.includes(';')) {
+    return stripped
+      .split(/;\s*\n?/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+
+  // Fall back to double-newline splitting (legacy format)
+  return stripped
+    .split(/\n{2,}/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Runs all pending Neo4j migrations from MIGRATIONS_DIR.
+ * Only .cypher files matching V###__*.cypher are considered.
+ * Already-applied migrations (tracked in :__Neo4jMigration nodes) are skipped.
+ */
+export async function runMigrations() {
+  const driver = getNeo4jDriver();
+  const session = driver.session();
+
+  try {
+    console.log('[Neo4jMigration] Starting migration run...');
+    await ensureMigrationConstraint(session);
+
+    const applied = await getAppliedMigrations(session);
+
+    // Ensure the directory exists (first-run safety)
+    try {
+      await fs.mkdir(MIGRATIONS_DIR, { recursive: true });
+    } catch {
+      // Directory already exists — ignore
+    }
+
+    const files = (await fs.readdir(MIGRATIONS_DIR))
+      .filter((f) => f.endsWith('.cypher'))
+      .sort(); // lexicographic sort preserves V001 < V002 < V003 order
+
+    if (files.length === 0) {
+      console.log('[Neo4jMigration] No .cypher migration files found.');
+      return;
+    }
+
+    for (const filename of files) {
+      const version = filename.split('__')[0]; // "V001" from "V001__initial_schema.cypher"
+
+      if (applied.has(version)) {
+        console.log(`[Neo4jMigration] Skipping ${filename} (already applied)`);
+        continue;
+      }
+
+      console.log(`[Neo4jMigration] Applying ${filename}...`);
+      const cypher = await fs.readFile(path.join(MIGRATIONS_DIR, filename), 'utf8');
+      const stmts = splitStatements(cypher);
+
+      if (stmts.length === 0) {
+        console.warn(`[Neo4jMigration] ${filename} produced no executable statements — skipping`);
+        continue;
+      }
+
+      for (const stmt of stmts) {
+        try {
+          await session.run(stmt);
+        } catch (err) {
+          // "already exists" errors are safe to ignore (idempotent migrations)
+          if (
+            err.message?.includes('already exists') ||
+            err.message?.includes('EquivalentSchemaRuleAlreadyExists')
+          ) {
+            console.log(`[Neo4jMigration]   (idempotent skip) ${err.message.split('\n')[0]}`);
+          } else {
+            console.error(`[Neo4jMigration] Failed statement in ${filename}:`, err.message);
+            throw err;
+          }
+        }
+      }
+
+      await markApplied(session, version, filename);
+      console.log(`[Neo4jMigration] Successfully applied ${filename}`);
+    }
+
+    console.log('[Neo4jMigration] All migrations completed.');
+  } catch (err) {
+    console.error('[Neo4jMigration] Migration run failed:', err.message);
+    throw err;
+  } finally {
+    await session.close();
+  }
+}
\ No newline at end of file
diff --git a/server/src/infrastructure/db/migrations/V001__initial_schema.cypher b/server/src/infrastructure/db/migrations/V001__initial_schema.cypher
new file mode 100644
index 0000000..c7725e0
--- /dev/null
+++ b/server/src/infrastructure/db/migrations/V001__initial_schema.cypher
@@ -0,0 +1,58 @@
+// V001__initial_schema.cypher
+// CodeGraph AI — Initial Neo4j Schema
+// Compatible with Neo4j Community Edition 5.x
+// Each statement is terminated with a semicolon so migrate.js splits correctly.
+
+// ── Migration tracking ────────────────────────────────────────────────────
+CREATE CONSTRAINT neo4j_migration_version IF NOT EXISTS
+FOR (m:__Neo4jMigration) REQUIRE m.version IS UNIQUE;
+
+// ── AnalysisJob ───────────────────────────────────────────────────────────
+CREATE CONSTRAINT job_unique IF NOT EXISTS
+FOR (j:AnalysisJob) REQUIRE j.jobId IS UNIQUE;
+
+// ── CodeFile: composite uniqueness (jobId + path) ────────────────────────
+// NOTE: IS NODE KEY is Enterprise-only. We use IS UNIQUE (Community-compatible).
+CREATE CONSTRAINT codefile_composite IF NOT EXISTS
+FOR (f:CodeFile) REQUIRE (f.jobId, f.path) IS UNIQUE;
+
+// ── Symbol (function / class / variable) ─────────────────────────────────
+CREATE CONSTRAINT symbol_composite IF NOT EXISTS
+FOR (s:Symbol) REQUIRE (s.jobId, s.filePath, s.name, s.kind) IS UNIQUE;
+
+// ── ApiEndpoint ───────────────────────────────────────────────────────────
+CREATE CONSTRAINT apiendpoint_composite IF NOT EXISTS
+FOR (a:ApiEndpoint) REQUIRE (a.jobId, a.path) IS UNIQUE;
+
+// ── DatabaseTable ─────────────────────────────────────────────────────────
+CREATE CONSTRAINT dbtable_composite IF NOT EXISTS
+FOR (t:DatabaseTable) REQUIRE (t.jobId, t.name) IS UNIQUE;
+
+// ── EventChannel ──────────────────────────────────────────────────────────
+CREATE CONSTRAINT eventchannel_composite IF NOT EXISTS
+FOR (e:EventChannel) REQUIRE (e.jobId, e.name) IS UNIQUE;
+
+// ── Performance indexes ───────────────────────────────────────────────────
+// Most queries filter by jobId first — this is the most important index.
+CREATE INDEX codefile_jobId IF NOT EXISTS
+FOR (f:CodeFile) ON (f.jobId);
+
+// File type filter (component | service | util | etc.)
+CREATE INDEX codefile_type IF NOT EXISTS
+FOR (f:CodeFile) ON (f.type);
+
+// Dead code queries
+CREATE INDEX codefile_dead IF NOT EXISTS
+FOR (f:CodeFile) ON (f.isDead);
+
+// Symbol lookup by name (used in impact analysis and CALLS traversal)
+CREATE INDEX symbol_name IF NOT EXISTS
+FOR (s:Symbol) ON (s.name);
+
+// Symbol kind filter (function | class | variable)
+CREATE INDEX symbol_kind IF NOT EXISTS
+FOR (s:Symbol) ON (s.kind);
+
+// Job status index (used in dashboard queries)
+CREATE INDEX job_status IF NOT EXISTS
+FOR (j:AnalysisJob) ON (j.status);
diff --git a/server/src/infrastructure/db/neo4jDriver.js b/server/src/infrastructure/db/neo4jDriver.js
new file mode 100644
index 0000000..8b15dd5
--- /dev/null
+++ b/server/src/infrastructure/db/neo4jDriver.js
@@ -0,0 +1,50 @@
+import neo4j from 'neo4j-driver';
+
+let _driver = null;
+
+/**
+ * Returns a singleton Neo4j driver instance.
+ * @returns {neo4j.Driver}
+ */
+export function getNeo4jDriver() {
+  if (_driver) return _driver;
+
+  const uri = process.env.NEO4J_URI || 'bolt://localhost:7687';
+  const user = process.env.NEO4J_USERNAME || 'neo4j';
+  const password = process.env.NEO4J_PASSWORD || 'neo4j';
+
+  _driver = neo4j.driver(uri, neo4j.auth.basic(user, password), {
+    maxConnectionPoolSize: 25,
+    connectionAcquisitionTimeout: 60_000,
+    connectionTimeout: 30_000,
+    // Keep connections warm — Aura idles them out faster than local
+    connectionLivenessCheckTimeout: 30_000,
+  });
+
+  return _driver;
+}
+
+/**
+ * Closes the singleton driver instance.
+ */
+export async function closeNeo4jDriver() {
+  if (_driver) {
+    await _driver.close();
+    _driver = null;
+  }
+}
+
+/**
+ * Verifies connectivity to the Neo4j cluster.
+ * @returns {Promise<boolean>}
+ */
+export async function verifyNeo4jConnectivity() {
+  try {
+    const driver = getNeo4jDriver();
+    await driver.verifyConnectivity();
+    return true;
+  } catch (err) {
+    console.error('[Neo4jDriver] Connectivity verification failed:', err.message);
+    return false;
+  }
+}
diff --git a/server/src/infrastructure/db/startup.js b/server/src/infrastructure/db/startup.js
new file mode 100644
index 0000000..525702d
--- /dev/null
+++ b/server/src/infrastructure/db/startup.js
@@ -0,0 +1,54 @@
+import { pgPool } from '../connections.js';
+import { getNeo4jDriver } from './neo4jDriver.js';
+import { runMigrations } from './migrate.js';
+
+/**
+ * Bootstraps all graph infrastructure at server startup.
+ *
+ * - Verifies Postgres connectivity
+ * - If NEO4J_URI is configured:
+ *     - Verifies Neo4j connectivity
+ *     - Runs all pending .cypher migrations (idempotent — safe on every restart)
+ *
+ * Called once from index.js before the HTTP server starts accepting requests.
+ */
+export async function bootstrapGraphInfrastructure() {
+  // ── Postgres ──────────────────────────────────────────────────────────────
+  try {
+    await pgPool.query('SELECT 1');
+    console.log('[GraphInfrastructure] Postgres OK');
+  } catch (error) {
+    console.error('[GraphInfrastructure] Postgres check FAILED:', error.message);
+    // This is fatal — throw so the process exits rather than silently proceeding
+    throw error;
+  }
+
+  // ── Neo4j (optional) ──────────────────────────────────────────────────────
+  if (!process.env.NEO4J_URI) {
+    console.log('[GraphInfrastructure] NEO4J_URI not set — Neo4j disabled, using Postgres only');
+    return;
+  }
+
+  try {
+    const driver = getNeo4jDriver();
+    await driver.verifyConnectivity();
+    console.log('[GraphInfrastructure] Neo4j connected');
+  } catch (error) {
+    // Non-fatal: the dynamic selector will fall back to Postgres for all jobs
+    console.warn(
+      '[GraphInfrastructure] Neo4j unavailable — graph jobs will use Postgres:',
+      error.message,
+    );
+    return;
+  }
+
+  // Run migrations only if Neo4j is reachable
+  try {
+    await runMigrations();
+    console.log('[GraphInfrastructure] Neo4j migrations complete');
+  } catch (error) {
+    // Non-fatal: schema may already be applied from a previous run.
+    // Log prominently but don't crash the server.
+    console.error('[GraphInfrastructure] Neo4j migration FAILED (proceeding anyway):', error.message);
+  }
+}
diff --git a/server/src/infrastructure/migrations/008_db_type_column.sql b/server/src/infrastructure/migrations/008_db_type_column.sql
new file mode 100644
index 0000000..ed3a1b2
--- /dev/null
+++ b/server/src/infrastructure/migrations/008_db_type_column.sql
@@ -0,0 +1,25 @@
+-- 008_db_type_column.sql
+-- Adds a db_type column to analysis_jobs so the application can determine
+-- which graph storage backend (postgres | neo4j) backs each job at retrieval
+-- time without having to probe both databases.
+--
+-- Required by:
+--   - ImpactAnalysisAgent  (routes BFS to correct backend, avoids wasted Neo4j attempts)
+--   - graph.routes.js      (can serve graph payload from the right backend)
+--   - Future: UI badge showing "Backed by Neo4j" vs "Backed by Postgres"
+
+ALTER TABLE analysis_jobs
+  ADD COLUMN IF NOT EXISTS db_type TEXT NOT NULL DEFAULT 'postgres';
+
+COMMENT ON COLUMN analysis_jobs.db_type IS
+  'Graph storage backend for this job: postgres | neo4j. '
+  'Set by SupervisorAgent immediately after createGraphRepository() runs.';
+
+-- Index for filtering/monitoring queries ("how many jobs use Neo4j?")
+CREATE INDEX IF NOT EXISTS idx_jobs_db_type
+  ON analysis_jobs (db_type);
+
+-- Backfill: existing jobs were all on Postgres (Neo4j was not active before this migration)
+UPDATE analysis_jobs
+  SET db_type = 'postgres'
+  WHERE db_type IS NULL OR db_type = '';
diff --git a/server/src/middleware/errorHandler.middleware.js b/server/src/middleware/errorHandler.middleware.js
index 6af3fb8..4c74fbf 100644
--- a/server/src/middleware/errorHandler.middleware.js
+++ b/server/src/middleware/errorHandler.middleware.js
@@ -1,17 +1,52 @@
+/**
+ * Global error handler middleware.
+ *
+ * BUG 7 FIX: normalises upstream AI provider errors (429, 503, 401) into
+ * user-actionable messages. Previously raw provider error objects leaked to
+ * the client with no guidance, and the status code defaulted to 500.
+ */
 export function errorHandler(err, _req, res, _next) {
-  const statusCode = err.statusCode ?? err.status ?? 500;
+  // Resolve status code — check all common locations upstream libs use
+  const upstreamStatus =
+    err?.status ??
+    err?.statusCode ??
+    err?.response?.status ??
+    null;
 
-  const body = {
-    error: err.message || 'Internal server error',
-  };
+  const statusCode = Number.isInteger(upstreamStatus) && upstreamStatus >= 100
+    ? upstreamStatus
+    : 500;
 
-  if (process.env.NODE_ENV === 'development' && err.stack) {
-    body.stack = err.stack;
+  let message = err?.message || 'Internal server error';
+
+  // ── User-actionable messages for known upstream AI provider errors ────────
+  if (statusCode === 429) {
+    message =
+      'AI provider quota exceeded. Add credits at platform.openai.com/billing, ' +
+      'or switch to Anthropic / Gemini by setting AI_PROVIDER in your server .env.';
+  } else if (statusCode === 503 || message.toLowerCase().includes('not configured')) {
+    message =
+      'AI provider is not configured. Set AI_API_KEY (and optionally AI_PROVIDER) ' +
+      'in your server .env file, then restart the server.';
+  } else if (statusCode === 401 && message.toLowerCase().includes('api')) {
+    message =
+      'AI API key is invalid or expired. Check AI_API_KEY in your server .env file.';
   }
 
+  // Log server errors (exclude expected 4xx)
   if (statusCode >= 500) {
-    console.error('[error]', err);
+    console.error('[errorHandler]', {
+      statusCode,
+      message: err?.message,
+      stack: err?.stack,
+    });
   }
 
-  return res.status(statusCode).json(body);
-}
+  return res.status(statusCode).json({
+    error: message,
+    // Stack trace only in development — never in production
+    ...(process.env.NODE_ENV === 'development' && err?.stack
+      ? { stack: err.stack }
+      : {}),
+  });
+}
\ No newline at end of file
diff --git a/server/test/dynamic-db-selection.test.js b/server/test/dynamic-db-selection.test.js
new file mode 100644
index 0000000..fdd4c27
--- /dev/null
+++ b/server/test/dynamic-db-selection.test.js
@@ -0,0 +1,69 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { selectDatabase } from "../src/infrastructure/db/dbSelector.js";
+import { createGraphRepository } from "../src/infrastructure/db/graphRepositoryFactory.js";
+
+test("selectDatabase prefers Postgres for small graphs", () => {
+  const result = selectDatabase({
+    nodeCount: 10,
+    edgeCount: 1,
+    cyclesDetected: 0,
+    relationshipTypeCount: 1,
+  });
+
+  assert.equal(result.db, "postgres");
+  assert.deepEqual(result.reasons, []);
+});
+
+test("selectDatabase switches to Neo4j for large topology signals", () => {
+  const result = selectDatabase({
+    nodeCount: 500,
+    edgeCount: 12475,
+    cyclesDetected: 20,
+    relationshipTypeCount: 4,
+    largestCycleSize: 51,
+  });
+
+  assert.equal(result.db, "neo4j");
+  assert.deepEqual(
+    new Set(result.reasons),
+    new Set([
+      "nodeCount",
+      "edgeCount",
+      "density",
+      "cyclesDetected",
+      "relationshipTypeCount",
+      "largestCycleSize",
+    ]),
+  );
+});
+
+test("selectDatabase respects manual overrides", () => {
+  assert.equal(
+    selectDatabase({ nodeCount: 999 }, { forcePostgres: true }).db,
+    "postgres",
+  );
+  assert.equal(
+    selectDatabase({ nodeCount: 1 }, { forceNeo4j: true }).db,
+    "neo4j",
+  );
+});
+
+test("createGraphRepository follows the selection result", () => {
+  const postgresRepo = createGraphRepository({
+    nodeCount: 10,
+    edgeCount: 1,
+    cyclesDetected: 0,
+  });
+  const neo4jRepo = createGraphRepository({
+    nodeCount: 500,
+    edgeCount: 12475,
+    cyclesDetected: 20,
+    relationshipTypeCount: 4,
+    largestCycleSize: 51,
+  });
+
+  assert.equal(postgresRepo.constructor.name, "PostgresGraphRepository");
+  assert.equal(neo4jRepo.constructor.name, "Neo4jGraphRepository");
+});
diff --git a/server/test/graph.heatmap.test.js b/server/test/graph.heatmap.test.js
index 6380fb1..c1ce1ff 100644
--- a/server/test/graph.heatmap.test.js
+++ b/server/test/graph.heatmap.test.js
@@ -1,6 +1,7 @@
 import { after, before, test } from 'node:test';
 import assert from 'node:assert/strict';
 import jwt from 'jsonwebtoken';
+import request from 'supertest';
 
 process.env.JWT_SECRET = process.env.JWT_SECRET || 'test-secret';
 process.env.DATABASE_URL =
@@ -10,8 +11,6 @@ process.env.REDIS_URL = process.env.REDIS_URL || 'redis://localhost:6379';
 let app;
 let pgPool;
 let redisClient;
-let server;
-let baseUrl;
 
 async function settleWithTimeout(promise, timeoutMs = 3000) {
   let timer;
@@ -36,30 +35,14 @@ async function settleWithTimeout(promise, timeoutMs = 3000) {
 before(async () => {
   ({ default: app } = await import('../app.js'));
   ({ pgPool, redisClient } = await import('../src/infrastructure/connections.js'));
-
-  await new Promise((resolve) => {
-    server = app.listen(0, resolve);
-  });
-
-  const address = server.address();
-  baseUrl = `http://127.0.0.1:${address.port}`;
 });
 
 after(async () => {
-  await settleWithTimeout(
-    new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error) return reject(error);
-        return resolve();
-      });
-    }),
-  );
-
   await settleWithTimeout(redisClient.quit());
   await settleWithTimeout(pgPool.end());
 });
 
-test('GET /api/graph/:jobId/heatmap returns nodes ordered by risk score', async () => {
+test('GET /api/graph/:jobId/heatmap', async () => {
   const userId = '9e4f6d7a-31e1-4d9f-8575-b9e5428eb111';
   const repositoryId = '2c4ef2f5-019e-41fd-b6f1-9652d4a7c222';
   const jobId = '14882a4f-f885-4488-8afb-7b15a2c3d333';
@@ -105,23 +88,26 @@ test('GET /api/graph/:jobId/heatmap returns nodes ordered by risk score', async
 
   try {
     const token = jwt.sign({ id: userId }, process.env.JWT_SECRET);
-    const response = await fetch(`${baseUrl}/api/graph/${jobId}/heatmap`, {
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
-    });
-    assert.equal(response.status, 200);
-
-    const payload = await response.clone().json();
-    assert.equal(Array.isArray(payload.hotspots), true);
-    assert.equal(payload.hotspots.length, 3);
-
-    assert.equal(payload.hotspots[0].filePath, 'src/high-risk.js');
-    assert.equal(payload.hotspots[0].riskScore, 28);
-    assert.equal(payload.hotspots[1].filePath, 'src/medium-risk.js');
-    assert.equal(payload.hotspots[1].riskScore, 9);
-    assert.equal(payload.hotspots[2].filePath, 'src/low-risk.js');
-    assert.equal(payload.hotspots[2].riskScore, 1);
+    const authResponse = await request(app)
+      .get(`/api/graph/${jobId}/heatmap`)
+      .set('Authorization', `Bearer ${token}`);
+    assert.equal(authResponse.status, 200);
+
+    const authPayload = authResponse.body;
+    assert.equal(Array.isArray(authPayload.hotspots), true);
+    assert.equal(authPayload.hotspots.length, 3);
+
+    assert.equal(authPayload.hotspots[0].filePath, 'src/high-risk.js');
+    assert.equal(authPayload.hotspots[0].riskScore, 28);
+    assert.equal(authPayload.hotspots[1].filePath, 'src/medium-risk.js');
+    assert.equal(authPayload.hotspots[1].riskScore, 9);
+    assert.equal(authPayload.hotspots[2].filePath, 'src/low-risk.js');
+    assert.equal(authPayload.hotspots[2].riskScore, 1);
+
+    const unauthResponse = await request(app).get('/api/graph/unknown-job/heatmap');
+    assert.equal(unauthResponse.status, 401);
+
+    assert.equal(unauthResponse.body.error, 'Authentication required.');
   } finally {
     await pgPool.query('DELETE FROM graph_nodes WHERE job_id = $1', [jobId]);
     await pgPool.query('DELETE FROM analysis_jobs WHERE id = $1', [jobId]);
@@ -129,11 +115,3 @@ test('GET /api/graph/:jobId/heatmap returns nodes ordered by risk score', async
     await pgPool.query('DELETE FROM users WHERE id = $1', [userId]);
   }
 });
-
-test('GET /api/graph/:jobId/heatmap rejects requests without authentication', async () => {
-  const response = await fetch(`${baseUrl}/api/graph/unknown-job/heatmap`);
-  assert.equal(response.status, 401);
-
-  const payload = await response.json();
-  assert.equal(payload.error, 'Authentication required.');
-});