feat: decouple frontend + multi-turn conversation + graph explorer + CAG layer

- Next.js frontend (chat UI, graph explorer, D3 force graph, citations panel)
- Multi-turn conversation with LangGraph PostgresSaver checkpointing
- Graph API routes (topology, section content, section-context query)
- Retrieval caching layer (CAG) with TTL-based embedding + graph caches
- LLM fallback chain: gemini-2.5-flash-lite → groq → openrouter
- Updated .gitignore and Makefile for cross-platform frontend builds
- frontend/.env.production for Vercel deployment

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -28,3 +28,23 @@ __MACOSX/
 .cache/
 models/
 **/*.onnx
+
+/docs/superpowers/**
+CLAUDE.md
+.claude/
+
+# Design artifacts
+stitch/
+stitch.zip
+index.html
+
+# Frontend (Next.js)
+frontend/.env.local
+frontend/.env*.local
+frontend/.next/
+frontend/out/
+frontend/node_modules/
+frontend/.vercel/
+frontend/npm-debug.log*
+frontend/yarn-debug.log*
+frontend/yarn-error.log*

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install dev serve ingest lint format typecheck test test-cov e2e docker-up docker-down clean
+.PHONY: help install dev serve ingest lint format typecheck test test-cov e2e docker-up docker-down clean frontend-install frontend-dev frontend-build frontend-start frontend-lint frontend-typecheck
 
 help:
 	@echo "CivicSetu — available commands:"
@@ -71,4 +71,23 @@ docker-down:
 clean:
 	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
 	find . -name "*.pyc" -delete 2>/dev/null || true
-	find . -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+
+# Frontend
+frontend-install:
+	cd frontend && npm install
+
+frontend-dev:
+	cd frontend && npm run dev
+
+frontend-build:
+	cd frontend && npm run build
+
+frontend-start:
+	cd frontend && npm run start
+
+frontend-lint:
+	cd frontend && npm run lint
+
+frontend-typecheck:
+	cd frontend && npm run typecheck

README.md

@@ -134,6 +134,7 @@ make docker-down                        # Tear down containers
 | RERA Act 2016                      | Central       | 224      |
 | Maharashtra Real Estate Rules 2017 | Maharashtra   | 214      |
 | UP RERA Rules 2016                 | Uttar Pradesh | 170      |
+| UP RERA General Regulations 2019   | Uttar Pradesh | 85       |
 | Karnataka RERA Rules 2017          | Karnataka     | 235      |
 | Tamil Nadu RERA Rules 2017         | Tamil Nadu    | 157      |
 

frontend/.env.production

@@ -0,0 +1 @@
+NEXT_PUBLIC_BACKEND_URL=https://adesh01-civicsetu.hf.space

frontend/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

frontend/next.config.ts

@@ -0,0 +1,14 @@
+import type { NextConfig } from 'next';
+
+const backendUrl = process.env.BACKEND_URL ?? 'http://localhost:8000';
+
+const nextConfig: NextConfig = {
+  async rewrites() {
+    return [
+      { source: '/api/:path*', destination: `${backendUrl}/api/:path*` },
+      { source: '/health', destination: `${backendUrl}/health` },
+    ];
+  },
+};
+
+export default nextConfig;

frontend/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "civicsetu-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "d3": "^7.9.0",
+    "next": "^15.0.0",
+    "next-themes": "^0.4.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/d3": "^7.4.3",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.2",
+    "@types/react-dom": "^19.0.2",
+    "autoprefixer": "^10.4.20",
+    "eslint": "^9.17.0",
+    "eslint-config-next": "^15.0.0",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.7.2"
+  }
+}

frontend/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

frontend/src/app/globals.css

@@ -0,0 +1,86 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  color-scheme: dark;
+  --ledger-bg: #0d0d0d;
+  --ledger-panel: #141414;
+  --ledger-card: #1a1a1a;
+  --ledger-hover: #222222;
+  --ledger-fg: #e5e2e1;
+  --ledger-muted: rgba(229, 226, 225, 0.42);
+  --ledger-ghost: rgba(255, 255, 255, 0.08);
+  --ledger-primary: #4f98a3;
+}
+
+.dark {
+  color-scheme: dark;
+}
+
+html,
+body {
+  min-height: 100%;
+}
+
+body {
+  margin: 0;
+  overflow: hidden;
+  background: var(--ledger-bg);
+  color: var(--ledger-fg);
+  font-family: var(--font-inter), sans-serif;
+}
+
+@layer base {
+  * {
+    box-sizing: border-box;
+  }
+
+  ::selection {
+    background: rgba(79, 152, 163, 0.26);
+  }
+}
+
+@layer utilities {
+  .ledger-brand {
+    font-family: var(--font-instrument-serif), serif;
+    font-style: italic;
+    color: var(--ledger-primary);
+  }
+
+  .ledger-scroll {
+    scrollbar-width: thin;
+    scrollbar-color: rgba(255, 255, 255, 0.12) transparent;
+  }
+
+  .ledger-scroll::-webkit-scrollbar {
+    width: 4px;
+    height: 4px;
+  }
+
+  .ledger-scroll::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  .ledger-scroll::-webkit-scrollbar-thumb {
+    background: rgba(255, 255, 255, 0.12);
+    border-radius: 999px;
+  }
+}
+
+@keyframes pulse-glow {
+  0%, 100% {
+    filter: drop-shadow(0 0 4px currentColor);
+  }
+  50% {
+    filter: drop-shadow(0 0 12px currentColor) drop-shadow(0 0 20px currentColor);
+  }
+}
+
+.node-selected {
+  animation: pulse-glow 2s ease-in-out infinite;
+}
+
+.node-hover-glow {
+  filter: drop-shadow(0 0 6px currentColor);
+}

frontend/src/app/layout.tsx

@@ -0,0 +1,43 @@
+import type { Metadata } from 'next';
+import { Instrument_Serif, Inter } from 'next/font/google';
+import { ThemeProvider } from '@/components/ThemeProvider';
+import './globals.css';
+
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-inter',
+  display: 'swap',
+});
+
+const instrumentSerif = Instrument_Serif({
+  subsets: ['latin'],
+  weight: ['400'],
+  style: ['italic'],
+  variable: '--font-instrument-serif',
+  display: 'swap',
+});
+
+export const metadata: Metadata = {
+  title: 'CivicSetu | Digital Ledger',
+  description:
+    'Query Indian real estate regulations across multiple jurisdictions with cited answers and graph exploration.',
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className={`${inter.variable} ${instrumentSerif.variable}`}>
+        <ThemeProvider
+          attribute="class"
+          defaultTheme="dark"
+          enableSystem={false}
+          disableTransitionOnChange
+        >
+          {children}
+        </ThemeProvider>
+      </body>
+    </html>
+  );
+}

frontend/src/app/page.tsx

@@ -0,0 +1,132 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { ChatThread } from '@/components/ChatThread';
+import { Header } from '@/components/Header';
+import { InputBar } from '@/components/InputBar';
+import { ContextPill } from '@/components/graph/ContextPill';
+import { GraphExplorer } from '@/components/graph/GraphExplorer';
+import { useChat } from '@/hooks/useChat';
+import { useGraphExplorer } from '@/hooks/useGraphExplorer';
+import type { Jurisdiction, SectionContext } from '@/lib/types';
+
+const railItems = [
+  { label: 'Research', glyph: 'R', active: true },
+  { label: 'Legal tools', glyph: 'L', active: false },
+  { label: 'Library', glyph: 'B', active: false },
+  { label: 'History', glyph: 'H', active: false },
+] as const;
+
+export default function Home() {
+  const { messages, isLoading, sendMessage, sendSectionMessage, newConversation } = useChat();
+  const graphState = useGraphExplorer();
+
+  const [pendingQuery, setPendingQuery] = useState<string | undefined>();
+  const [sectionContext, setSectionContext] = useState<SectionContext | null>(null);
+
+  const handleChatAboutSection = useCallback(
+    (sectionId: string, title: string, docName: string, jurisdiction: string) => {
+      setSectionContext({ sectionId, title, docName, jurisdiction });
+      setPendingQuery(`Explain ${title} of ${docName}`);
+      setTimeout(() => setPendingQuery(undefined), 0);
+    },
+    [],
+  );
+
+  const handleExampleClick = useCallback((query: string) => {
+    setPendingQuery(query);
+    setTimeout(() => setPendingQuery(undefined), 0);
+  }, []);
+
+  function handleSend(text: string, jurisdiction: Jurisdiction | '') {
+    if (sectionContext) {
+      void sendSectionMessage(text, sectionContext.sectionId, sectionContext.jurisdiction);
+      setSectionContext(null);
+      return;
+    }
+
+    void sendMessage(text, jurisdiction);
+  }
+
+  return (
+    <div className="flex h-screen flex-col overflow-hidden bg-[#0d0d0d] text-[#e5e2e1]">
+      <Header onNewConversation={newConversation} />
+
+      <main className="flex min-h-0 flex-1 overflow-hidden">
+        <aside className="flex w-[45%] min-w-[420px] flex-col bg-[#141414] max-lg:w-full max-lg:min-w-0">
+          <div className="flex min-h-0 flex-1">
+            <nav className="flex w-14 shrink-0 flex-col items-center gap-5 bg-[#111111] py-4">
+              {railItems.map(item => (
+                <button
+                  key={item.label}
+                  type="button"
+                  aria-label={item.label}
+                  className={`grid h-8 w-8 place-items-center rounded-[6px] text-sm transition-[background-color,color,transform] duration-150 ease-out active:scale-95 ${
+                    item.active
+                      ? 'bg-[#222222] text-[#4f98a3]'
+                      : 'text-white/30 hover:bg-[#222222] hover:text-white/70'
+                  }`}
+                >
+                  {item.glyph}
+                </button>
+              ))}
+              <button
+                type="button"
+                aria-label="Settings"
+                className="mt-auto grid h-8 w-8 place-items-center rounded-[6px] text-sm text-white/30 transition-[background-color,color,transform] duration-150 ease-out hover:bg-[#222222] hover:text-white/70 active:scale-95"
+              >
+                S
+              </button>
+            </nav>
+
+            <div className="flex min-w-0 flex-1 flex-col">
+              <div className="flex h-14 shrink-0 items-center justify-between bg-[#141414] px-4">
+                <button
+                  type="button"
+                  onClick={newConversation}
+                  className="inline-flex items-center gap-2 rounded-[6px] bg-[#1a1a1a] px-3 py-1.5 text-xs text-white/60 transition-[background-color,color,transform] duration-150 ease-out hover:bg-[#222222] hover:text-white/80 active:scale-[0.98]"
+                >
+                  <span className="text-sm">+</span>
+                  New Conversation
+                </button>
+                <span className="font-mono text-[10px] uppercase tracking-[0.28em] text-white/25">
+                  Active session
+                </span>
+              </div>
+
+              {sectionContext ? (
+                <ContextPill
+                  sectionId={sectionContext.sectionId}
+                  docName={sectionContext.docName}
+                  jurisdiction={sectionContext.jurisdiction}
+                  onRemove={() => setSectionContext(null)}
+                />
+              ) : null}
+
+              <div className="min-h-0 flex-1 overflow-hidden">
+                <ChatThread messages={messages} isLoading={isLoading} onExampleClick={handleExampleClick} />
+              </div>
+
+              <InputBar onSend={handleSend} disabled={isLoading} pendingQuery={pendingQuery} />
+            </div>
+          </div>
+        </aside>
+
+        <section className="flex w-[55%] min-w-0 flex-col bg-[#0d0d0d] max-lg:hidden">
+          <GraphExplorer {...graphState} onChatAboutSection={handleChatAboutSection} />
+        </section>
+      </main>
+
+      <footer className="flex h-6 shrink-0 items-center justify-between bg-[#0d0d0d] px-4 font-mono text-[10px] uppercase tracking-tight text-zinc-600">
+        <div className="flex items-center gap-4">
+          <span>DB_LATENCY: 12ms</span>
+          <span>CORPUS: RERA_INDIA_2026</span>
+        </div>
+        <div className="flex items-center gap-1.5 text-[#4f98a3]">
+          <span className="h-1 w-1 rounded-full bg-[#4f98a3]" />
+          System ready
+        </div>
+      </footer>
+    </div>
+  );
+}

frontend/src/components/ChatThread.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { MessageBubble } from '@/components/MessageBubble';
+import type { ChatMessage } from '@/lib/types';
+
+const EXAMPLE_QUERIES = [
+  'What are promoter obligations under RERA?',
+  'What penalty applies for delayed possession?',
+  'How does agent registration work under Maharashtra rules?',
+  'What is the complaint filing process for a buyer?',
+] as const;
+
+interface Props {
+  messages: ChatMessage[];
+  isLoading: boolean;
+  onExampleClick: (query: string) => void;
+}
+
+export function ChatThread({ messages, isLoading, onExampleClick }: Props) {
+  const bottomRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: 'smooth' });
+  }, [messages, isLoading]);
+
+  if (messages.length === 0 && !isLoading) {
+    return (
+      <div className="ledger-scroll flex h-full flex-col justify-center overflow-y-auto px-4 py-8">
+        <div className="max-w-md">
+          <p className="font-mono text-[10px] uppercase tracking-[0.28em] text-white/25">Research desk</p>
+          <h2 className="mt-3 text-2xl font-semibold tracking-[-0.02em] text-white/84">
+            Ask the ledger a legal question.
+          </h2>
+          <p className="mt-3 text-sm leading-6 text-white/50">
+            Query Indian RERA provisions, compare jurisdictions, and route selected graph sections directly into the chat.
+          </p>
+        </div>
+
+        <div className="mt-8 grid gap-2">
+          {EXAMPLE_QUERIES.map(query => (
+            <button
+              key={query}
+              type="button"
+              onClick={() => onExampleClick(query)}
+              className="rounded-[10px] bg-[#1a1a1a] px-3.5 py-3 text-left text-[13px] leading-5 text-white/60 transition-colors hover:bg-[#222222] hover:text-white/80"
+            >
+              {query}
+            </button>
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="ledger-scroll flex h-full flex-col gap-6 overflow-y-auto p-4">
+      {messages.map(message => (
+        <MessageBubble key={message.id} message={message} />
+      ))}
+
+      {isLoading ? (
+        <div className="flex gap-1.5 self-start p-2">
+          <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-white/20" />
+          <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-white/20 [animation-delay:200ms]" />
+          <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-white/20 [animation-delay:400ms]" />
+        </div>
+      ) : null}
+
+      <div ref={bottomRef} />
+    </div>
+  );
+}

frontend/src/components/CitationsPanel.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import { useState } from 'react';
+import { JURISDICTION_COLORS, JURISDICTION_LABELS } from '@/lib/constants';
+import type { Citation } from '@/lib/types';
+
+interface Props {
+  citations: Citation[];
+}
+
+export function CitationsPanel({ citations }: Props) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="mt-3">
+      <button
+        type="button"
+        onClick={() => setOpen(value => !value)}
+        className="inline-flex items-center gap-2 font-mono text-[10px] uppercase tracking-[0.2em] text-white/30 transition-colors hover:text-[#4f98a3] active:scale-[0.98]"
+      >
+        <span className={`transition-transform duration-150 ease-out ${open ? 'rotate-180' : ''}`}>&#x25BC;</span>
+        {citations.length} citation{citations.length === 1 ? '' : 's'}
+      </button>
+
+      {open ? (
+        <div className="mt-3 space-y-2">
+          {citations.map(citation => {
+            const color = JURISDICTION_COLORS[citation.jurisdiction] ?? '#888';
+            return (
+              <article key={citation.chunk_id} className="border border-white/[0.07] bg-white/[0.025] p-3">
+                <div className="flex items-start justify-between gap-3">
+                  <div className="min-w-0 space-y-1">
+                    <p className="font-mono text-[10px] uppercase tracking-[0.2em] text-white/30">
+                      Sec {citation.section_id}
+                    </p>
+                    <p className="truncate text-[12px] font-medium text-white/70">{citation.doc_name}</p>
+                  </div>
+                  <span
+                    className="shrink-0 px-1.5 py-0.5 font-mono text-[9px] uppercase tracking-[0.14em]"
+                    style={{ backgroundColor: `${color}24`, color }}
+                  >
+                    {JURISDICTION_LABELS[citation.jurisdiction] ?? citation.jurisdiction}
+                  </span>
+                </div>
+
+                <div className="mt-3 flex flex-wrap items-center gap-x-4 gap-y-2 font-mono text-[9px] uppercase tracking-[0.16em] text-white/30">
+                  <span>Effective {citation.effective_date ?? 'not listed'}</span>
+                  <a
+                    href={citation.source_url}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="text-[#4f98a3] transition-colors hover:text-[#8ad2de]"
+                  >
+                    Source
+                  </a>
+                </div>
+              </article>
+            );
+          })}
+        </div>
+      ) : null}
+    </div>
+  );
+}

frontend/src/components/ConfidenceBadge.tsx

@@ -0,0 +1,31 @@
+interface Props {
+  score: number;
+}
+
+const LEVELS = {
+  HIGH: {
+    label: 'HIGH',
+    classes: 'border-emerald-300/20 bg-emerald-300/10 text-emerald-200/80',
+  },
+  MEDIUM: {
+    label: 'MEDIUM',
+    classes: 'border-amber-300/20 bg-amber-300/10 text-amber-200/80',
+  },
+  LOW: {
+    label: 'LOW',
+    classes: 'border-rose-300/20 bg-rose-300/10 text-rose-200/80',
+  },
+} as const;
+
+export function ConfidenceBadge({ score }: Props) {
+  const key = score >= 0.75 ? 'HIGH' : score >= 0.5 ? 'MEDIUM' : 'LOW';
+  const { label, classes } = LEVELS[key];
+
+  return (
+    <span
+      className={`inline-flex items-center border px-2 py-0.5 font-mono text-[9px] font-medium uppercase tracking-[0.18em] ${classes}`}
+    >
+      {label} {(score * 100).toFixed(0)}%
+    </span>
+  );
+}

frontend/src/components/Header.tsx

@@ -0,0 +1,83 @@
+'use client';
+
+import { useTheme } from 'next-themes';
+import { useEffect, useState } from 'react';
+
+interface Props {
+  onNewConversation: () => void;
+}
+
+export function Header({ onNewConversation: _onNewConversation }: Props) {
+  const { resolvedTheme, setTheme } = useTheme();
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  return (
+    <header className="z-20 flex h-12 shrink-0 items-center justify-between bg-[#0d0d0d] px-6">
+      <div className="flex w-full items-center justify-between">
+        <div className="flex items-center gap-2">
+          <span className="text-[#4f98a3]">CS</span>
+          <h1 className="ledger-brand text-xl">CivicSetu</h1>
+        </div>
+
+        <div className="flex items-center gap-4">
+          {mounted ? (
+            <button
+              type="button"
+              onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}
+              aria-label={resolvedTheme === 'dark' ? 'Switch to light mode' : 'Switch to dark mode'}
+              className="grid h-8 w-8 place-items-center rounded-[6px] text-zinc-400 transition-[background-color,color,transform] duration-150 ease-out hover:bg-white/5 hover:text-white/70 active:scale-95"
+            >
+              {resolvedTheme === 'dark' ? <MoonIcon /> : <SunIcon />}
+            </button>
+          ) : null}
+        </div>
+      </div>
+    </header>
+  );
+}
+
+function MoonIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      className="h-4 w-4"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M20.2 14.8A8.5 8.5 0 0 1 9.2 3.8 8 8 0 1 0 20.2 14.8Z" />
+    </svg>
+  );
+}
+
+function SunIcon() {
+  return (
+    <svg
+      aria-hidden="true"
+      className="h-4 w-4"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <circle cx="12" cy="12" r="3.5" />
+      <path d="M12 2.8v2.4" />
+      <path d="M12 18.8v2.4" />
+      <path d="m4.7 4.7 1.7 1.7" />
+      <path d="m17.6 17.6 1.7 1.7" />
+      <path d="M2.8 12h2.4" />
+      <path d="M18.8 12h2.4" />
+      <path d="m4.7 19.3 1.7-1.7" />
+      <path d="m17.6 6.4 1.7-1.7" />
+    </svg>
+  );
+}

frontend/src/components/InputBar.tsx

@@ -0,0 +1,171 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import type { Jurisdiction } from '@/lib/types';
+
+const JURISDICTIONS = [
+  { value: '' as const, label: 'All Jurisdictions', shortLabel: 'All', dotClass: 'bg-white/35' },
+  { value: 'CENTRAL' as const, label: 'Central', shortLabel: 'Central', dotClass: 'bg-[#2db7a3]' },
+  { value: 'MAHARASHTRA' as const, label: 'Maharashtra', shortLabel: 'Maharashtra', dotClass: 'bg-[#4e7cff]' },
+  { value: 'UTTAR_PRADESH' as const, label: 'Uttar Pradesh', shortLabel: 'Uttar Pradesh', dotClass: 'bg-[#f4b63f]' },
+  { value: 'KARNATAKA' as const, label: 'Karnataka', shortLabel: 'Karnataka', dotClass: 'bg-[#78b94d]' },
+  { value: 'TAMIL_NADU' as const, label: 'Tamil Nadu', shortLabel: 'Tamil Nadu', dotClass: 'bg-[#ff7a59]' },
+];
+
+interface Props {
+  onSend: (query: string, jurisdiction: Jurisdiction | '') => void;
+  disabled: boolean;
+  pendingQuery?: string;
+}
+
+export function InputBar({ onSend, disabled, pendingQuery }: Props) {
+  const [query, setQuery] = useState('');
+  const [jurisdiction, setJurisdiction] = useState<Jurisdiction | ''>('');
+  const [isJurisdictionOpen, setIsJurisdictionOpen] = useState(false);
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const jurisdictionMenuRef = useRef<HTMLDivElement>(null);
+  const MAX_VISIBLE_LINES = 9;
+
+  const selectedJurisdiction = JURISDICTIONS.find(item => item.value === jurisdiction) ?? JURISDICTIONS[0];
+
+  useEffect(() => {
+    if (!pendingQuery) {
+      return;
+    }
+
+    setQuery(pendingQuery);
+    requestAnimationFrame(() => {
+      textareaRef.current?.focus();
+      autoResize();
+    });
+  }, [pendingQuery]);
+
+  useEffect(() => {
+    if (!isJurisdictionOpen) {
+      return;
+    }
+
+    function handlePointerDown(event: PointerEvent) {
+      if (!jurisdictionMenuRef.current?.contains(event.target as Node)) {
+        setIsJurisdictionOpen(false);
+      }
+    }
+
+    window.addEventListener('pointerdown', handlePointerDown);
+    return () => window.removeEventListener('pointerdown', handlePointerDown);
+  }, [isJurisdictionOpen]);
+
+  function autoResize() {
+    const element = textareaRef.current;
+    if (!element) {
+      return;
+    }
+
+    const computed = window.getComputedStyle(element);
+    const lineHeight = Number.parseFloat(computed.lineHeight) || 24;
+    const maxHeight = lineHeight * MAX_VISIBLE_LINES;
+    element.style.height = 'auto';
+    element.style.height = `${Math.min(element.scrollHeight, maxHeight)}px`;
+    element.style.overflowY = element.scrollHeight > maxHeight ? 'auto' : 'hidden';
+  }
+
+  function handleInput(event: React.ChangeEvent<HTMLTextAreaElement>) {
+    setQuery(event.target.value);
+    autoResize();
+  }
+
+  function handleSend() {
+    const text = query.trim();
+    if (!text || disabled) {
+      return;
+    }
+
+    onSend(text, jurisdiction);
+    setQuery('');
+    if (textareaRef.current) {
+      textareaRef.current.style.height = 'auto';
+      textareaRef.current.style.overflowY = 'hidden';
+    }
+  }
+
+  function handleKeyDown(event: React.KeyboardEvent<HTMLTextAreaElement>) {
+    if (event.key === 'Enter' && !event.shiftKey) {
+      event.preventDefault();
+      handleSend();
+    }
+  }
+
+  return (
+    <div className="shrink-0 bg-[#0d0d0d] p-3">
+      <div ref={jurisdictionMenuRef} className="relative mb-1 w-fit">
+        <button
+          type="button"
+          onClick={() => setIsJurisdictionOpen(value => !value)}
+          className="inline-flex h-7 items-center gap-2 rounded-[7px] border border-white/[0.07] bg-[#141414] px-2.5 font-mono text-[10px] uppercase tracking-[0.2em] text-white/50 transition-[background-color,border-color,color,transform] duration-150 ease-out hover:border-white/15 hover:bg-[#1a1a1a] hover:text-white/70 active:scale-[0.98]"
+          aria-haspopup="listbox"
+          aria-expanded={isJurisdictionOpen}
+        >
+          <span className={`h-1.5 w-1.5 rounded-full ${selectedJurisdiction.dotClass}`} />
+          {selectedJurisdiction.shortLabel}
+          <span className={`text-white/25 transition-transform duration-150 ease-out ${isJurisdictionOpen ? 'rotate-180' : ''}`}>
+            &#x25BC;
+          </span>
+        </button>
+
+        {isJurisdictionOpen ? (
+          <div
+            role="listbox"
+            className="absolute bottom-8 left-0 z-30 w-52 border border-white/[0.08] bg-[#141414]/98 p-1 shadow-[0_18px_50px_rgba(0,0,0,0.45)] backdrop-blur"
+          >
+            {JURISDICTIONS.map(item => (
+              <button
+                key={item.value}
+                type="button"
+                role="option"
+                aria-selected={jurisdiction === item.value}
+                onClick={() => {
+                  setJurisdiction(item.value);
+                  setIsJurisdictionOpen(false);
+                }}
+                className={`flex w-full items-center justify-between gap-3 rounded-[6px] px-2.5 py-2 text-left text-[12px] transition-[background-color,color] duration-150 ease-out ${
+                  jurisdiction === item.value
+                    ? 'bg-[#4f98a3]/12 text-[#9ed4dc]'
+                    : 'text-white/60 hover:bg-white/[0.04] hover:text-white/80'
+                }`}
+              >
+                <span className="flex min-w-0 items-center gap-2">
+                  <span className={`h-1.5 w-1.5 shrink-0 rounded-full ${item.dotClass}`} />
+                  <span className="truncate">{item.label}</span>
+                </span>
+                {jurisdiction === item.value ? (
+                  <span className={`h-1.5 w-1.5 shrink-0 rounded-full ${item.dotClass}`} />
+                ) : null}
+              </button>
+            ))}
+          </div>
+        ) : null}
+      </div>
+
+      <div className="relative flex items-end">
+        <textarea
+          ref={textareaRef}
+          value={query}
+          onChange={handleInput}
+          onKeyDown={handleKeyDown}
+          rows={1}
+          placeholder="Ask about RERA regulations..."
+          className="ledger-scroll min-h-[40px] w-full resize-none overflow-hidden rounded-[10px] bg-[#1a1a1a] py-2 pl-3 pr-10 text-[14px] leading-6 text-white/85 outline-none transition-[border-color,height] duration-150 ease-out placeholder:text-white/25 focus:ring-1 focus:ring-[#4f98a3]/50"
+        />
+        <button
+          type="button"
+          onClick={handleSend}
+          disabled={disabled || !query.trim()}
+          aria-label="Send message"
+          className="absolute bottom-2 right-3 text-[#4f98a3] transition-opacity hover:opacity-80 disabled:opacity-25"
+        >
+          -&gt;
+        </button>
+      </div>
+    </div>
+  );
+}

frontend/src/components/MessageBubble.tsx

@@ -0,0 +1,109 @@
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { CitationsPanel } from '@/components/CitationsPanel';
+import { ConfidenceBadge } from '@/components/ConfidenceBadge';
+import type { ChatMessage } from '@/lib/types';
+import { isCivicSetuResponse } from '@/lib/types';
+
+interface Props {
+  message: ChatMessage;
+}
+
+export function MessageBubble({ message }: Props) {
+  if (message.role === 'user') {
+    return (
+      <div className="flex justify-end">
+        <div className="max-w-[85%] rounded-[12px] bg-white/5 px-3.5 py-2.5 text-[13px] leading-6 text-white/85">
+          <p className="whitespace-pre-wrap">{message.text}</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (message.role === 'error') {
+    return (
+      <div className="max-w-[95%] self-start rounded-[10px] bg-red-950/25 px-3.5 py-3 text-[13px] leading-6 text-red-200/80">
+        {message.text}
+      </div>
+    );
+  }
+
+  const data = message.data;
+  const isRichResponse = data !== undefined && isCivicSetuResponse(data);
+
+  return (
+    <div className="flex max-w-[95%] flex-col gap-3 self-start">
+      <div className="text-[14px] leading-7 text-white/70">
+        <ReactMarkdown
+          remarkPlugins={[remarkGfm]}
+          components={{
+            p: ({ children }) => <p className="mb-4 last:mb-0">{children}</p>,
+            h1: ({ children }) => <h1 className="mb-3 text-xl font-semibold leading-7 text-white/90">{children}</h1>,
+            h2: ({ children }) => <h2 className="mb-3 text-lg font-semibold leading-7 text-white/90">{children}</h2>,
+            h3: ({ children }) => <h3 className="mb-2 text-base font-semibold leading-6 text-white/85">{children}</h3>,
+            ul: ({ children }) => <ul className="mb-4 list-disc space-y-1 pl-5 last:mb-0">{children}</ul>,
+            ol: ({ children }) => <ol className="mb-4 list-decimal space-y-1 pl-5 last:mb-0">{children}</ol>,
+            li: ({ children }) => <li className="pl-1">{children}</li>,
+            strong: ({ children }) => <strong className="font-semibold text-white/90">{children}</strong>,
+            blockquote: ({ children }) => (
+              <blockquote className="mb-4 border-l-2 border-[#4f98a3]/50 pl-4 text-white/55 last:mb-0">
+                {children}
+              </blockquote>
+            ),
+            hr: () => <hr className="my-5 border-white/10" />,
+            table: ({ children }) => (
+              <div className="ledger-scroll mb-4 overflow-x-auto last:mb-0">
+                <table className="min-w-full border-collapse text-left text-[13px] leading-6">
+                  {children}
+                </table>
+              </div>
+            ),
+            thead: ({ children }) => <thead className="border-b border-white/15 text-white/85">{children}</thead>,
+            tbody: ({ children }) => <tbody className="divide-y divide-white/10">{children}</tbody>,
+            th: ({ children }) => <th className="px-3 py-2 font-semibold">{children}</th>,
+            td: ({ children }) => <td className="px-3 py-2 align-top text-white/65">{children}</td>,
+            code: ({ children, className }) => (
+              <code className={`rounded bg-white/10 px-1.5 py-0.5 font-mono text-[0.92em] text-white/80 ${className ?? ''}`}>
+                {children}
+              </code>
+            ),
+            pre: ({ children }) => (
+              <pre className="ledger-scroll mb-4 overflow-x-auto rounded-[10px] bg-[#1a1a1a] px-4 py-3 font-mono text-xs text-white/70 last:mb-0">
+                {children}
+              </pre>
+            ),
+            a: ({ children, href }) => (
+              <a
+                href={href}
+                target="_blank"
+                rel="noreferrer"
+                className="font-medium text-[#4f98a3] underline decoration-[#4f98a3]/40 underline-offset-4 hover:text-[#72bdc6]"
+              >
+                {children}
+              </a>
+            ),
+          }}
+        >
+          {message.text}
+        </ReactMarkdown>
+      </div>
+
+      {isRichResponse && data.citations.length > 0 ? <CitationsPanel citations={data.citations} /> : null}
+
+      {isRichResponse ? (
+        <div className="flex flex-col gap-1.5">
+          <div className="flex items-center gap-2">
+            <span className="text-[12px] text-white/30">Confidence:</span>
+            <ConfidenceBadge score={data.confidence_score} />
+          </div>
+          {data.conflict_warnings.length > 0 ? (
+            <p className="text-xs leading-5 text-amber-200/70">Conflict warning: {data.conflict_warnings.join(', ')}</p>
+          ) : null}
+          {data.amendment_notice ? (
+            <p className="text-xs leading-5 text-[#8ad2de]/75">Amendment notice: {data.amendment_notice}</p>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}

frontend/src/components/ThemeProvider.tsx

@@ -0,0 +1,8 @@
+'use client';
+
+import { ThemeProvider as NextThemesProvider } from 'next-themes';
+import type { ThemeProviderProps } from 'next-themes';
+
+export function ThemeProvider(props: ThemeProviderProps) {
+  return <NextThemesProvider {...props} />;
+}

frontend/src/components/graph/ContextPill.tsx

@@ -0,0 +1,26 @@
+'use client';
+
+interface Props {
+  sectionId: string;
+  docName: string;
+  jurisdiction: string;
+  onRemove: () => void;
+}
+
+export function ContextPill({ sectionId, docName, jurisdiction, onRemove }: Props) {
+  return (
+    <div className="flex h-10 shrink-0 items-center justify-between bg-[#141414] px-3">
+      <span className="truncate text-[12px] text-white/60">
+        Sec {sectionId} / {docName} / {jurisdiction}
+      </span>
+      <button
+        onClick={onRemove}
+        className="text-white/30 transition-colors hover:text-white/70 active:scale-95"
+        aria-label="Remove section context"
+        type="button"
+      >
+        x
+      </button>
+    </div>
+  );
+}

frontend/src/components/graph/ForceGraph.tsx

@@ -0,0 +1,274 @@
+'use client';
+
+import * as d3 from 'd3';
+import { useEffect, useRef } from 'react';
+import { EDGE_STYLES, JURISDICTION_COLORS, NODE_RADIUS } from '@/lib/constants';
+import type { GraphEdge, GraphFilters, GraphNode } from '@/lib/types';
+
+interface Props {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  filters: GraphFilters;
+  selectedNode: GraphNode | null;
+  hoveredNode: GraphNode | null;
+  onNodeClick: (node: GraphNode | null) => void;
+  onNodeHover: (node: GraphNode | null) => void;
+  width: number;
+  height: number;
+}
+
+export function ForceGraph({
+  nodes,
+  edges,
+  filters,
+  selectedNode,
+  hoveredNode,
+  onNodeClick,
+  onNodeHover,
+  width,
+  height,
+}: Props) {
+  const svgRef = useRef<SVGSVGElement>(null);
+  const simRef = useRef<d3.Simulation<GraphNode, GraphEdge> | null>(null);
+  const zoomRef = useRef<d3.ZoomBehavior<SVGSVGElement, unknown> | null>(null);
+
+  const filteredNodes = nodes.filter(node => filters.jurisdictions.has(node.jurisdiction));
+  const filteredNodeIds = new Set(filteredNodes.map(node => node.chunk_id));
+  const filteredEdges = edges.filter(
+    edge =>
+      filters.edgeTypes.has(edge.edge_type) &&
+      filteredNodeIds.has(typeof edge.source === 'string' ? edge.source : edge.source.chunk_id) &&
+      filteredNodeIds.has(typeof edge.target === 'string' ? edge.target : edge.target.chunk_id),
+  );
+
+  useEffect(() => {
+    if (!svgRef.current || width === 0 || height === 0) {
+      return;
+    }
+
+    const svg = d3.select(svgRef.current);
+    svg.selectAll('*').remove();
+
+    const defs = svg.append('defs');
+    const filter = defs.append('filter').attr('id', 'node-glow');
+    filter.append('feGaussianBlur').attr('stdDeviation', '3').attr('result', 'blur');
+    const merge = filter.append('feMerge');
+    merge.append('feMergeNode').attr('in', 'blur');
+    merge.append('feMergeNode').attr('in', 'SourceGraphic');
+
+    const container = svg.append('g').attr('class', 'zoom-container');
+    const edgeGroup = container.append('g').attr('class', 'edges');
+    const nodeGroup = container.append('g').attr('class', 'nodes');
+
+    const simNodes: GraphNode[] = filteredNodes.map(node => ({ ...node }));
+    const chunkIdToNode = new Map(simNodes.map(node => [node.chunk_id, node]));
+    const simEdges: GraphEdge[] = filteredEdges.map(edge => ({
+      ...edge,
+      source: typeof edge.source === 'string' ? edge.source : edge.source.chunk_id,
+      target: typeof edge.target === 'string' ? edge.target : edge.target.chunk_id,
+    }));
+
+    const connectionCounts = simNodes.map(node => node.connection_count);
+    const minConn = Math.min(...connectionCounts, 1);
+    const maxConn = Math.max(...connectionCounts, 2);
+    const radiusScale = d3.scaleSqrt().domain([minConn, maxConn]).range([NODE_RADIUS.MIN, NODE_RADIUS.MAX]);
+    const getRadius = (node: GraphNode) =>
+      filters.nodeSizeMode === 'uniform' ? NODE_RADIUS.DEFAULT : radiusScale(node.connection_count);
+
+    const sim = d3
+      .forceSimulation<GraphNode>(simNodes)
+      .force(
+        'link',
+        d3
+          .forceLink<GraphNode, GraphEdge>(simEdges)
+          .id(node => node.chunk_id)
+          .distance(82)
+          .strength(0.38),
+      )
+      .force('charge', d3.forceManyBody<GraphNode>().strength(-64).distanceMax(310))
+      .force('center', d3.forceCenter(width / 2, height / 2))
+      .force('collide', d3.forceCollide<GraphNode>(node => getRadius(node) + 3))
+      .alphaDecay(0.02)
+      .velocityDecay(0.42);
+
+    simRef.current = sim;
+
+    const link = edgeGroup
+      .selectAll<SVGLineElement, GraphEdge>('line')
+      .data(simEdges)
+      .join('line')
+      .attr('stroke', edge => EDGE_STYLES[edge.edge_type]?.color ?? 'rgba(255,255,255,0.14)')
+      .attr('stroke-width', edge => EDGE_STYLES[edge.edge_type]?.width ?? 1)
+      .attr('stroke-dasharray', edge => EDGE_STYLES[edge.edge_type]?.dashArray ?? 'none')
+      .attr('stroke-opacity', 0.82);
+
+    const nodeEl = nodeGroup
+      .selectAll<SVGGElement, GraphNode>('g.node')
+      .data(simNodes, node => node.chunk_id)
+      .join('g')
+      .attr('class', 'node')
+      .style('cursor', 'pointer')
+      .call(
+        d3
+          .drag<SVGGElement, GraphNode>()
+          .on('start', (event: d3.D3DragEvent<SVGGElement, GraphNode, GraphNode>, node: GraphNode) => {
+            if (!event.active) {
+              sim.alphaTarget(0.3).restart();
+            }
+            node.fx = node.x;
+            node.fy = node.y;
+          })
+          .on('drag', (event: d3.D3DragEvent<SVGGElement, GraphNode, GraphNode>, node: GraphNode) => {
+            node.fx = event.x;
+            node.fy = event.y;
+          })
+          .on('end', (event: d3.D3DragEvent<SVGGElement, GraphNode, GraphNode>, node: GraphNode) => {
+            if (!event.active) {
+              sim.alphaTarget(0);
+            }
+            node.fx = null;
+            node.fy = null;
+          }),
+      );
+
+    nodeEl
+      .append('circle')
+      .attr('class', 'glow-ring')
+      .attr('r', node => getRadius(node) + 4)
+      .attr('fill', 'none')
+      .attr('stroke', node => JURISDICTION_COLORS[node.jurisdiction] ?? '#888')
+      .attr('stroke-width', 1.5)
+      .attr('filter', 'url(#node-glow)')
+      .attr('opacity', 0);
+
+    nodeEl
+      .append('circle')
+      .attr('class', 'main-circle')
+      .attr('r', node => getRadius(node))
+      .attr('fill', node => JURISDICTION_COLORS[node.jurisdiction] ?? '#888')
+      .attr('stroke', '#0d0d0d')
+      .attr('stroke-width', 1.25)
+      .attr('stroke-opacity', 0.75);
+
+    nodeEl
+      .append('text')
+      .attr('class', 'node-label')
+      .attr('dy', node => -(getRadius(node) + 6))
+      .attr('text-anchor', 'middle')
+      .attr('fill', 'rgba(229,226,225,0.86)')
+      .attr('font-size', '10px')
+      .attr('font-family', 'var(--font-inter), sans-serif')
+      .attr('pointer-events', 'none')
+      .text(node => `Sec ${node.section_id} / ${node.title.slice(0, 28)}${node.title.length > 28 ? '...' : ''}`)
+      .attr('opacity', 0);
+
+    nodeEl
+      .on('mouseenter', (_event: MouseEvent, node: GraphNode) => {
+        onNodeHover(chunkIdToNode.get(node.chunk_id) ?? null);
+      })
+      .on('mouseleave', () => {
+        onNodeHover(null);
+      })
+      .on('click', (event: MouseEvent, node: GraphNode) => {
+        event.stopPropagation();
+        onNodeClick(chunkIdToNode.get(node.chunk_id) ?? node);
+      });
+
+    svg.on('click', () => onNodeClick(null));
+
+    const zoom = d3
+      .zoom<SVGSVGElement, unknown>()
+      .scaleExtent([0.3, 5])
+      .on('zoom', (event: d3.D3ZoomEvent<SVGSVGElement, unknown>) => {
+        container.attr('transform', event.transform.toString());
+        nodeEl.select<SVGTextElement>('.node-label').attr('opacity', event.transform.k > 2.5 ? 0.9 : 0);
+      });
+
+    zoomRef.current = zoom;
+    svg.call(zoom);
+
+    sim.on('tick', () => {
+      link
+        .attr('x1', edge => (edge.source as GraphNode).x ?? 0)
+        .attr('y1', edge => (edge.source as GraphNode).y ?? 0)
+        .attr('x2', edge => (edge.target as GraphNode).x ?? 0)
+        .attr('y2', edge => (edge.target as GraphNode).y ?? 0);
+
+      nodeEl.attr('transform', node => `translate(${node.x ?? 0},${node.y ?? 0})`);
+    });
+
+    return () => {
+      sim.stop();
+      svg.on('.zoom', null);
+    };
+    // Rebuilding here keeps D3 ownership simple when the filter set changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [filteredNodes.length, filteredEdges.length, width, height, filters.nodeSizeMode]);
+
+  useEffect(() => {
+    if (!svgRef.current) {
+      return;
+    }
+
+    const svg = d3.select(svgRef.current);
+    const nodeEl = svg.selectAll<SVGGElement, GraphNode>('g.node');
+
+    if (!hoveredNode) {
+      nodeEl.selectAll('.main-circle').attr('opacity', 1);
+      nodeEl.selectAll<SVGTextElement, GraphNode>('.node-label').each(function() {
+        const zoom = zoomRef.current;
+        if (zoom && svgRef.current) {
+          const transform = d3.zoomTransform(svgRef.current);
+          d3.select(this).attr('opacity', transform.k > 2.5 ? 0.9 : 0);
+        } else {
+          d3.select(this).attr('opacity', 0);
+        }
+      });
+      return;
+    }
+
+    const neighborIds = new Set<string>([hoveredNode.chunk_id]);
+    svg.selectAll<SVGLineElement, GraphEdge>('line').each((edge: GraphEdge) => {
+      const src = typeof edge.source === 'string' ? edge.source : edge.source.chunk_id;
+      const tgt = typeof edge.target === 'string' ? edge.target : edge.target.chunk_id;
+      if (src === hoveredNode.chunk_id) {
+        neighborIds.add(tgt);
+      }
+      if (tgt === hoveredNode.chunk_id) {
+        neighborIds.add(src);
+      }
+    });
+
+    nodeEl.each(function(this: SVGGElement, node: GraphNode) {
+      const isNeighbor = neighborIds.has(node.chunk_id);
+      d3.select(this).select('.main-circle').attr('opacity', isNeighbor ? 1 : 0.12);
+      d3.select(this)
+        .select('.node-label')
+        .attr('opacity', node.chunk_id === hoveredNode.chunk_id ? 1 : 0);
+    });
+  }, [hoveredNode]);
+
+  useEffect(() => {
+    if (!svgRef.current) {
+      return;
+    }
+
+    const svg = d3.select(svgRef.current);
+    svg.selectAll<SVGCircleElement, GraphNode>('.glow-ring').each(function(this: SVGCircleElement, node: GraphNode) {
+      const isSelected = selectedNode?.chunk_id === node.chunk_id;
+      d3.select(this)
+        .attr('opacity', isSelected ? 0.8 : 0)
+        .classed('node-selected', isSelected);
+    });
+  }, [selectedNode]);
+
+  return (
+    <svg
+      ref={svgRef}
+      width={width}
+      height={height}
+      className="h-full w-full bg-[#0d0d0d]"
+      style={{ display: 'block' }}
+    />
+  );
+}

frontend/src/components/graph/GraphExplorer.tsx

@@ -0,0 +1,132 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { ForceGraph } from './ForceGraph';
+import { GraphFilterSidebar } from './GraphFilterSidebar';
+import { SectionDrawer } from './SectionDrawer';
+import type { UseGraphExplorerReturn } from '@/hooks/useGraphExplorer';
+
+interface Props extends UseGraphExplorerReturn {
+  onChatAboutSection: (
+    sectionId: string,
+    title: string,
+    docName: string,
+    jurisdiction: string,
+  ) => void;
+}
+
+export function GraphExplorer({
+  topology,
+  isLoading,
+  error,
+  selectedNode,
+  hoveredNode,
+  sectionContent,
+  isSectionLoading,
+  filters,
+  setSelectedNode,
+  setHoveredNode,
+  setFilters,
+  navigateToNode,
+  onChatAboutSection,
+}: Props) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [dims, setDims] = useState({ width: 0, height: 0 });
+
+  useEffect(() => {
+    if (!containerRef.current) {
+      return;
+    }
+
+    const ro = new ResizeObserver(entries => {
+      for (const entry of entries) {
+        const { width, height } = entry.contentRect;
+        setDims({ width: Math.floor(width), height: Math.floor(height) });
+      }
+    });
+
+    ro.observe(containerRef.current);
+    return () => ro.disconnect();
+  }, []);
+
+  const nodes = topology?.nodes ?? [];
+  const edges = topology?.edges ?? [];
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-[#0d0d0d]">
+      <div className="flex h-12 shrink-0 items-center justify-between border-b border-white/[0.06] px-4">
+        <div>
+          <p className="font-mono text-[10px] uppercase tracking-[0.24em] text-white/30">Graph Explorer</p>
+          <p className="mt-0.5 text-[12px] text-white/40">
+            {nodes.length} sections / {edges.length} relationships
+          </p>
+        </div>
+        <div className="flex items-center gap-2 font-mono text-[10px] uppercase tracking-[0.2em] text-white/30">
+          <span className="h-1.5 w-1.5 rounded-full bg-[#4f98a3]" />
+          Live topology
+        </div>
+      </div>
+
+      <div ref={containerRef} className="relative min-h-0 flex-1 overflow-hidden bg-[#0d0d0d]">
+        <div className="pointer-events-none absolute inset-0 opacity-[0.14] [background-image:radial-gradient(circle_at_center,rgba(229,226,225,0.72)_1px,transparent_1.5px)] [background-position:0_0] [background-size:24px_24px]" />
+
+        {isLoading ? (
+          <div className="absolute inset-0 z-10 flex items-center justify-center">
+            <div className="flex items-center gap-2 font-mono text-[10px] uppercase tracking-[0.24em] text-white/30">
+              {[0, 1, 2].map(i => (
+                <span
+                  key={i}
+                  className="h-1.5 w-1.5 rounded-full bg-white/25 animate-pulse"
+                  style={{ animationDelay: `${i * 140}ms` }}
+                />
+              ))}
+              Loading graph
+            </div>
+          </div>
+        ) : null}
+
+        {error ? (
+          <div className="absolute inset-0 z-10 flex items-center justify-center">
+            <div className="max-w-xs border border-red-300/15 bg-red-950/10 p-4 text-center">
+              <p className="text-sm text-red-200/80">Graph unavailable</p>
+              <p className="mt-1 text-xs leading-5 text-white/30">{error}</p>
+            </div>
+          </div>
+        ) : null}
+
+        {!isLoading && !error && nodes.length === 0 ? (
+          <div className="absolute inset-0 z-10 flex items-center justify-center">
+            <div className="border border-white/[0.06] bg-[#141414] p-5 text-center">
+              <p className="text-sm text-white/60">No section relationships found</p>
+              <p className="mt-1 text-xs text-white/30">Run ingestion to populate the graph.</p>
+            </div>
+          </div>
+        ) : null}
+
+        {dims.width > 0 && dims.height > 0 && nodes.length > 0 ? (
+          <ForceGraph
+            nodes={nodes}
+            edges={edges}
+            filters={filters}
+            selectedNode={selectedNode}
+            hoveredNode={hoveredNode}
+            onNodeClick={node => setSelectedNode(node)}
+            onNodeHover={setHoveredNode}
+            width={dims.width}
+            height={dims.height}
+          />
+        ) : null}
+
+        <GraphFilterSidebar filters={filters} onFiltersChange={setFilters} topology={topology} />
+
+        <SectionDrawer
+          content={sectionContent}
+          isLoading={isSectionLoading}
+          onClose={() => setSelectedNode(null)}
+          onNodeNavigate={navigateToNode}
+          onChatAboutSection={onChatAboutSection}
+        />
+      </div>
+    </div>
+  );
+}

frontend/src/components/graph/GraphFilterSidebar.tsx

@@ -0,0 +1,155 @@
+'use client';
+
+import { useState } from 'react';
+import { ALL_JURISDICTIONS, JURISDICTION_LABELS } from '@/lib/constants';
+import type { GraphFilters, GraphTopology } from '@/lib/types';
+
+interface Props {
+  filters: GraphFilters;
+  onFiltersChange: (f: GraphFilters) => void;
+  topology: GraphTopology | null;
+}
+
+const JURISDICTION_DOT_CLASSES = {
+  CENTRAL: {
+    on: 'border-[#2db7a3] bg-[#2db7a3] opacity-100',
+    off: 'border-[#2db7a3] bg-transparent opacity-50',
+  },
+  MAHARASHTRA: {
+    on: 'border-[#4e7cff] bg-[#4e7cff] opacity-100',
+    off: 'border-[#4e7cff] bg-transparent opacity-50',
+  },
+  UTTAR_PRADESH: {
+    on: 'border-[#f4b63f] bg-[#f4b63f] opacity-100',
+    off: 'border-[#f4b63f] bg-transparent opacity-50',
+  },
+  KARNATAKA: {
+    on: 'border-[#78b94d] bg-[#78b94d] opacity-100',
+    off: 'border-[#78b94d] bg-transparent opacity-50',
+  },
+  TAMIL_NADU: {
+    on: 'border-[#ff7a59] bg-[#ff7a59] opacity-100',
+    off: 'border-[#ff7a59] bg-transparent opacity-50',
+  },
+} as const;
+
+export function GraphFilterSidebar({ filters, onFiltersChange, topology }: Props) {
+  const [collapsed, setCollapsed] = useState(false);
+
+  function toggleJurisdiction(j: (typeof ALL_JURISDICTIONS)[number]) {
+    const next = new Set(filters.jurisdictions);
+    if (next.has(j)) {
+      next.delete(j);
+    } else {
+      next.add(j);
+    }
+    onFiltersChange({ ...filters, jurisdictions: next });
+  }
+
+  function toggleEdgeType(t: 'REFERENCES' | 'DERIVED_FROM') {
+    const next = new Set(filters.edgeTypes);
+    if (next.has(t)) {
+      next.delete(t);
+    } else {
+      next.add(t);
+    }
+    onFiltersChange({ ...filters, edgeTypes: next });
+  }
+
+  return (
+    <div className="absolute left-3 top-3 z-10 w-48 border border-white/[0.07] bg-[#141414]/95 text-xs text-white/60 shadow-[0_18px_60px_rgba(0,0,0,0.32)] backdrop-blur">
+      <button
+        className="flex w-full items-center gap-2 px-3 py-2.5 text-left font-mono text-[10px] uppercase tracking-[0.22em] text-white/40 transition-colors hover:text-white/70 active:scale-[0.99]"
+        onClick={() => setCollapsed(value => !value)}
+        aria-label="Toggle graph filters"
+        type="button"
+      >
+        <span className="h-1.5 w-1.5 rounded-full bg-[#4f98a3]" />
+        Filters
+        <span className={`ml-auto transition-transform duration-150 ease-out ${collapsed ? '-rotate-90' : ''}`}>
+          &#x25BC;
+        </span>
+      </button>
+
+      {!collapsed ? (
+        <div className="space-y-4 border-t border-white/[0.05] px-3 pb-3 pt-3">
+          <section>
+            <p className="mb-2 font-mono text-[9px] uppercase tracking-[0.22em] text-white/30">Jurisdictions</p>
+            <div className="space-y-1">
+              {ALL_JURISDICTIONS.map(j => (
+                <label
+                  key={j}
+                  className="flex cursor-pointer items-center gap-2 py-0.5 transition-colors hover:text-white/80"
+                >
+                  <input
+                    type="checkbox"
+                    checked={filters.jurisdictions.has(j)}
+                    onChange={() => toggleJurisdiction(j)}
+                    className="sr-only"
+                  />
+                  <span
+                    className={`h-2.5 w-2.5 shrink-0 rounded-full border transition-[background-color,opacity] duration-150 ease-out ${
+                      filters.jurisdictions.has(j) ? JURISDICTION_DOT_CLASSES[j].on : JURISDICTION_DOT_CLASSES[j].off
+                    }`}
+                  />
+                  <span>{JURISDICTION_LABELS[j]}</span>
+                </label>
+              ))}
+            </div>
+          </section>
+
+          <section>
+            <p className="mb-2 font-mono text-[9px] uppercase tracking-[0.22em] text-white/30">Relationship</p>
+            {(['REFERENCES', 'DERIVED_FROM'] as const).map(t => (
+              <label
+                key={t}
+                className="flex cursor-pointer items-center gap-2 py-0.5 transition-colors hover:text-white/80"
+              >
+                <input
+                  type="checkbox"
+                  checked={filters.edgeTypes.has(t)}
+                  onChange={() => toggleEdgeType(t)}
+                  className="sr-only"
+                />
+                <span
+                  className={`h-px w-4 shrink-0 transition-opacity ${
+                    filters.edgeTypes.has(t) ? 'opacity-100' : 'opacity-25'
+                  } ${
+                    t === 'REFERENCES'
+                      ? 'bg-white/40'
+                      : 'border-t border-dashed border-[#e8af34]/80 bg-transparent'
+                  }`}
+                />
+                <span>{t === 'REFERENCES' ? 'References' : 'Derived from'}</span>
+              </label>
+            ))}
+          </section>
+
+          <section>
+            <p className="mb-2 font-mono text-[9px] uppercase tracking-[0.22em] text-white/30">Node scale</p>
+            {(['connections', 'uniform'] as const).map(mode => (
+              <label
+                key={mode}
+                className="flex cursor-pointer items-center gap-2 py-0.5 transition-colors hover:text-white/80"
+              >
+                <input
+                  type="radio"
+                  name="nodeSizeMode"
+                  checked={filters.nodeSizeMode === mode}
+                  onChange={() => onFiltersChange({ ...filters, nodeSizeMode: mode })}
+                  className="sr-only"
+                />
+                <span
+                  className={`h-2.5 w-2.5 shrink-0 rounded-full border border-white/40 transition-colors duration-150 ease-out ${
+                    filters.nodeSizeMode === mode ? 'bg-white/90' : 'bg-transparent'
+                  }`}
+                />
+                <span>{mode === 'connections' ? 'By connections' : 'Uniform'}</span>
+              </label>
+            ))}
+          </section>
+        </div>
+      ) : null}
+    </div>
+  );
+}

frontend/src/components/graph/NodeInfoCard.tsx

@@ -0,0 +1,112 @@
+'use client';
+
+import { JURISDICTION_COLORS, JURISDICTION_LABELS } from '@/lib/constants';
+import type { GraphNode, SectionContent } from '@/lib/types';
+
+interface Props {
+  node: GraphNode;
+  sectionContent: SectionContent | null;
+  isSectionLoading: boolean;
+  onChatAboutSection: (sectionId: string, title: string, docName: string, jurisdiction: string) => void;
+  onClose: () => void;
+}
+
+export function NodeInfoCard({
+  node,
+  sectionContent,
+  isSectionLoading,
+  onChatAboutSection,
+  onClose,
+}: Props) {
+  const color = JURISDICTION_COLORS[node.jurisdiction] ?? '#888';
+  const refsOut = sectionContent?.connected_sections.filter(s => s.edge_type === 'REFERENCES_OUT') ?? [];
+  const refsIn = sectionContent?.connected_sections.filter(s => s.edge_type === 'REFERENCES_IN') ?? [];
+  const derivedOut = sectionContent?.connected_sections.filter(s => s.edge_type === 'DERIVED_FROM_OUT') ?? [];
+  const derivedIn = sectionContent?.connected_sections.filter(s => s.edge_type === 'DERIVED_FROM_IN') ?? [];
+  const hasRelationships = refsOut.length > 0 || refsIn.length > 0 || derivedOut.length > 0 || derivedIn.length > 0;
+
+  return (
+    <aside className="absolute right-3 top-3 z-20 w-72 border border-white/[0.07] bg-[#141414]/95 text-xs text-white/60 shadow-[0_22px_70px_rgba(0,0,0,0.36)] backdrop-blur">
+      <div className="border-b border-white/[0.06] px-3 py-3">
+        <div className="flex items-start justify-between gap-3">
+          <div className="min-w-0 flex-1">
+            <div className="mb-1 flex items-center gap-2">
+              <span className="font-mono text-[10px] uppercase tracking-[0.2em] text-white/30">Sec</span>
+              <span className="truncate text-[13px] font-semibold text-white/90">{node.section_id}</span>
+              <span
+                className="shrink-0 px-1.5 py-0.5 font-mono text-[9px] uppercase tracking-[0.14em]"
+                style={{ backgroundColor: `${color}24`, color }}
+              >
+                {JURISDICTION_LABELS[node.jurisdiction] ?? node.jurisdiction}
+              </span>
+            </div>
+            <p className="line-clamp-2 text-[12px] leading-5 text-white/70">{node.title}</p>
+            <p className="mt-1 truncate font-mono text-[9px] uppercase tracking-[0.14em] text-white/30">
+              {node.doc_name}
+            </p>
+          </div>
+          <button
+            onClick={onClose}
+            className="text-white/30 transition-colors hover:text-white/70 active:scale-95"
+            aria-label="Close section summary"
+            type="button"
+          >
+            x
+          </button>
+        </div>
+      </div>
+
+      <div className="grid grid-cols-2 border-b border-white/[0.05]">
+        <div className="border-r border-white/[0.05] px-3 py-2">
+          <p className="font-mono text-[9px] uppercase tracking-[0.18em] text-white/25">Links</p>
+          <p className="mt-0.5 text-sm text-white/75">{node.connection_count}</p>
+        </div>
+        <div className="px-3 py-2">
+          <p className="font-mono text-[9px] uppercase tracking-[0.18em] text-white/25">State</p>
+          <p className="mt-0.5 text-sm text-white/75">{node.is_active ? 'Active' : 'Archived'}</p>
+        </div>
+      </div>
+
+      <div className="ledger-scroll max-h-40 space-y-2 overflow-y-auto px-3 py-3">
+        {isSectionLoading ? (
+          <p className="font-mono text-[10px] uppercase tracking-[0.2em] text-white/30">Loading relationships</p>
+        ) : null}
+
+        {!isSectionLoading && refsOut.length > 0 ? (
+          <RelationshipGroup label="References" values={refsOut.map(s => s.section_id)} />
+        ) : null}
+        {!isSectionLoading && refsIn.length > 0 ? (
+          <RelationshipGroup label="Referenced by" values={refsIn.map(s => s.section_id)} />
+        ) : null}
+        {!isSectionLoading && derivedOut.length > 0 ? (
+          <RelationshipGroup label="Derives from" values={derivedOut.map(s => s.section_id)} />
+        ) : null}
+        {!isSectionLoading && derivedIn.length > 0 ? (
+          <RelationshipGroup label="Derived by" values={derivedIn.map(s => s.section_id)} />
+        ) : null}
+        {!isSectionLoading && !hasRelationships ? (
+          <p className="text-[11px] leading-5 text-white/25">No relationship detail loaded for this node.</p>
+        ) : null}
+      </div>
+
+      <div className="border-t border-white/[0.05] px-3 py-3">
+        <button
+          onClick={() => onChatAboutSection(node.section_id, node.title, node.doc_name, node.jurisdiction)}
+          className="w-full border border-white/[0.09] bg-white/[0.03] px-3 py-2 text-[11px] font-medium text-white/70 transition-[background-color,border-color,transform] duration-150 ease-out hover:border-[#4f98a3]/50 hover:bg-white/[0.06] hover:text-white active:scale-[0.98]"
+          type="button"
+        >
+          Chat about this section
+        </button>
+      </div>
+    </aside>
+  );
+}
+
+function RelationshipGroup({ label, values }: { label: string; values: string[] }) {
+  return (
+    <div>
+      <p className="mb-1 font-mono text-[9px] uppercase tracking-[0.18em] text-white/25">{label}</p>
+      <p className="truncate text-[11px] leading-5 text-white/50">{values.map(value => `Sec ${value}`).join(', ')}</p>
+    </div>
+  );
+}

frontend/src/components/graph/SectionDrawer.tsx

@@ -0,0 +1,133 @@
+'use client';
+
+import { JURISDICTION_COLORS, JURISDICTION_LABELS } from '@/lib/constants';
+import type { SectionContent } from '@/lib/types';
+
+interface Props {
+  content: SectionContent | null;
+  isLoading: boolean;
+  onClose: () => void;
+  onNodeNavigate: (sectionId: string, jurisdiction: string) => void;
+  onChatAboutSection: (sectionId: string, title: string, docName: string, jurisdiction: string) => void;
+}
+
+export function SectionDrawer({
+  content,
+  isLoading,
+  onClose,
+  onNodeNavigate,
+  onChatAboutSection,
+}: Props) {
+  const isOpen = isLoading || content !== null;
+  const color = content ? JURISDICTION_COLORS[content.jurisdiction] ?? '#888' : '#888';
+
+  return (
+    <div
+      className={`absolute inset-x-3 bottom-3 z-20 flex max-h-[42%] min-h-0 flex-col overflow-hidden border border-white/[0.07] bg-[#141414]/95 shadow-[0_22px_70px_rgba(0,0,0,0.4)] backdrop-blur transition-[opacity,transform] duration-200 ease-out ${
+        isOpen ? 'pointer-events-auto translate-y-0 opacity-100' : 'pointer-events-none translate-y-3 opacity-0'
+      }`}
+      aria-hidden={!isOpen}
+    >
+      {content ? (
+        <header className="flex shrink-0 items-start justify-between gap-3 border-b border-white/[0.06] px-4 py-3">
+          <div className="min-w-0 flex-1">
+            <div className="flex flex-wrap items-center gap-2">
+              <span className="font-mono text-[10px] uppercase tracking-[0.22em] text-white/30">Selected statute</span>
+              <span
+                className="px-1.5 py-0.5 font-mono text-[9px] uppercase tracking-[0.14em]"
+                style={{ backgroundColor: `${color}24`, color }}
+              >
+                {JURISDICTION_LABELS[content.jurisdiction] ?? content.jurisdiction}
+              </span>
+              {content.effective_date ? (
+                <span className="font-mono text-[9px] uppercase tracking-[0.14em] text-white/25">
+                  Effective {content.effective_date}
+                </span>
+              ) : null}
+            </div>
+            <p className="mt-1 truncate text-sm font-semibold text-white/90">
+              Sec {content.section_id} / {content.title}
+            </p>
+            <p className="mt-0.5 truncate text-[11px] text-white/30">{content.doc_name}</p>
+          </div>
+
+          <div className="flex shrink-0 items-center gap-3">
+            {content.source_url ? (
+              <a
+                href={content.source_url}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="font-mono text-[9px] uppercase tracking-[0.18em] text-white/30 transition-colors hover:text-[#4f98a3]"
+              >
+                View PDF
+              </a>
+            ) : null}
+            <button
+              onClick={onClose}
+              className="text-white/30 transition-colors hover:text-white/70 active:scale-95"
+              aria-label="Close section drawer"
+              type="button"
+            >
+              x
+            </button>
+          </div>
+        </header>
+      ) : null}
+
+      {isLoading ? (
+        <div className="flex flex-1 items-center justify-center">
+          <div className="flex items-center gap-2 font-mono text-[10px] uppercase tracking-[0.24em] text-white/30">
+            {[0, 1, 2].map(i => (
+              <span
+                key={i}
+                className="h-1.5 w-1.5 rounded-full bg-white/20 animate-pulse"
+                style={{ animationDelay: `${i * 150}ms` }}
+              />
+            ))}
+            Loading section
+          </div>
+        </div>
+      ) : null}
+
+      {!isLoading && content ? (
+        <>
+          <div className="ledger-scroll min-h-0 flex-1 overflow-y-auto px-4 py-3 text-[13px] leading-6 text-white/70">
+            {content.chunks.map((chunk, index) => (
+              <article key={chunk.chunk_id} className={index > 0 ? 'mt-4 border-t border-white/[0.05] pt-4' : ''}>
+                <p className="whitespace-pre-wrap">{chunk.text}</p>
+              </article>
+            ))}
+          </div>
+
+          <footer className="flex shrink-0 items-center gap-3 border-t border-white/[0.06] px-4 py-2.5">
+            <div className="ledger-scroll flex min-w-0 flex-1 gap-1.5 overflow-x-auto">
+              {content.connected_sections.slice(0, 10).map((section, index) => (
+                <button
+                  key={`${section.section_id}-${index}`}
+                  onClick={() => onNodeNavigate(section.section_id, section.jurisdiction)}
+                  className="shrink-0 border border-white/[0.08] bg-white/[0.02] px-2 py-1 font-mono text-[9px] uppercase tracking-[0.14em] text-white/40 transition-[background-color,border-color,color,transform] duration-150 ease-out hover:border-white/20 hover:bg-white/[0.05] hover:text-white/75 active:scale-[0.98]"
+                  type="button"
+                  style={{
+                    borderColor: section.edge_type.startsWith('DERIVED') ? 'rgba(232,175,52,0.28)' : undefined,
+                  }}
+                >
+                  Sec {section.section_id}
+                </button>
+              ))}
+            </div>
+
+            <button
+              onClick={() =>
+                onChatAboutSection(content.section_id, content.title, content.doc_name, content.jurisdiction)
+              }
+              className="shrink-0 border border-[#4f98a3]/35 bg-[#4f98a3]/10 px-3 py-1.5 text-[11px] font-medium text-[#9ed4dc] transition-[background-color,border-color,transform] duration-150 ease-out hover:border-[#4f98a3]/70 hover:bg-[#4f98a3]/16 active:scale-[0.98]"
+              type="button"
+            >
+              Chat about section
+            </button>
+          </footer>
+        </>
+      ) : null}
+    </div>
+  );
+}

frontend/src/hooks/useChat.ts

@@ -0,0 +1,99 @@
+'use client';
+
+import { useCallback, useRef, useState } from 'react';
+import { queryRera, querySectionContext } from '@/lib/api';
+import type { ApiResponse, ChatMessage, Jurisdiction } from '@/lib/types';
+
+const SESSION_KEY = 'civicsetu_session_id';
+
+export interface UseChatReturn {
+  messages: ChatMessage[];
+  isLoading: boolean;
+  sendMessage: (text: string, jurisdiction: Jurisdiction | '') => Promise<void>;
+  sendSectionMessage: (text: string, sectionId: string, jurisdiction: string) => Promise<void>;
+  newConversation: () => void;
+}
+
+export function useChat(): UseChatReturn {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const sessionIdRef = useRef<string | null>(
+    typeof window !== 'undefined' ? window.localStorage.getItem(SESSION_KEY) : null,
+  );
+
+  const _handleResponse = useCallback((data: ApiResponse) => {
+    if (data.session_id) {
+      sessionIdRef.current = data.session_id;
+      if (typeof window !== 'undefined') {
+        window.localStorage.setItem(SESSION_KEY, data.session_id);
+      }
+    }
+    setMessages(prev => [
+      ...prev,
+      { id: crypto.randomUUID(), role: 'assistant', text: data.answer, data },
+    ]);
+  }, []);
+
+  const _handleError = useCallback((error: unknown) => {
+    setMessages(prev => [
+      ...prev,
+      {
+        id: crypto.randomUUID(),
+        role: 'error',
+        text: error instanceof Error ? error.message : 'Request failed',
+      },
+    ]);
+  }, []);
+
+  const sendMessage = useCallback(
+    async (text: string, jurisdiction: Jurisdiction | '') => {
+      setMessages(prev => [...prev, { id: crypto.randomUUID(), role: 'user', text }]);
+      setIsLoading(true);
+      try {
+        const data = await queryRera({
+          query: text,
+          top_k: 5,
+          ...(jurisdiction ? { jurisdiction_filter: jurisdiction } : {}),
+          ...(sessionIdRef.current ? { session_id: sessionIdRef.current } : {}),
+        });
+        _handleResponse(data);
+      } catch (error) {
+        _handleError(error);
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [_handleResponse, _handleError],
+  );
+
+  const sendSectionMessage = useCallback(
+    async (text: string, sectionId: string, jurisdiction: string) => {
+      setMessages(prev => [...prev, { id: crypto.randomUUID(), role: 'user', text }]);
+      setIsLoading(true);
+      try {
+        const data = await querySectionContext({
+          query: text,
+          section_id: sectionId,
+          jurisdiction,
+          ...(sessionIdRef.current ? { session_id: sessionIdRef.current } : {}),
+        });
+        _handleResponse(data);
+      } catch (error) {
+        _handleError(error);
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [_handleResponse, _handleError],
+  );
+
+  const newConversation = useCallback(() => {
+    sessionIdRef.current = null;
+    if (typeof window !== 'undefined') {
+      window.localStorage.removeItem(SESSION_KEY);
+    }
+    setMessages([]);
+  }, []);
+
+  return { messages, isLoading, sendMessage, sendSectionMessage, newConversation };
+}

frontend/src/hooks/useGraphExplorer.ts

@@ -0,0 +1,102 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import { fetchGraphTopology, fetchSectionContent } from '@/lib/api';
+import { ALL_JURISDICTIONS } from '@/lib/constants';
+import type { GraphFilters, GraphNode, GraphTopology, SectionContent } from '@/lib/types';
+
+export interface UseGraphExplorerReturn {
+  topology: GraphTopology | null;
+  isLoading: boolean;
+  error: string | null;
+  selectedNode: GraphNode | null;
+  hoveredNode: GraphNode | null;
+  sectionContent: SectionContent | null;
+  isSectionLoading: boolean;
+  filters: GraphFilters;
+  setSelectedNode: (node: GraphNode | null) => void;
+  setHoveredNode: (node: GraphNode | null) => void;
+  setFilters: (filters: GraphFilters) => void;
+  navigateToNode: (sectionId: string, jurisdiction: string) => void;
+}
+
+export function useGraphExplorer(): UseGraphExplorerReturn {
+  const [topology, setTopology] = useState<GraphTopology | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const [selectedNode, setSelectedNodeRaw] = useState<GraphNode | null>(null);
+  const [hoveredNode, setHoveredNode] = useState<GraphNode | null>(null);
+  const [sectionContent, setSectionContent] = useState<SectionContent | null>(null);
+  const [isSectionLoading, setIsSectionLoading] = useState(false);
+
+  const [filters, setFilters] = useState<GraphFilters>({
+    jurisdictions: new Set(ALL_JURISDICTIONS),
+    edgeTypes: new Set(['REFERENCES', 'DERIVED_FROM']),
+    nodeSizeMode: 'connections',
+  });
+
+  // Fetch topology once on mount
+  useEffect(() => {
+    let cancelled = false;
+    setIsLoading(true);
+    fetchGraphTopology()
+      .then(data => {
+        if (!cancelled) {
+          setTopology(data);
+          setError(null);
+        }
+      })
+      .catch(err => {
+        if (!cancelled) setError((err as Error).message);
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false);
+      });
+    return () => { cancelled = true; };
+  }, []);
+
+  // Fetch section content when a node is selected
+  const setSelectedNode = useCallback((node: GraphNode | null) => {
+    setSelectedNodeRaw(node);
+    if (!node) {
+      setSectionContent(null);
+      return;
+    }
+    setIsSectionLoading(true);
+    fetchSectionContent(node.section_id, node.jurisdiction, node.chunk_id)
+      .then(data => setSectionContent(data))
+      .catch(err => {
+        console.error('Section content fetch failed:', err);
+        setSectionContent(null);
+      })
+      .finally(() => setIsSectionLoading(false));
+  }, []);
+
+  // Navigate to a node by section_id + jurisdiction (called from SectionDrawer chips)
+  const navigateToNode = useCallback(
+    (sectionId: string, jurisdiction: string) => {
+      if (!topology) return;
+      const target = topology.nodes.find(
+        n => n.section_id === sectionId && n.jurisdiction === jurisdiction,
+      );
+      if (target) setSelectedNode(target);
+    },
+    [topology, setSelectedNode],
+  );
+
+  return {
+    topology,
+    isLoading,
+    error,
+    selectedNode,
+    hoveredNode,
+    sectionContent,
+    isSectionLoading,
+    filters,
+    setSelectedNode,
+    setHoveredNode,
+    setFilters,
+    navigateToNode,
+  };
+}

frontend/src/lib/api.ts

@@ -0,0 +1,92 @@
+import type {
+  ApiResponse,
+  GraphTopology,
+  Jurisdiction,
+  SectionContent,
+} from './types';
+
+const API_BASE_URL = process.env.NEXT_PUBLIC_BACKEND_URL ?? '';
+
+function apiUrl(path: string): string {
+  return `${API_BASE_URL}${path}`;
+}
+
+export interface QueryPayload {
+  query: string;
+  session_id?: string;
+  jurisdiction_filter?: Jurisdiction;
+  top_k?: number;
+}
+
+export async function queryRera(payload: QueryPayload): Promise<ApiResponse> {
+  const res = await fetch(apiUrl('/api/v1/query'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+  if (!res.ok) {
+    let detail = res.statusText;
+    try {
+      const err = (await res.json()) as { detail?: string };
+      if (err.detail) detail = err.detail;
+    } catch {}
+    throw new Error(`API error ${res.status}: ${detail}`);
+  }
+  return res.json() as Promise<ApiResponse>;
+}
+
+export async function fetchGraphTopology(): Promise<GraphTopology> {
+  const res = await fetch(apiUrl('/api/v1/graph/topology'));
+  if (!res.ok) {
+    throw new Error(`Topology fetch failed: ${res.status}`);
+  }
+  return res.json() as Promise<GraphTopology>;
+}
+
+export async function fetchSectionContent(
+  sectionId: string,
+  jurisdiction: string,
+  chunkId?: string,
+): Promise<SectionContent> {
+  const params = new URLSearchParams({ jurisdiction });
+  if (chunkId) {
+    params.set('chunk_id', chunkId);
+  }
+  const url = apiUrl(`/api/v1/graph/section/${encodeURIComponent(sectionId)}?${params.toString()}`);
+  const res = await fetch(url);
+  if (!res.ok) {
+    let detail = res.statusText;
+    try {
+      const err = (await res.json()) as { detail?: string };
+      if (err.detail) detail = err.detail;
+    } catch {}
+    throw new Error(`Section fetch failed: ${res.status} ${detail}`);
+  }
+  return res.json() as Promise<SectionContent>;
+}
+
+export interface SectionContextPayload {
+  query: string;
+  section_id: string;
+  jurisdiction: string;
+  session_id?: string;
+}
+
+export async function querySectionContext(
+  payload: SectionContextPayload,
+): Promise<ApiResponse> {
+  const res = await fetch(apiUrl('/api/v1/query/section-context'), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+  if (!res.ok) {
+    let detail = res.statusText;
+    try {
+      const err = (await res.json()) as { detail?: string };
+      if (err.detail) detail = err.detail;
+    } catch {}
+    throw new Error(`API error ${res.status}: ${detail}`);
+  }
+  return res.json() as Promise<ApiResponse>;
+}

frontend/src/lib/constants.ts

@@ -0,0 +1,44 @@
+import type { Jurisdiction } from './types';
+
+export const JURISDICTION_COLORS: Record<Jurisdiction, string> = {
+  CENTRAL:       '#2db7a3',
+  MAHARASHTRA:   '#4e7cff',
+  UTTAR_PRADESH: '#f4b63f',
+  KARNATAKA:     '#78b94d',
+  TAMIL_NADU:    '#ff7a59',
+};
+
+export const EDGE_STYLES = {
+  REFERENCES: {
+    color: 'rgba(255,255,255,0.15)',
+    dashArray: 'none',
+    width: 1,
+  },
+  DERIVED_FROM: {
+    color: '#e8af34',
+    dashArray: '6,3',
+    width: 1.5,
+  },
+} as const;
+
+export const NODE_RADIUS = {
+  MIN: 4,
+  MAX: 18,
+  DEFAULT: 6,
+} as const;
+
+export const ALL_JURISDICTIONS: Jurisdiction[] = [
+  'CENTRAL',
+  'MAHARASHTRA',
+  'UTTAR_PRADESH',
+  'KARNATAKA',
+  'TAMIL_NADU',
+];
+
+export const JURISDICTION_LABELS: Record<Jurisdiction, string> = {
+  CENTRAL:       'Central',
+  MAHARASHTRA:   'Maharashtra',
+  UTTAR_PRADESH: 'Uttar Pradesh',
+  KARNATAKA:     'Karnataka',
+  TAMIL_NADU:    'Tamil Nadu',
+};

frontend/src/lib/types.ts

@@ -0,0 +1,122 @@
+export type Jurisdiction =
+  | 'CENTRAL'
+  | 'MAHARASHTRA'
+  | 'UTTAR_PRADESH'
+  | 'KARNATAKA'
+  | 'TAMIL_NADU';
+
+export type QueryType =
+  | 'fact_lookup'
+  | 'cross_reference'
+  | 'conflict_detection'
+  | 'temporal'
+  | 'penalty_lookup';
+
+export interface Citation {
+  section_id: string;
+  doc_name: string;
+  jurisdiction: Jurisdiction;
+  effective_date: string | null;
+  source_url: string;
+  chunk_id: string;
+}
+
+export interface CivicSetuResponse {
+  answer: string;
+  citations: Citation[];
+  confidence_score: number;
+  query_type_resolved: QueryType;
+  conflict_warnings: string[];
+  amendment_notice: string | null;
+  session_id: string | null;
+  disclaimer: string;
+  confidence_level: 'HIGH' | 'MEDIUM' | 'LOW';
+}
+
+export interface InsufficientInfoResponse {
+  answer: string;
+  searched_query: string;
+  session_id: string | null;
+  disclaimer: string;
+}
+
+export type ApiResponse = CivicSetuResponse | InsufficientInfoResponse;
+
+export function isCivicSetuResponse(r: ApiResponse): r is CivicSetuResponse {
+  return 'citations' in r && Array.isArray(r.citations);
+}
+
+export interface ChatMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'error';
+  text: string;
+  data?: ApiResponse;
+}
+
+// ── Graph Types ───────────────────────────────────────────────────────────────
+
+export interface GraphNode {
+  chunk_id: string;
+  section_id: string;
+  title: string;
+  jurisdiction: Jurisdiction;
+  doc_name: string;
+  is_active: boolean;
+  connection_count: number;
+  // D3 simulation fields, mutated in place by force simulation.
+  x?: number;
+  y?: number;
+  vx?: number;
+  vy?: number;
+  fx?: number | null;
+  fy?: number | null;
+}
+
+export interface GraphEdge {
+  source: string | GraphNode;
+  target: string | GraphNode;
+  edge_type: 'REFERENCES' | 'DERIVED_FROM';
+}
+
+export interface GraphTopology {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  stats: Record<string, number>;
+}
+
+export interface SectionChunk {
+  chunk_id: string;
+  text: string;
+  page_number: number;
+}
+
+export interface ConnectedSection {
+  section_id: string;
+  title: string;
+  jurisdiction: Jurisdiction;
+  edge_type: 'REFERENCES_OUT' | 'REFERENCES_IN' | 'DERIVED_FROM_OUT' | 'DERIVED_FROM_IN';
+}
+
+export interface SectionContent {
+  section_id: string;
+  title: string;
+  doc_name: string;
+  jurisdiction: Jurisdiction;
+  effective_date: string | null;
+  source_url: string;
+  chunks: SectionChunk[];
+  connected_sections: ConnectedSection[];
+}
+
+export interface GraphFilters {
+  jurisdictions: Set<Jurisdiction>;
+  edgeTypes: Set<'REFERENCES' | 'DERIVED_FROM'>;
+  nodeSizeMode: 'connections' | 'uniform';
+}
+
+export interface SectionContext {
+  sectionId: string;
+  title: string;
+  docName: string;
+  jurisdiction: string;
+}

frontend/tailwind.config.ts

@@ -0,0 +1,31 @@
+import type { Config } from 'tailwindcss';
+
+const config: Config = {
+  content: [
+    './src/pages/**/*.{js,ts,jsx,tsx,mdx}',
+    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
+    './src/app/**/*.{js,ts,jsx,tsx,mdx}',
+  ],
+  darkMode: 'class',
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['var(--font-inter)', 'Inter', 'sans-serif'],
+        serif: ['var(--font-merriweather)', 'Merriweather', 'serif'],
+      },
+        colors: {
+          graph: {
+            bg:           '#0d0d0d',
+            central:      '#2db7a3',
+            maharashtra:  '#4e7cff',
+            uttar_pradesh:'#f4b63f',
+            karnataka:    '#78b94d',
+            tamil_nadu:   '#ff7a59',
+          },
+        },
+    },
+  },
+  plugins: [],
+};
+
+export default config;

frontend/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

pyproject.toml

@@ -10,6 +10,7 @@ requires-python = ">=3.11"
 dependencies = [
     # --- LLM & Orchestration ---
     "langgraph>=0.3.0",
+    "langgraph-checkpoint-postgres>=2.0.0",
     "langchain>=0.3.0",
     "langchain-core>=0.3.0",
     "langchain-google-genai>=2.0.0",
@@ -43,6 +44,7 @@ dependencies = [
     # --- Utilities ---
     "python-dotenv>=1.0.0",
     "tenacity>=8.3.0",
+    "cachetools>=5.3.0",
     "structlog>=24.0.0",
     "einops>=0.8.2",
     "huggingface-hub[cli]>=1.7.1",

src/civicsetu/agent/graph.py

@@ -1,17 +1,19 @@
 from __future__ import annotations
 
 import structlog
+from langgraph.checkpoint.base import BaseCheckpointSaver
 from langgraph.graph import END, StateGraph
 
 from civicsetu.agent.edges import route_after_classifier, route_after_validator
 from civicsetu.agent.nodes import (
     classifier_node,
     generator_node,
+    graph_retrieval_node,
+    hybrid_retrieval_node,
     reranker_node,
+    turn_reset_node,
     validator_node,
     vector_retrieval_node,
-    graph_retrieval_node,
-    hybrid_retrieval_node,
 )
 from civicsetu.agent.state import CivicSetuState
 
@@ -32,33 +34,31 @@ def _retry_node(state: CivicSetuState) -> dict:
 def build_graph() -> StateGraph:
     graph = StateGraph(CivicSetuState)
 
-    # ── Register nodes ─────────────────────────────────────────────────────────
-    graph.add_node("classifier",        classifier_node)
-    graph.add_node("vector_retrieval",  vector_retrieval_node)
-    graph.add_node("graph_retrieval",   graph_retrieval_node)
-    graph.add_node("reranker",          reranker_node)
-    graph.add_node("generator",         generator_node)
-    graph.add_node("validator",         validator_node)
-    graph.add_node("retry",             _retry_node)
-    graph.add_node("hybrid_retrieval",  hybrid_retrieval_node)
-
-    # ── Entry point ────────────────────────────────────────────────────────────
-    graph.set_entry_point("classifier")
+    graph.add_node("turn_reset", turn_reset_node)
+    graph.add_node("classifier", classifier_node)
+    graph.add_node("vector_retrieval", vector_retrieval_node)
+    graph.add_node("graph_retrieval", graph_retrieval_node)
+    graph.add_node("reranker", reranker_node)
+    graph.add_node("generator", generator_node)
+    graph.add_node("validator", validator_node)
+    graph.add_node("retry", _retry_node)
+    graph.add_node("hybrid_retrieval", hybrid_retrieval_node)
 
-    # ── Edges ──────────────────────────────────────────────────────────────────
+    graph.set_entry_point("turn_reset")
+    graph.add_edge("turn_reset", "classifier")
     graph.add_conditional_edges(
         "classifier",
         route_after_classifier,
         {
             "vector_retrieval": "vector_retrieval",
-            "graph_retrieval":  "graph_retrieval",
+            "graph_retrieval": "graph_retrieval",
             "hybrid_retrieval": "hybrid_retrieval",
         },
     )
     graph.add_edge("vector_retrieval", "reranker")
-    graph.add_edge("graph_retrieval",  "reranker")
-    graph.add_edge("reranker",         "generator")
-    graph.add_edge("generator",        "validator")
+    graph.add_edge("graph_retrieval", "reranker")
+    graph.add_edge("reranker", "generator")
+    graph.add_edge("generator", "validator")
     graph.add_conditional_edges(
         "validator",
         route_after_validator,
@@ -70,6 +70,6 @@ def build_graph() -> StateGraph:
     return graph
 
 
-def get_compiled_graph():
+def get_compiled_graph(checkpointer: BaseCheckpointSaver | None = None):
     """Returns the compiled, executable LangGraph. Call once, reuse."""
-    return build_graph().compile()
+    return build_graph().compile(checkpointer=checkpointer)

src/civicsetu/agent/nodes.py

@@ -2,35 +2,70 @@ from __future__ import annotations
 
 import asyncio
 import json
+import time
 
 import litellm
 import structlog
 
 from civicsetu.agent.state import CivicSetuState
 from civicsetu.config.settings import get_settings
-from civicsetu.ingestion.embedder import Embedder
 from civicsetu.models.enums import QueryType, Jurisdiction
 from civicsetu.models.schemas import Citation, RetrievedChunk
 from civicsetu.prompts.classifier import CLASSIFIER_PROMPT
 from civicsetu.prompts.generator import GENERATOR_PROMPT
-from civicsetu.prompts.validator import VALIDATOR_PROMPT
+from civicsetu.retrieval import cached_embed
 from civicsetu.stores.relational_store import AsyncSessionLocal
 from civicsetu.stores.vector_store import VectorStore
 
 log = structlog.get_logger(__name__)
 settings = get_settings()
-_embedder = Embedder()
+_ranker = None
 
 
 # ── LiteLLM fallback chain ─────────────────────────────────────────────────────
 
 FALLBACK_MODELS = [
     settings.primary_model,
-    settings.fallback_model_1,
     settings.fallback_model_2,
+    settings.fallback_model_1,
 ]
 
 
+def _get_ranker():
+    global _ranker
+    if _ranker is not None:
+        return _ranker
+
+    from flashrank import Ranker
+    ranker = Ranker(model_name="ms-marco-MiniLM-L-12-v2", cache_dir=".cache/flashrank")
+
+    # Do not cache unittest mocks, otherwise tests that patch Ranker bleed into each other.
+    if type(ranker).__module__ != "unittest.mock":
+        _ranker = ranker
+    return ranker
+
+
+def turn_reset_node(state: CivicSetuState) -> dict:
+    """
+    Clear per-turn fields while preserving session-scoped inputs and messages.
+    """
+    log.info("turn_reset", session_id=state.get("session_id"))
+    return {
+        "query_type": None,
+        "rewritten_query": None,
+        "retrieved_chunks": [],
+        "reranked_chunks": [],
+        "raw_response": None,
+        "citations": [],
+        "confidence_score": 0.0,
+        "conflict_warnings": [],
+        "amendment_notice": None,
+        "retry_count": 0,
+        "hallucination_flag": False,
+        "error": None,
+    }
+
+
 def _llm_call(prompt: str, system: str, temperature: float = 0.0) -> str:
     """
     LiteLLM call with automatic fallback chain.
@@ -42,6 +77,7 @@ def _llm_call(prompt: str, system: str, temperature: float = 0.0) -> str:
     ]
     last_error = None
     for model in FALLBACK_MODELS:
+        start = time.perf_counter()
         try:
             # Gemini 3.x models degrade below temperature=1.0
             effective_temp = 1.0 if "gemini-3" in model else temperature
@@ -51,9 +87,22 @@ def _llm_call(prompt: str, system: str, temperature: float = 0.0) -> str:
                 temperature=effective_temp,
                 max_tokens=1024,
             )
-            return response.choices[0].message.content.strip()
+            duration_ms = round((time.perf_counter() - start) * 1000, 2)
+            content = response.choices[0].message.content.strip()
+            usage = getattr(response, "usage", None)
+            log.info(
+                "llm_call_complete",
+                model=model,
+                duration_ms=duration_ms,
+                prompt_chars=len(prompt),
+                output_chars=len(content),
+                prompt_tokens=getattr(usage, "prompt_tokens", None) if usage else None,
+                completion_tokens=getattr(usage, "completion_tokens", None) if usage else None,
+            )
+            return content
         except Exception as e:
-            log.warning("llm_fallback", model=model, error=str(e))
+            duration_ms = round((time.perf_counter() - start) * 1000, 2)
+            log.warning("llm_fallback", model=model, duration_ms=duration_ms, error=str(e))
             last_error = e
             continue
 
@@ -67,6 +116,16 @@ def classifier_node(state: CivicSetuState) -> dict:
     Classifies query type and rewrites the query for better retrieval.
     Returns: query_type, rewritten_query
     """
+    node_start = time.perf_counter()
+    # ── Skip classifier for graph-context queries (section drawer flow) ───────
+    if state.get("skip_classifier"):
+        log.info("classifier_node_skipped", reason="skip_classifier=True")
+        log.info("node_timing", node="classifier", duration_ms=round((time.perf_counter() - node_start) * 1000, 2))
+        return {
+            "query_type": state["query_type"],
+            "rewritten_query": state.get("rewritten_query") or state["query"],
+        }
+    # ─────────────────────────────────────────────────────────────────────────
     query = state["query"]
     log.info("classifier_node", query=query[:80])
 
@@ -93,6 +152,7 @@ def classifier_node(state: CivicSetuState) -> dict:
         rewritten = query
 
     log.info("classified", query_type=query_type.value, rewritten=rewritten[:80])
+    log.info("node_timing", node="classifier", duration_ms=round((time.perf_counter() - node_start) * 1000, 2))
     return {"query_type": query_type, "rewritten_query": rewritten}
 
 
@@ -112,10 +172,13 @@ def vector_retrieval_node(state: CivicSetuState) -> dict:
     query = state.get("rewritten_query") or state["query"]
     top_k = state.get("top_k", 5)
     jurisdiction = state.get("jurisdiction_filter")
+    node_start = time.perf_counter()
 
     log.info("vector_retrieval_node", query=query[:80], top_k=top_k)
 
-    query_embedding = _embedder.embed_query(query)
+    embed_start = time.perf_counter()
+    query_embedding = cached_embed(query)
+    log.info("stage_timing", node="vector_retrieval", stage="embedding", duration_ms=round((time.perf_counter() - embed_start) * 1000, 2))
 
     async def _retrieve():
         async with AsyncSessionLocal() as session:
@@ -157,7 +220,10 @@ def vector_retrieval_node(state: CivicSetuState) -> dict:
             )
             return expanded
 
+    retrieve_start = time.perf_counter()
     chunks = asyncio.run(_retrieve())
+    log.info("stage_timing", node="vector_retrieval", stage="postgres_retrieval", duration_ms=round((time.perf_counter() - retrieve_start) * 1000, 2))
+    log.info("node_timing", node="vector_retrieval", duration_ms=round((time.perf_counter() - node_start) * 1000, 2), results=len(chunks))
     return {"retrieved_chunks": chunks}
 
 
@@ -172,6 +238,7 @@ def graph_retrieval_node(state: CivicSetuState) -> dict:
     query = state.get("rewritten_query") or state["query"]
     jurisdiction = state.get("jurisdiction_filter")
     top_k = state.get("top_k", 5)
+    node_start = time.perf_counter()
 
     log.info("graph_retrieval_node", query=query[:80])
 
@@ -180,16 +247,21 @@ def graph_retrieval_node(state: CivicSetuState) -> dict:
             query=query,
             jurisdiction=jurisdiction,
             depth=2,
+            source_section_id=state.get("source_section_id"),
         )
 
+    retrieve_start = time.perf_counter()
     chunks = asyncio.run(_retrieve())
     log.info("graph_retrieval_complete", results=len(chunks))
+    log.info("stage_timing", node="graph_retrieval", stage="neo4j_postgres_hydration", duration_ms=round((time.perf_counter() - retrieve_start) * 1000, 2))
     
     # Fallback: if graph found nothing (no explicit section in query),
     # run vector retrieval instead
     if not chunks:
         log.info("graph_retrieval_fallback_to_vector", query=query[:80])
-        query_embedding = _embedder.embed_query(query)
+        embed_start = time.perf_counter()
+        query_embedding = cached_embed(query)
+        log.info("stage_timing", node="graph_retrieval", stage="fallback_embedding", duration_ms=round((time.perf_counter() - embed_start) * 1000, 2))
 
         async def _vector_fallback():
             async with AsyncSessionLocal() as session:
@@ -201,7 +273,9 @@ def graph_retrieval_node(state: CivicSetuState) -> dict:
                     active_only=True,
                 )
 
+        fallback_start = time.perf_counter()
         chunks = asyncio.run(_vector_fallback())
+        log.info("stage_timing", node="graph_retrieval", stage="fallback_vector_search", duration_ms=round((time.perf_counter() - fallback_start) * 1000, 2))
         log.info("graph_fallback_complete", results=len(chunks))
 
     _MAX_GRAPH_CHUNKS = 25
@@ -213,6 +287,7 @@ def graph_retrieval_node(state: CivicSetuState) -> dict:
         )
         chunks = chunks[:_MAX_GRAPH_CHUNKS]
         
+    log.info("node_timing", node="graph_retrieval", duration_ms=round((time.perf_counter() - node_start) * 1000, 2), results=len(chunks))
     return {"retrieved_chunks": chunks}
     
 # ── Node 3: Reranker ───────────────────────────────────────────────────────────
@@ -223,12 +298,14 @@ def reranker_node(state: CivicSetuState) -> dict:
     Deduplicates by chunk_id first, then scores.
     Returns: reranked_chunks (top 5 max)
     """
-    from flashrank import Ranker, RerankRequest
+    from flashrank import RerankRequest
 
     chunks = state.get("retrieved_chunks", [])
     query = state.get("rewritten_query") or state["query"]
+    node_start = time.perf_counter()
 
     if not chunks:
+        log.info("node_timing", node="reranker", duration_ms=round((time.perf_counter() - node_start) * 1000, 2), reranked=0)
         return {"reranked_chunks": []}
 
     # Deduplicate by chunk_id
@@ -247,10 +324,14 @@ def reranker_node(state: CivicSetuState) -> dict:
     rankable = [c for c in unique_chunks if not c.is_pinned]
 
     try:
-        ranker = Ranker(model_name="ms-marco-MiniLM-L-12-v2", cache_dir=".cache/flashrank")
+        init_start = time.perf_counter()
+        ranker = _get_ranker()
+        log.info("stage_timing", node="reranker", stage="ranker_init", duration_ms=round((time.perf_counter() - init_start) * 1000, 2))
         passages = [{"id": i, "text": c.chunk.text} for i, c in enumerate(rankable)]
         request = RerankRequest(query=query, passages=passages)
+        inference_start = time.perf_counter()
         results = ranker.rerank(request)
+        log.info("stage_timing", node="reranker", stage="ranker_inference", duration_ms=round((time.perf_counter() - inference_start) * 1000, 2), passages=len(passages))
 
         # Map scores back to chunks
         id_to_chunk = {i: c for i, c in enumerate(rankable)}
@@ -270,6 +351,7 @@ def reranker_node(state: CivicSetuState) -> dict:
         reranked = pinned + rankable[:slots_for_ranked]
 
     log.info("reranker_complete", reranked=len(reranked), pinned=len(pinned))
+    log.info("node_timing", node="reranker", duration_ms=round((time.perf_counter() - node_start) * 1000, 2), unique_chunks=len(unique_chunks), rankable=len(rankable), pinned=len(pinned), reranked=len(reranked))
     return {"reranked_chunks": reranked}
 
 
@@ -284,8 +366,11 @@ def generator_node(state: CivicSetuState) -> dict:
     """
     query = state["query"]
     chunks: list[RetrievedChunk] = state.get("reranked_chunks", [])
+    messages = state.get("messages", [])
+    node_start = time.perf_counter()
 
     if not chunks:
+        log.info("node_timing", node="generator", duration_ms=round((time.perf_counter() - node_start) * 1000, 2), context_chunks=0)
         return {
             "raw_response": "Insufficient information found in indexed documents.",
             "citations": [],
@@ -305,7 +390,34 @@ def generator_node(state: CivicSetuState) -> dict:
         )
     context = "\n---\n".join(context_parts)
 
-    prompt = GENERATOR_PROMPT.format(query=query, context=context)
+    recent_messages = messages[-6:]
+    if recent_messages:
+        history_lines = []
+        for message in recent_messages:
+            role = getattr(message, "role", None)
+            content = getattr(message, "content", None)
+            if role is None and isinstance(message, dict):
+                role = message.get("role")
+                content = message.get("content")
+            if not role or not content:
+                continue
+            role_label = "User" if role == "user" else "Assistant"
+            history_lines.append(f"{role_label}: {content}")
+        conversation_history_block = (
+            "Prior conversation (for context only; answer the current question):\n"
+            + "\n".join(history_lines)
+            + "\n\n"
+            if history_lines
+            else ""
+        )
+    else:
+        conversation_history_block = ""
+
+    prompt = GENERATOR_PROMPT.format(
+        query=query,
+        context=context,
+        conversation_history_block=conversation_history_block,
+    )
     system = (
         "You are CivicSetu, a legal information assistant for Indian law. "
         "Answer only from the provided context. "
@@ -313,10 +425,17 @@ def generator_node(state: CivicSetuState) -> dict:
         "Respond with valid JSON only."
     )
 
-    log.info("generator_node", query=query[:80], context_chunks=len(chunks))
+    log.info(
+        "generator_node",
+        query=query[:80],
+        context_chunks=len(chunks),
+        history_messages=len(recent_messages),
+    )
 
     try:
+        llm_start = time.perf_counter()
         raw = _llm_call(prompt, system, temperature=0.0)
+        log.info("stage_timing", node="generator", stage="llm", duration_ms=round((time.perf_counter() - llm_start) * 1000, 2))
         raw = raw.strip().removeprefix("```json").removeprefix("```").removesuffix("```").strip()
         result = json.loads(raw)
 
@@ -382,6 +501,7 @@ def generator_node(state: CivicSetuState) -> dict:
         conflict_warnings = []
         amendment_notice = None
 
+    log.info("node_timing", node="generator", duration_ms=round((time.perf_counter() - node_start) * 1000, 2), context_chunks=len(chunks))
     return {
         "raw_response": answer,
         "citations": citations,
@@ -397,40 +517,16 @@ def generator_node(state: CivicSetuState) -> dict:
 def validator_node(state: CivicSetuState) -> dict:
     answer = state.get("raw_response", "")
     chunks = state.get("reranked_chunks", [])
+    node_start = time.perf_counter()
 
     if not answer or not chunks:
+        log.info("node_timing", node="validator", duration_ms=round((time.perf_counter() - node_start) * 1000, 2), skipped=True)
         return {"hallucination_flag": False, "confidence_score": 0.5}
 
-    # Build context with section metadata — same format as generator_node
-    # so the validator can verify citations like "Section 11(1)" actually exist
-    context_parts = []
-    for i, rc in enumerate(chunks, 1):
-        c = rc.chunk
-        context_parts.append(
-            f"[{i}] {c.doc_name} — {c.section_id}: {c.section_title}\n"
-            f"Effective: {c.effective_date}\n"
-            f"{c.text}\n"
-        )
-    context = "\n---\n".join(context_parts)
-
-    query_type = str(state.get("query_type", "fact_lookup"))
-    prompt = VALIDATOR_PROMPT.format(
-        query_type=query_type, answer=answer, context=context
-    )
-    system = "You are a factual grounding scorer. Respond with JSON only."
-
-    try:
-        raw = _llm_call(prompt, system)
-        raw = raw.strip().removeprefix("```json").removeprefix("```").removesuffix("```").strip()
-        result = json.loads(raw)
-        updated_score = float(result.get("confidence_score", 0.5))
-        hallucinated = updated_score < 0.3
-    except Exception as e:
-        log.warning("validator_failed", error=str(e))
-        updated_score = state.get("confidence_score", 0.5)
-        hallucinated = False
-
+    updated_score = state.get("confidence_score", 0.5)
+    hallucinated = updated_score < 0.2
     log.info("validator_node", confidence=updated_score, hallucinated=hallucinated)
+    log.info("node_timing", node="validator", duration_ms=round((time.perf_counter() - node_start) * 1000, 2))
     return {
         "hallucination_flag": hallucinated,
         "confidence_score": updated_score,
@@ -448,10 +544,13 @@ def hybrid_retrieval_node(state: CivicSetuState) -> dict:
     query = state.get("rewritten_query") or state["query"]
     top_k = state.get("top_k", 5)
     jurisdiction = state.get("jurisdiction_filter")
+    node_start = time.perf_counter()
 
     log.info("hybrid_retrieval_node", query=query[:80])
 
-    query_embedding = _embedder.embed_query(query)
+    embed_start = time.perf_counter()
+    query_embedding = cached_embed(query)
+    log.info("stage_timing", node="hybrid_retrieval", stage="embedding", duration_ms=round((time.perf_counter() - embed_start) * 1000, 2))
 
     async def _retrieve():
         async with AsyncSessionLocal() as session:
@@ -481,7 +580,9 @@ def hybrid_retrieval_node(state: CivicSetuState) -> dict:
 
         return v_chunks, g_chunks
 
+    retrieve_start = time.perf_counter()
     v_chunks, g_chunks = asyncio.run(_retrieve())
+    log.info("stage_timing", node="hybrid_retrieval", stage="vector_graph_parallel", duration_ms=round((time.perf_counter() - retrieve_start) * 1000, 2))
 
     log.info(
         "hybrid_retrieval_complete",
@@ -489,5 +590,6 @@ def hybrid_retrieval_node(state: CivicSetuState) -> dict:
         graph_chunks=len(g_chunks),
         total=len(v_chunks) + len(g_chunks),
     )
+    log.info("node_timing", node="hybrid_retrieval", duration_ms=round((time.perf_counter() - node_start) * 1000, 2), total=len(v_chunks) + len(g_chunks))
     # Return both — reranker deduplicates by chunk_id
     return {"retrieved_chunks": v_chunks + g_chunks}

src/civicsetu/agent/state.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
 import operator
-from typing import Annotated
+from typing import Annotated, NotRequired
 
 from typing_extensions import TypedDict
 
 from civicsetu.models.enums import Jurisdiction, QueryType
-from civicsetu.models.schemas import Citation, RetrievedChunk
+from civicsetu.models.schemas import ChatMessage, Citation, RetrievedChunk
 
 
 class CivicSetuState(TypedDict):
@@ -15,13 +15,14 @@ class CivicSetuState(TypedDict):
     session_id: str | None
     jurisdiction_filter: Jurisdiction | None
     top_k: int
+    messages: Annotated[list[ChatMessage], operator.add]
 
     # ── Classification ─────────────────────────────────────────────────────────
     query_type: QueryType | None
     rewritten_query: str | None           # expanded/clarified query
 
     # ── Retrieval ──────────────────────────────────────────────────────────────
-    retrieved_chunks: Annotated[list[RetrievedChunk], operator.add]
+    retrieved_chunks: list[RetrievedChunk]
     reranked_chunks: list[RetrievedChunk]
 
     # ── Generation ─────────────────────────────────────────────────────────────
@@ -35,3 +36,5 @@ class CivicSetuState(TypedDict):
     retry_count: int
     hallucination_flag: bool
     error: str | None
+    skip_classifier: NotRequired[bool]
+    source_section_id: NotRequired[str]

src/civicsetu/api/main.py

@@ -1,455 +1,39 @@
 from __future__ import annotations
 
+import asyncio
+import time
 from contextlib import asynccontextmanager
 
 import structlog
 from fastapi import FastAPI
-from fastapi.responses import HTMLResponse
 from fastapi.middleware.cors import CORSMiddleware
 
 from civicsetu.api.middleware.logging import LoggingMiddleware
-from civicsetu.api.routes import health, query
+from civicsetu.api.routes import health, query, graph
 from civicsetu.config.settings import get_settings
-from civicsetu.stores.graph_store import get_driver, close_driver
+from civicsetu.stores.graph_store import close_driver, get_driver
 
 log = structlog.get_logger(__name__)
 settings = get_settings()
 
-def get_landing_page_html() -> str:
-    return """
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <title>CivicSetu — AI-Powered RERA Research</title>
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <meta name="description" content="Open-source RAG system for querying Indian civic and legal documents with accurate citations and cross-reference traversal.">
-    <script>
-        // Tailwind dark mode: class-based
-        tailwind.config = {
-            darkMode: 'class'
-        }
-    </script>
-    <script src="https://cdn.tailwindcss.com"></script>
-    <link rel="preconnect" href="https://fonts.googleapis.com">
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Merriweather:wght@400;700&display=swap" rel="stylesheet">
-    <style>
-        body { font-family: 'Inter', sans-serif; }
-        .answer-body { font-family: 'Merriweather', serif; }
-        .gradient-text {
-            background: linear-gradient(135deg, #3b82f6 0%, #8b5cf6 50%, #d946ef 100%);
-            -webkit-background-clip: text;
-            -webkit-text-fill-color: transparent;
-            background-clip: text;
-        }
-        .glass {
-            background: rgba(255, 255, 255, 0.85);
-            backdrop-filter: blur(12px);
-            -webkit-backdrop-filter: blur(12px);
-        }
-        .dark .glass {
-            background: rgba(30, 41, 59, 0.85);
-        }
-        .pulse-ring {
-            animation: pulse-ring 1.5s cubic-bezier(0.4, 0, 0.6, 1) infinite;
-        }
-        @keyframes pulse-ring {
-            0%, 100% { opacity: 1; }
-            50% { opacity: 0.5; }
-        }
-        .slide-up {
-            animation: slideUp 0.4s ease-out forwards;
-        }
-        @keyframes slideUp {
-            from { opacity: 0; transform: translateY(20px); }
-            to { opacity: 1; transform: translateY(0); }
-        }
-        .citation-card {
-            transition: transform 0.2s ease, box-shadow 0.2s ease;
-        }
-        .citation-card:hover {
-            transform: translateY(-2px);
-            box-shadow: 0 8px 25px rgba(0, 0, 0, 0.15);
-        }
-        .example-chip {
-            transition: all 0.2s ease;
-        }
-        .example-chip:hover {
-            transform: scale(1.02);
-        }
-        /* Theme toggle button */
-        .theme-toggle {
-            position: relative;
-            width: 40px;
-            height: 40px;
-            border-radius: 12px;
-            display: flex;
-            align-items: center;
-            justify-center;
-            cursor: pointer;
-            transition: all 0.2s ease;
-            background: transparent;
-            border: none;
-        }
-        .theme-toggle:hover {
-            background: rgba(0, 0, 0, 0.05);
-        }
-        .dark .theme-toggle:hover {
-            background: rgba(255, 255, 255, 0.1);
-        }
-        .theme-toggle .sun { display: block; }
-        .theme-toggle .moon { display: none; }
-        .dark .theme-toggle .sun { display: none; }
-        .dark .theme-toggle .moon { display: block; }
-    </style>
-</head>
-<body class="min-h-screen bg-gradient-to-br from-slate-50 via-blue-50 to-indigo-100 dark:from-slate-900 dark:via-slate-800 dark:to-indigo-950 transition-colors duration-300">
-    <header class="glass sticky top-0 z-50 border-b border-white/20 dark:border-slate-700/20">
-        <div class="max-w-6xl mx-auto px-6 py-4 flex items-center justify-between">
-            <div class="flex items-center gap-3">
-                <div class="w-10 h-10 rounded-xl bg-gradient-to-br from-blue-600 to-purple-600 flex items-center justify-center shadow-lg">
-                    <svg class="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 21V5a2 2 0 00-2-2H7a2 2 0 00-2 2v16m14 0h2m-2 0h-5m-9 0H3m2 0h5M9 7h1m-1 4h1m4-4h1m-1 4h1m-5 10v-5a1 1 0 011-1h2a1 1 0 011 1v5m-4 0h4"/>
-                    </svg>
-                </div>
-                <div>
-                    <h1 class="text-xl font-bold gradient-text">CivicSetu</h1>
-                    <p class="text-xs text-gray-500 dark:text-gray-400">RERA Research Engine</p>
-                </div>
-            </div>
-            <div class="flex items-center gap-3">
-                <span class="hidden sm:inline-flex items-center gap-1.5 text-xs text-green-600 dark:text-green-400 bg-green-50 dark:bg-green-900/30 px-3 py-1 rounded-full">
-                    <span class="w-2 h-2 bg-green-500 dark:bg-green-400 rounded-full pulse-ring"></span>
-                    Live
-                </span>
-                <button id="theme-toggle" class="theme-toggle text-gray-600 dark:text-gray-300" aria-label="Toggle dark mode">
-                    <!-- Sun (shown in dark mode to switch to light) -->
-                    <svg class="sun w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z"/>
-                    </svg>
-                    <!-- Moon (shown in light mode to switch to dark) -->
-                    <svg class="moon w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z"/>
-                    </svg>
-                </button>
-                <a href="https://github.com/adeshboudh/civicsetu" target="_blank" class="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-white transition-colors">
-                    <svg class="w-6 h-6" fill="currentColor" viewBox="0 0 24 24">
-                        <path fill-rule="evenodd" d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z" clip-rule="evenodd"/>
-                    </svg>
-                </a>
-            </div>
-        </div>
-    </header>
 
-    <main class="max-w-6xl mx-auto px-6 py-12">
-        <div class="text-center mb-12">
-            <h2 class="text-4xl md:text-5xl font-bold text-gray-900 dark:text-white mb-4">
-                AI-Powered <span class="gradient-text">RERA Research</span>
-            </h2>
-            <p class="text-lg text-gray-600 dark:text-gray-300 max-w-2xl mx-auto leading-relaxed">
-                Query Indian real estate regulations across 5 jurisdictions. Get cited, structured answers
-                with cross-reference traversal and conflict detection — powered by LangGraph agents.
-            </p>
-        </div>
-
-        <div class="glass rounded-3xl shadow-2xl p-8 mb-8 border border-white/30 dark:border-slate-700/30">
-            <div class="flex flex-col lg:flex-row gap-4 mb-6">
-                <div class="flex-1 relative">
-                    <svg class="absolute left-4 top-1/2 -translate-y-1/2 w-5 h-5 text-gray-400 dark:text-gray-500" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"/>
-                    </svg>
-                    <input id="query" type="text"
-                           placeholder="Ask about RERA: promoter obligations, agent registration, penalties..."
-                           class="w-full pl-12 pr-4 py-4 text-lg border-2 border-gray-200 dark:border-gray-600 bg-white dark:bg-slate-800 text-gray-900 dark:text-white rounded-2xl focus:border-blue-400 dark:focus:border-blue-400 focus:outline-none focus:ring-4 focus:ring-blue-100 dark:focus:ring-blue-900 transition-all">
-                </div>
-                <div class="flex gap-3">
-                    <select id="jurisdiction" class="px-4 py-4 text-gray-700 dark:text-gray-200 bg-white dark:bg-slate-800 border-2 border-gray-200 dark:border-gray-600 rounded-2xl focus:border-blue-400 dark:focus:border-blue-400 focus:outline-none cursor-pointer">
-                        <option value="">All India</option>
-                        <option value="CENTRAL">RERA Act (Central)</option>
-                        <option value="MAHARASHTRA">Maharashtra</option>
-                        <option value="UTTAR_PRADESH">Uttar Pradesh</option>
-                        <option value="KARNATAKA">Karnataka</option>
-                        <option value="TAMIL_NADU">Tamil Nadu</option>
-                    </select>
-                    <button onclick="doQuery()"
-                            class="bg-gradient-to-r from-blue-600 to-purple-600 hover:from-blue-700 hover:to-purple-700 text-white px-8 py-4 rounded-2xl font-semibold text-lg shadow-lg hover:shadow-xl transition-all duration-200 flex items-center gap-2">
-                        <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"/>
-                        </svg>
-                        <span>Ask</span>
-                    </button>
-                </div>
-            </div>
-
-            <div class="flex flex-wrap gap-2">
-                <span class="text-sm text-gray-500 dark:text-gray-400 mr-2">Try:</span>
-                <button onclick="setQuery(this.textContent)" class="example-chip text-sm bg-blue-50 dark:bg-blue-900/30 hover:bg-blue-100 dark:hover:bg-blue-900/50 text-blue-700 dark:text-blue-300 px-4 py-2 rounded-full border border-blue-200 dark:border-blue-700">
-                    What are promoter obligations under RERA?
-                </button>
-                <button onclick="setQuery(this.textContent)" class="example-chip text-sm bg-purple-50 dark:bg-purple-900/30 hover:bg-purple-100 dark:hover:bg-purple-900/50 text-purple-700 dark:text-purple-300 px-4 py-2 rounded-full border border-purple-200 dark:border-purple-700">
-                    Penalties for delayed possession
-                </button>
-                <button onclick="setQuery(this.textContent)" class="example-chip text-sm bg-green-50 dark:bg-green-900/30 hover:bg-green-100 dark:hover:bg-green-900/50 text-green-700 dark:text-green-300 px-4 py-2 rounded-full border border-green-200 dark:border-green-700">
-                    Agent registration requirements
-                </button>
-                <button onclick="setQuery(this.textContent)" class="example-chip text-sm bg-amber-50 dark:bg-amber-900/30 hover:bg-amber-100 dark:hover:bg-amber-900/50 text-amber-700 dark:text-amber-300 px-4 py-2 rounded-full border border-amber-200 dark:border-amber-700">
-                    Complaint filing process
-                </button>
-            </div>
-        </div>
-
-        <div id="response" class="hidden space-y-6">
-            <div id="loading" class="glass rounded-2xl p-12 text-center">
-                <div class="inline-flex items-center gap-3">
-                    <div class="w-10 h-10 border-4 border-blue-200 dark:border-slate-600 border-t-blue-600 dark:border-t-blue-400 rounded-full animate-spin"></div>
-                    <span class="text-gray-600 dark:text-gray-300 text-lg">Analyzing RERA regulations...</span>
-                </div>
-                <p class="text-gray-400 dark:text-gray-500 text-sm mt-3">This may take 10-15 seconds</p>
-            </div>
-
-            <div id="answer-card" class="glass rounded-2xl shadow-xl p-8 slide-up hidden">
-                <div class="flex items-start gap-4 mb-6">
-                    <div class="w-12 h-12 rounded-xl bg-gradient-to-br from-blue-500 to-purple-500 flex items-center justify-center flex-shrink-0">
-                        <svg class="w-6 h-6 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z"/>
-                        </svg>
-                    </div>
-                    <div class="flex-1">
-                        <h3 class="text-lg font-semibold text-gray-800 dark:text-white mb-1">Answer</h3>
-                        <div id="query-type-badge" class="inline-block text-xs bg-gray-100 dark:bg-slate-700 text-gray-600 dark:text-gray-300 px-2 py-1 rounded-full"></div>
-                    </div>
-                </div>
-                <div id="answer" class="answer-body text-gray-800 dark:text-gray-200 text-lg leading-relaxed"></div>
-                <div id="warnings" class="mt-6 hidden"></div>
-            </div>
-
-            <div id="stats-row" class="grid grid-cols-2 md:grid-cols-4 gap-4 hidden">
-                <div class="glass rounded-xl p-4 text-center">
-                    <div id="confidence-value" class="text-2xl font-bold text-blue-600 dark:text-blue-400">--</div>
-                    <div class="text-xs text-gray-500 dark:text-gray-400">Confidence</div>
-                </div>
-                <div class="glass rounded-xl p-4 text-center">
-                    <div id="citations-count" class="text-2xl font-bold text-purple-600 dark:text-purple-400">--</div>
-                    <div class="text-xs text-gray-500 dark:text-gray-400">Citations</div>
-                </div>
-                <div class="glass rounded-xl p-4 text-center">
-                    <div id="chunks-count" class="text-2xl font-bold text-green-600 dark:text-green-400">--</div>
-                    <div class="text-xs text-gray-500 dark:text-gray-400">Chunks</div>
-                </div>
-                <div class="glass rounded-xl p-4 text-center">
-                    <div id="retry-count" class="text-2xl font-bold text-amber-600 dark:text-amber-400">--</div>
-                    <div class="text-xs text-gray-500 dark:text-gray-400">Retries</div>
-                </div>
-            </div>
-
-            <div id="citations-card" class="glass rounded-2xl shadow-xl p-8 hidden">
-                <h3 class="text-lg font-semibold text-gray-800 dark:text-white mb-4 flex items-center gap-2">
-                    <svg class="w-5 h-5 text-blue-500 dark:text-blue-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"/>
-                    </svg>
-                    Legal Citations
-                </h3>
-                <div id="citations" class="grid gap-3"></div>
-            </div>
-
-            <div class="bg-amber-50 dark:bg-amber-900/30 border border-amber-200 dark:border-amber-700 rounded-xl p-4 text-sm text-amber-800 dark:text-amber-200">
-                <div class="flex items-start gap-2">
-                    <svg class="w-5 h-5 flex-shrink-0 mt-0.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"/>
-                    </svg>
-                    <div>
-                        <strong>Legal Disclaimer:</strong> This is AI-generated legal information, not legal advice.
-                        Always verify with a qualified lawyer or the official gazette before making any legal decisions.
-                    </div>
-                </div>
-            </div>
-        </div>
-
-        <div class="mt-16 grid md:grid-cols-3 gap-6">
-            <div class="glass rounded-2xl p-6 border border-white/30 dark:border-slate-700/30 hover:shadow-lg transition-shadow">
-                <div class="w-12 h-12 rounded-xl bg-blue-100 dark:bg-blue-900/50 flex items-center justify-center mb-4">
-                    <svg class="w-6 h-6 text-blue-600 dark:text-blue-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"/>
-                    </svg>
-                </div>
-                <h3 class="font-semibold text-gray-800 dark:text-white mb-2">5-Jurisdiction Coverage</h3>
-                <p class="text-sm text-gray-600 dark:text-gray-400">Central RERA Act + Maharashtra, UP, Karnataka, and Tamil Nadu state rules</p>
-            </div>
-            <div class="glass rounded-2xl p-6 border border-white/30 dark:border-slate-700/30 hover:shadow-lg transition-shadow">
-                <div class="w-12 h-12 rounded-xl bg-purple-100 dark:bg-purple-900/50 flex items-center justify-center mb-4">
-                    <svg class="w-6 h-6 text-purple-600 dark:text-purple-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13.828 10.172a4 4 0 00-5.656 0l-4 4a4 4 0 105.656 5.656l1.102-1.101m-.758-4.899a4 4 0 005.656 0l4-4a4 4 0 00-5.656-5.656l-1.1 1.1"/>
-                    </svg>
-                </div>
-                <h3 class="font-semibold text-gray-800 dark:text-white mb-2">Cross-Reference Graph</h3>
-                <p class="text-sm text-gray-600 dark:text-gray-400">Neo4j-powered traversal between sections and DERIVED_FROM relationships</p>
-            </div>
-            <div class="glass rounded-2xl p-6 border border-white/30 dark:border-slate-700/30 hover:shadow-lg transition-shadow">
-                <div class="w-12 h-12 rounded-xl bg-green-100 dark:bg-green-900/50 flex items-center justify-center mb-4">
-                    <svg class="w-6 h-6 text-green-600 dark:text-green-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z"/>
-                    </svg>
-                </div>
-                <h3 class="font-semibold text-gray-800 dark:text-white mb-2">Hallucination Detection</h3>
-                <p class="text-sm text-gray-600 dark:text-gray-400">Validator agent with confidence scoring and citation verification</p>
-            </div>
-        </div>
-
-        <div class="mt-12 glass rounded-2xl p-8 border border-white/30 dark:border-slate-700/30">
-            <h3 class="text-lg font-semibold text-gray-800 dark:text-white mb-6">Document Coverage</h3>
-            <div class="grid sm:grid-cols-2 lg:grid-cols-3 gap-4">
-                <div class="flex items-center gap-3 p-4 bg-white/50 dark:bg-slate-800/50 rounded-xl">
-                    <div class="w-10 h-10 rounded-lg bg-blue-100 dark:bg-blue-900/50 flex items-center justify-center text-blue-600 dark:text-blue-400 font-bold text-sm">RERA</div>
-                    <div>
-                        <div class="font-medium text-gray-800 dark:text-white">RERA Act 2016</div>
-                        <div class="text-xs text-gray-500 dark:text-gray-400">Central • 224 sections</div>
-                    </div>
-                </div>
-                <div class="flex items-center gap-3 p-4 bg-white/50 dark:bg-slate-800/50 rounded-xl">
-                    <div class="w-10 h-10 rounded-lg bg-purple-100 dark:bg-purple-900/50 flex items-center justify-center text-purple-600 dark:text-purple-400 font-bold text-sm">MH</div>
-                    <div>
-                        <div class="font-medium text-gray-800 dark:text-white">Maharashtra Rules 2017</div>
-                        <div class="text-xs text-gray-500 dark:text-gray-400">Maharashtra • 214 sections</div>
-                    </div>
-                </div>
-                <div class="flex items-center gap-3 p-4 bg-white/50 dark:bg-slate-800/50 rounded-xl">
-                    <div class="w-10 h-10 rounded-lg bg-green-100 dark:bg-green-900/50 flex items-center justify-center text-green-600 dark:text-green-400 font-bold text-sm">UP</div>
-                    <div>
-                        <div class="font-medium text-gray-800 dark:text-white">UP RERA Rules 2016</div>
-                        <div class="text-xs text-gray-500 dark:text-gray-400">Uttar Pradesh</div>
-                    </div>
-                </div>
-                <div class="flex items-center gap-3 p-4 bg-white/50 dark:bg-slate-800/50 rounded-xl">
-                    <div class="w-10 h-10 rounded-lg bg-amber-100 dark:bg-amber-900/50 flex items-center justify-center text-amber-600 dark:text-amber-400 font-bold text-sm">KA</div>
-                    <div>
-                        <div class="font-medium text-gray-800 dark:text-white">Karnataka Rules 2017</div>
-                        <div class="text-xs text-gray-500 dark:text-gray-400">Karnataka</div>
-                    </div>
-                </div>
-                <div class="flex items-center gap-3 p-4 bg-white/50 dark:bg-slate-800/50 rounded-xl">
-                    <div class="w-10 h-10 rounded-lg bg-red-100 dark:bg-red-900/50 flex items-center justify-center text-red-600 dark:text-red-400 font-bold text-sm">TN</div>
-                    <div>
-                        <div class="font-medium text-gray-800 dark:text-white">Tamil Nadu Rules 2017</div>
-                        <div class="text-xs text-gray-500 dark:text-gray-400">Tamil Nadu</div>
-                    </div>
-                </div>
-            </div>
-        </div>
-    </main>
-
-    <footer class="mt-16 border-t border-gray-200 dark:border-slate-700 bg-white/50 dark:bg-slate-900/50">
-        <div class="max-w-6xl mx-auto px-6 py-8">
-            <div class="flex flex-col md:flex-row items-center justify-between gap-4">
-                <div class="text-sm text-gray-500 dark:text-gray-400">
-                    <span class="font-semibold text-gray-700 dark:text-gray-200">CivicSetu</span> — Open-source RAG for Indian civic documents
-                </div>
-                <div class="flex items-center gap-6 text-sm text-gray-500 dark:text-gray-400">
-                    <a href="https://github.com/adeshboudh/civicsetu" class="hover:text-gray-700 dark:hover:text-gray-200 transition-colors">GitHub</a>
-                    <a href="/docs" class="hover:text-gray-700 dark:hover:text-gray-200 transition-colors">API Docs</a>
-                </div>
-            </div>
-        </div>
-    </footer>
-
-    <script>
-        // Dark mode toggle
-        const toggleBtn = document.getElementById('theme-toggle');
-        const html = document.documentElement;
-
-        // Init: check localStorage or system preference
-        if (localStorage.getItem('theme') === 'dark' || (!localStorage.getItem('theme') && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
-            html.classList.add('dark');
-        }
-
-        toggleBtn.addEventListener('click', () => {
-            html.classList.toggle('dark');
-            localStorage.setItem('theme', html.classList.contains('dark') ? 'dark' : 'light');
-        });
-
-        function setQuery(text) {
-            document.getElementById('query').value = text;
-            document.getElementById('query').focus();
-        }
-
-        async function doQuery() {
-            const queryText = document.getElementById('query').value.trim();
-            if (!queryText) return;
-
-            const jurisdiction = document.getElementById('jurisdiction').value;
-            const responseDiv = document.getElementById('response');
-
-            responseDiv.classList.remove('hidden');
-            document.getElementById('loading').classList.remove('hidden');
-            document.getElementById('answer-card').classList.add('hidden');
-            document.getElementById('stats-row').classList.add('hidden');
-            document.getElementById('citations-card').classList.add('hidden');
-            document.getElementById('warnings').classList.add('hidden');
-
-            const payload = { query: queryText, top_k: 5 };
-            if (jurisdiction) payload.jurisdiction_filter = jurisdiction;
-
-            try {
-                const res = await fetch('/api/v1/query', {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify(payload)
-                });
-                const data = await res.json();
-
-                document.getElementById('loading').classList.add('hidden');
-                document.getElementById('answer-card').classList.remove('hidden');
-                document.getElementById('answer').innerHTML = (data.answer || '').replace(/\\n/g, '<br>');
-                document.getElementById('query-type-badge').textContent = data.query_type_resolved || 'general';
-
-                const warningsDiv = document.getElementById('warnings');
-                let warningsHtml = '';
-                if (data.conflict_warnings && data.conflict_warnings.length) {
-                    warningsHtml += '<div class="mb-3"><strong class="text-amber-700">Conflict Detected:</strong> ' + data.conflict_warnings.join(', ') + '</div>';
-                }
-                if (data.amendment_notice) {
-                    warningsHtml += '<div class="mb-3"><strong class="text-blue-700">Amendment Notice:</strong> ' + data.amendment_notice + '</div>';
-                }
-                if (warningsHtml) {
-                    warningsDiv.innerHTML = '<div class="bg-amber-50 dark:bg-amber-900/30 border border-amber-200 dark:border-amber-700 rounded-xl p-4 text-sm">' + warningsHtml + '</div>';
-                    warningsDiv.classList.remove('hidden');
-                }
-
-                document.getElementById('stats-row').classList.remove('hidden');
-                document.getElementById('confidence-value').textContent = ((data.confidence_score || 0) * 100).toFixed(0) + '%';
-                document.getElementById('citations-count').textContent = data.citations ? data.citations.length : 0;
-
-                const citationsCard = document.getElementById('citations-card');
-                const citationsDiv = document.getElementById('citations');
-                if (data.citations && data.citations.length) {
-                    citationsCard.classList.remove('hidden');
-                    citationsDiv.innerHTML = data.citations.map(c => `
-                        <div class="citation-card bg-white dark:bg-slate-800 rounded-xl p-4 border-l-4 border-blue-500 dark:border-blue-400 shadow-sm">
-                            <div class="flex justify-between items-start">
-                                <div>
-                                    <div class="font-mono text-sm text-blue-600 dark:text-blue-400 font-semibold">${c.section_id}</div>
-                                    <div class="font-medium text-gray-800 dark:text-gray-200">${c.doc_name}</div>
-                                </div>
-                                <span class="text-xs bg-gray-100 dark:bg-slate-700 text-gray-600 dark:text-gray-300 px-2 py-1 rounded-full">${c.jurisdiction}</span>
-                            </div>
-                            <div class="text-xs text-gray-500 dark:text-gray-400 mt-2">Effective: ${c.effective_date || 'N/A'}</div>
-                        </div>
-                    `).join('');
-                }
-
-            } catch (error) {
-                document.getElementById('loading').classList.add('hidden');
-                document.getElementById('answer-card').classList.remove('hidden');
-                document.getElementById('answer').innerHTML = '<div class="text-red-600 dark:text-red-400 p-4 bg-red-50 dark:bg-red-900/30 rounded-xl"><strong>Error:</strong> ' + error.message + '</div>';
-            }
-        }
-
-        document.getElementById('query').addEventListener('keypress', function(e) {
-            if (e.key === 'Enter') doQuery();
-        });
-    </script>
-</body>
-</html>
-"""
+def create_checkpointer():
+    from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
+    from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
+
+    serde = JsonPlusSerializer(
+        allowed_msgpack_modules=[
+            ("civicsetu.models.schemas", "ChatMessage"),
+            ("civicsetu.models.schemas", "Citation"),
+            ("civicsetu.models.schemas", "LegalChunk"),
+            ("civicsetu.models.schemas", "RetrievedChunk"),
+            ("civicsetu.models.enums", "ChunkStatus"),
+            ("civicsetu.models.enums", "DocType"),
+            ("civicsetu.models.enums", "Jurisdiction"),
+            ("civicsetu.models.enums", "QueryType"),
+        ]
+    )
+    return AsyncPostgresSaver.from_conn_string(settings.postgres_conninfo, serde=serde)
 
 
 @asynccontextmanager
@@ -457,14 +41,33 @@ async def lifespan(app: FastAPI):
     """Startup and shutdown events."""
     log.info("civicsetu_starting", env=settings.api_env)
 
-    # Pre-compile the graph once at startup — not on first request
     from civicsetu.agent.graph import get_compiled_graph
-    app.state.graph = get_compiled_graph()
-    log.info("langgraph_compiled")
-    await get_driver()
-    yield
-    await close_driver()
-    log.info("civicsetu_shutdown")
+
+    async with create_checkpointer() as checkpointer:
+        await checkpointer.setup()
+        app.state.checkpointer = checkpointer
+        app.state.graph = get_compiled_graph(checkpointer=checkpointer)
+        log.info("langgraph_compiled", checkpointing=True)
+        await get_driver()
+        from civicsetu.retrieval import warm_embedding_model
+
+        warm_start = time.perf_counter()
+        await asyncio.to_thread(warm_embedding_model)
+        log.info(
+            "embedding_model_warmed",
+            duration_ms=round((time.perf_counter() - warm_start) * 1000, 2),
+        )
+        from civicsetu.agent.nodes import _get_ranker
+
+        ranker_start = time.perf_counter()
+        await asyncio.to_thread(_get_ranker)
+        log.info(
+            "reranker_warmed",
+            duration_ms=round((time.perf_counter() - ranker_start) * 1000, 2),
+        )
+        yield
+        await close_driver()
+        log.info("civicsetu_shutdown")
 
 
 def create_app() -> FastAPI:
@@ -477,13 +80,10 @@ def create_app() -> FastAPI:
         redoc_url="/redoc",
     )
 
-    @app.get("/", include_in_schema=False)
-    async def landing_page():
-        return HTMLResponse(get_landing_page_html())
-
     app.add_middleware(
         CORSMiddleware,
-        allow_origins=["*"] if not settings.is_production else [],
+        allow_origins=settings.allowed_origins,
+        allow_credentials=True,
         allow_methods=["GET", "POST"],
         allow_headers=["*"],
     )
@@ -491,8 +91,8 @@ def create_app() -> FastAPI:
 
     app.include_router(health.router, tags=["health"])
     app.include_router(query.router, prefix="/api/v1", tags=["query"])
+    app.include_router(graph.router, prefix="/api/v1", tags=["graph"])
 
     return app
 
-
 app = create_app()

src/civicsetu/api/routes/graph.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+
+import structlog
+from fastapi import APIRouter, HTTPException, Path, Query, Request
+from sqlalchemy import text
+
+from civicsetu.guardrails.input_guard import InputGuard
+from civicsetu.guardrails.output_guard import OutputGuard
+from civicsetu.models.enums import Jurisdiction, QueryType
+from civicsetu.models.schemas import (
+    ChatMessage,
+    CivicSetuResponse,
+    ConnectedSectionOut,
+    GraphEdge,
+    GraphNode,
+    GraphTopologyResponse,
+    InsufficientInfoResponse,
+    SectionChunkOut,
+    SectionContentResponse,
+    SectionContextQueryRequest,
+)
+from civicsetu.stores.graph_store import GraphStore
+from civicsetu.stores.relational_store import AsyncSessionLocal
+
+log = structlog.get_logger(__name__)
+router = APIRouter()
+
+_topo_cache: dict = {"data": None, "ts": 0.0}
+_TOPO_TTL = 300
+
+
+@router.get("/graph/topology", response_model=GraphTopologyResponse)
+async def get_graph_topology() -> GraphTopologyResponse:
+    """All connected Section nodes and REFERENCES/DERIVED_FROM edges."""
+    now = time.monotonic()
+    if _topo_cache["data"] is not None and (now - _topo_cache["ts"]) < _TOPO_TTL:
+        log.info("topology_cache_hit")
+        return _topo_cache["data"]
+
+    try:
+        nodes_raw, edges_raw = await GraphStore.get_topology()
+        stats = await GraphStore.graph_stats()
+    except Exception as e:
+        log.error("topology_fetch_failed", error=str(e))
+        raise HTTPException(status_code=500, detail=f"Graph topology fetch failed: {e}")
+
+    response = GraphTopologyResponse(
+        nodes=[GraphNode(**n) for n in nodes_raw],
+        edges=[GraphEdge(**e) for e in edges_raw],
+        stats=stats,
+    )
+    _topo_cache["data"] = response
+    _topo_cache["ts"] = now
+    log.info("topology_cache_updated", nodes=len(response.nodes), edges=len(response.edges))
+    return response
+
+
+@router.get("/graph/section/{section_id:path}", response_model=SectionContentResponse)
+async def get_section_content(
+    section_id: str = Path(..., description="Section ID, e.g. 'Section 18'"),
+    jurisdiction: str = Query(..., description="Jurisdiction enum value, e.g. 'CENTRAL'"),
+    chunk_id: str | None = Query(default=None, description="Optional chunk id from the graph node"),
+) -> SectionContentResponse:
+    """Stitched section text from Postgres plus connected sections from Neo4j."""
+    async with AsyncSessionLocal() as db:
+        resolved_section_id = section_id
+        resolved_jurisdiction = jurisdiction
+
+        if chunk_id:
+            node_result = await db.execute(
+                text(
+                    """
+                    SELECT
+                        section_id,
+                        jurisdiction
+                    FROM legal_chunks
+                    WHERE chunk_id::text = :chunk_id
+                      AND lower(status) = 'active'
+                    LIMIT 1
+                    """
+                ),
+                {"chunk_id": chunk_id},
+            )
+            node_row = node_result.mappings().first()
+            if node_row:
+                resolved_section_id = node_row["section_id"]
+                resolved_jurisdiction = node_row["jurisdiction"]
+
+        result = await db.execute(
+            text(
+                """
+                SELECT
+                    chunk_id::text AS chunk_id,
+                    section_id,
+                    section_title,
+                    text,
+                    page_number,
+                    doc_name,
+                    jurisdiction,
+                    effective_date,
+                    source_url
+                FROM legal_chunks
+                WHERE section_id = :section_id
+                  AND jurisdiction = :jurisdiction
+                  AND lower(status) = 'active'
+                ORDER BY page_number ASC
+                """
+            ),
+            {"section_id": resolved_section_id, "jurisdiction": resolved_jurisdiction},
+        )
+        rows = result.mappings().all()
+
+    if not rows:
+        raise HTTPException(
+            status_code=404,
+            detail=(
+                f"No chunks found for section_id='{section_id}' jurisdiction='{jurisdiction}'"
+                + (f" chunk_id='{chunk_id}'" if chunk_id else "")
+            ),
+        )
+
+    first = rows[0]
+    chunks = [
+        SectionChunkOut(chunk_id=row["chunk_id"], text=row["text"], page_number=row["page_number"])
+        for row in rows
+    ]
+
+    refs_out, refs_in, derived_out, derived_in = await asyncio.gather(
+        GraphStore.get_referenced_sections(resolved_section_id, resolved_jurisdiction),
+        GraphStore.get_sections_referencing(resolved_section_id, resolved_jurisdiction),
+        GraphStore.get_derived_act_sections(resolved_section_id, resolved_jurisdiction),
+        GraphStore.get_deriving_rule_sections(resolved_section_id, resolved_jurisdiction),
+        return_exceptions=True,
+    )
+
+    def _safe_connections(result: object, edge_type: str) -> list[ConnectedSectionOut]:
+        if isinstance(result, Exception):
+            log.warning("connected_sections_partial_failure", edge_type=edge_type, error=str(result))
+            return []
+        return [
+            ConnectedSectionOut(
+                section_id=row["section_id"],
+                title=row.get("title", ""),
+                jurisdiction=row.get("jurisdiction", resolved_jurisdiction),
+                edge_type=edge_type,
+            )
+            for row in result  # type: ignore[union-attr]
+        ]
+
+    connected = (
+        _safe_connections(refs_out, "REFERENCES_OUT")
+        + _safe_connections(refs_in, "REFERENCES_IN")
+        + _safe_connections(derived_out, "DERIVED_FROM_OUT")
+        + _safe_connections(derived_in, "DERIVED_FROM_IN")
+    )
+
+    log.info(
+        "section_content_fetched",
+        section_id=resolved_section_id,
+        jurisdiction=resolved_jurisdiction,
+        chunks=len(chunks),
+        connected=len(connected),
+    )
+
+    return SectionContentResponse(
+        section_id=first.get("section_id", resolved_section_id),
+        title=first["section_title"],
+        doc_name=first["doc_name"],
+        jurisdiction=resolved_jurisdiction,
+        effective_date=str(first["effective_date"]) if first["effective_date"] else None,
+        source_url=first["source_url"],
+        chunks=chunks,
+        connected_sections=connected,
+    )
+
+
+@router.post("/query/section-context", response_model=CivicSetuResponse | InsufficientInfoResponse)
+async def section_context_query(
+    request: Request,
+    body: SectionContextQueryRequest,
+) -> CivicSetuResponse | InsufficientInfoResponse:
+    """Bypass the classifier and route directly into graph retrieval for a chosen section."""
+    guard_result = InputGuard.check(body.query)
+    if not guard_result.is_safe:
+        log.info("section_context_rejected", reason=guard_result.reason)
+        raise HTTPException(status_code=400, detail=guard_result.reason)
+
+    try:
+        jurisdiction = Jurisdiction(body.jurisdiction)
+    except ValueError:
+        raise HTTPException(status_code=422, detail=f"Invalid jurisdiction: '{body.jurisdiction}'")
+
+    safe_query = guard_result.sanitized_query
+    session_id = body.session_id or str(uuid.uuid4())
+    graph = request.app.state.graph
+    config = {"configurable": {"thread_id": session_id}}
+
+    initial_state = {
+        "query": safe_query,
+        "session_id": session_id,
+        "jurisdiction_filter": jurisdiction,
+        "top_k": 5,
+        "messages": [ChatMessage(role="user", content=safe_query)],
+        "source_section_id": body.section_id,
+        "query_type": QueryType.CROSS_REFERENCE,
+        "rewritten_query": safe_query,
+        "skip_classifier": True,
+        "retrieved_chunks": [],
+        "reranked_chunks": [],
+        "raw_response": None,
+        "citations": [],
+        "confidence_score": 0.0,
+        "conflict_warnings": [],
+        "amendment_notice": None,
+        "retry_count": 0,
+        "hallucination_flag": False,
+        "error": None,
+    }
+
+    try:
+        invoke_start = time.perf_counter()
+        result = await asyncio.to_thread(graph.invoke, initial_state, config)
+        log.info(
+            "graph_invoke_complete",
+            route="section_context",
+            duration_ms=round((time.perf_counter() - invoke_start) * 1000, 2),
+        )
+    except Exception as e:
+        log.error("section_context_invoke_failed", error=str(e))
+        raise HTTPException(status_code=500, detail=str(e))
+
+    raw_response = result.get("raw_response")
+    if raw_response:
+        try:
+            update_start = time.perf_counter()
+            await asyncio.to_thread(
+                graph.update_state,
+                config,
+                {"messages": [ChatMessage(role="assistant", content=raw_response)]},
+            )
+            log.info(
+                "graph_update_state_complete",
+                route="section_context",
+                duration_ms=round((time.perf_counter() - update_start) * 1000, 2),
+            )
+        except Exception as e:
+            log.warning("section_context_update_state_failed", error=str(e))
+
+    output_start = time.perf_counter()
+    result["session_id"] = session_id
+    response = OutputGuard.process(result, original_query=body.query)
+    log.info(
+        "output_guard_complete",
+        route="section_context",
+        duration_ms=round((time.perf_counter() - output_start) * 1000, 2),
+    )
+    return response

src/civicsetu/api/routes/query.py

@@ -1,18 +1,15 @@
 from __future__ import annotations
 
 import asyncio
+import time
+import uuid
 
 import structlog
 from fastapi import APIRouter, HTTPException, Request
 
 from civicsetu.guardrails.input_guard import InputGuard
 from civicsetu.guardrails.output_guard import OutputGuard
-from civicsetu.models.enums import QueryType
-from civicsetu.models.schemas import (
-    CivicSetuResponse,
-    InsufficientInfoResponse,
-    QueryRequest,
-)
+from civicsetu.models.schemas import CivicSetuResponse, ChatMessage, InsufficientInfoResponse, QueryRequest
 
 log = structlog.get_logger(__name__)
 router = APIRouter()
@@ -20,23 +17,22 @@ router = APIRouter()
 
 @router.post("/query", response_model=CivicSetuResponse | InsufficientInfoResponse)
 async def query_endpoint(request: Request, body: QueryRequest):
-    # ── 1. Input guard ────────────────────────────────────────────────────────
     guard_result = InputGuard.check(body.query)
     if not guard_result.is_safe:
         log.info("query_rejected_by_input_guard", reason=guard_result.reason)
         raise HTTPException(status_code=400, detail=guard_result.reason)
 
-    # Use sanitized query downstream (strips whitespace, no PII)
     safe_query = guard_result.sanitized_query
-
-    # ── 2. Build initial state ────────────────────────────────────────────────
+    session_id = body.session_id or str(uuid.uuid4())
     graph = request.app.state.graph
+    config = {"configurable": {"thread_id": session_id}}
 
     initial_state = {
         "query": safe_query,
-        "session_id": body.session_id,
+        "session_id": session_id,
         "jurisdiction_filter": body.jurisdiction_filter,
         "top_k": body.top_k,
+        "messages": [ChatMessage(role="user", content=safe_query)],
         "query_type": None,
         "rewritten_query": None,
         "retrieved_chunks": [],
@@ -51,12 +47,41 @@ async def query_endpoint(request: Request, body: QueryRequest):
         "error": None,
     }
 
-    # ── 3. Invoke graph ───────────────────────────────────────────────────────
     try:
-        result = await asyncio.to_thread(graph.invoke, initial_state)
+        invoke_start = time.perf_counter()
+        result = await asyncio.to_thread(graph.invoke, initial_state, config)
+        log.info(
+            "graph_invoke_complete",
+            route="query",
+            duration_ms=round((time.perf_counter() - invoke_start) * 1000, 2),
+        )
     except Exception as e:
         log.error("graph_invoke_failed", error=str(e))
         raise HTTPException(status_code=500, detail=str(e))
 
-    # ── 4. Output guard ───────────────────────────────────────────────────────
-    return OutputGuard.process(result, original_query=body.query)
+    raw_response = result.get("raw_response")
+    if raw_response:
+        try:
+            update_start = time.perf_counter()
+            await asyncio.to_thread(
+                graph.update_state,
+                config,
+                {"messages": [ChatMessage(role="assistant", content=raw_response)]},
+            )
+            log.info(
+                "graph_update_state_complete",
+                route="query",
+                duration_ms=round((time.perf_counter() - update_start) * 1000, 2),
+            )
+        except Exception as e:
+            log.warning("graph_update_state_failed", error=str(e))
+
+    output_start = time.perf_counter()
+    result["session_id"] = session_id
+    response = OutputGuard.process(result, original_query=body.query)
+    log.info(
+        "output_guard_complete",
+        route="query",
+        duration_ms=round((time.perf_counter() - output_start) * 1000, 2),
+    )
+    return response

src/civicsetu/config/settings.py

@@ -1,7 +1,8 @@
+from typing import Annotated
 from functools import lru_cache
 
-from pydantic import Field
-from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict
 
 
 class Settings(BaseSettings):
@@ -28,6 +29,10 @@ class Settings(BaseSettings):
         default="openrouter/meta-llama/llama-3.3-70b-instruct:free",
         alias="FALLBACK_MODEL_2",
     )
+    fallback_model_3: str = Field(
+        default="openrouter/qwen/qwen3.6-plus:free",
+        alias="FALLBACK_MODEL_3",
+    )
     local_model: str = Field(default="ollama/mistral", alias="LOCAL_MODEL")
 
     # Embeddings
@@ -54,6 +59,10 @@ class Settings(BaseSettings):
     api_host: str = Field(default="0.0.0.0", alias="API_HOST")
     api_port: int = Field(default=8000, alias="API_PORT")
     api_env: str = Field(default="development", alias="API_ENV")
+    allowed_origins: Annotated[list[str], NoDecode] = Field(
+        default=["http://localhost:3000"],
+        alias="ALLOWED_ORIGINS",
+    )
 
     # Observability
     phoenix_host: str = Field(default="localhost", alias="PHOENIX_HOST")
@@ -66,6 +75,15 @@ class Settings(BaseSettings):
     )
     log_level: str = Field(default="INFO", alias="LOG_LEVEL")
 
+    @field_validator("allowed_origins", mode="before")
+    @classmethod
+    def parse_allowed_origins(cls, value: str | list[str]) -> list[str]:
+        if isinstance(value, list):
+            return value
+        if isinstance(value, str):
+            return [origin.strip() for origin in value.split(",") if origin.strip()]
+        return value
+
     @property
     def postgres_dsn(self) -> str:
         return (
@@ -73,6 +91,13 @@ class Settings(BaseSettings):
             f"@{self.postgres_host}:{self.postgres_port}/{self.postgres_db}"
         )
 
+    @property
+    def postgres_conninfo(self) -> str:
+        return (
+            f"postgresql://{self.postgres_user}:{self.postgres_password}"
+            f"@{self.postgres_host}:{self.postgres_port}/{self.postgres_db}"
+        )
+
     @property
     def is_production(self) -> bool:
         return self.api_env == "production"

src/civicsetu/guardrails/output_guard.py

@@ -44,7 +44,10 @@ class OutputGuard:
         # 1 — No citations → always InsufficientInfoResponse
         if not citations:
             log.info("output_guard_no_citations", query_preview=original_query[:80])
-            return InsufficientInfoResponse(searched_query=original_query)
+            return InsufficientInfoResponse(
+                searched_query=original_query,
+                session_id=result.get("session_id"),
+            )
 
         # 2 — Confidence below floor → downgrade
         if confidence < _CONFIDENCE_FLOOR:
@@ -54,7 +57,10 @@ class OutputGuard:
                 floor=_CONFIDENCE_FLOOR,
                 query_preview=original_query[:80],
             )
-            return InsufficientInfoResponse(searched_query=original_query)
+            return InsufficientInfoResponse(
+                searched_query=original_query,
+                session_id=result.get("session_id"),
+            )
 
         # 3 — Build response (disclaimer is a default field on CivicSetuResponse,
         #     but we enforce it here explicitly so no future refactor silently drops it)
@@ -66,6 +72,7 @@ class OutputGuard:
             query_type_resolved=result.get("query_type") or QueryType.FACT_LOOKUP,
             conflict_warnings=result.get("conflict_warnings", []),
             amendment_notice=result.get("amendment_notice"),
+            session_id=result.get("session_id"),
         )
 
         # Sanity check — disclaimer must survive serialization unchanged

src/civicsetu/models/schemas.py

@@ -1,137 +1,200 @@
 from __future__ import annotations
 
 from datetime import date, datetime
-from typing import Optional
+from typing import Literal, Optional
 from uuid import UUID, uuid4
 
 from pydantic import BaseModel, Field, computed_field
 
 from civicsetu.models.enums import (
-    ChunkStatus,
-    ConfidenceLevel,
-    DocType,
-    Jurisdiction,
-    QueryType,
+		ChunkStatus,
+		ConfidenceLevel,
+		DocType,
+		Jurisdiction,
+		QueryType,
 )
 
 # ── Ingestion Schemas ──────────────────────────────────────────────────────────
 
 class LegalChunk(BaseModel):
-    """Canonical unit produced by the ingestion pipeline.
-    Every downstream store (pgvector, Neo4j, Postgres) is populated from this."""
-
-    chunk_id: UUID = Field(default_factory=uuid4)
-    doc_id: UUID
-    jurisdiction: Jurisdiction
-    doc_type: DocType
-    doc_name: str
-    section_id: str                          # e.g. "Section 18", "Rule 12"
-    section_title: str
-    section_hierarchy: list[str]             # e.g. ["Part IV", "Chapter 2", "Section 18"]
-    text: str
-    effective_date: date | None = None
-    superseded_by: UUID | None = None
-    status: ChunkStatus = ChunkStatus.ACTIVE
-    source_url: str
-    page_number: int
-    embedding: list[float] | None = None  # populated after embedding step
-
-    @computed_field
-    @property
-    def citation_label(self) -> str:
-        """Human-readable citation string."""
-        return f"{self.doc_name} — {self.section_id}"
+		"""Canonical unit produced by the ingestion pipeline.
+		Every downstream store (pgvector, Neo4j, Postgres) is populated from this."""
+
+		chunk_id: UUID = Field(default_factory=uuid4)
+		doc_id: UUID
+		jurisdiction: Jurisdiction
+		doc_type: DocType
+		doc_name: str
+		section_id: str                          # e.g. "Section 18", "Rule 12"
+		section_title: str
+		section_hierarchy: list[str]             # e.g. ["Part IV", "Chapter 2", "Section 18"]
+		text: str
+		effective_date: date | None = None
+		superseded_by: UUID | None = None
+		status: ChunkStatus = ChunkStatus.ACTIVE
+		source_url: str
+		page_number: int
+		embedding: list[float] | None = None  # populated after embedding step
+
+		@computed_field
+		@property
+		def citation_label(self) -> str:
+				"""Human-readable citation string."""
+				return f"{self.doc_name} — {self.section_id}"
 
 
 class IngestedDocument(BaseModel):
-    """Metadata record for a fully ingested document."""
+		"""Metadata record for a fully ingested document."""
 
-    doc_id: UUID = Field(default_factory=uuid4)
-    doc_name: str
-    jurisdiction: Jurisdiction
-    doc_type: DocType
-    source_url: str
-    effective_date: date | None = None
-    gazette_number: str | None = None
-    total_chunks: int = 0
-    ingested_at: datetime = Field(default_factory=datetime.utcnow)
-    is_active: bool = True
+		doc_id: UUID = Field(default_factory=uuid4)
+		doc_name: str
+		jurisdiction: Jurisdiction
+		doc_type: DocType
+		source_url: str
+		effective_date: date | None = None
+		gazette_number: str | None = None
+		total_chunks: int = 0
+		ingested_at: datetime = Field(default_factory=datetime.utcnow)
+		is_active: bool = True
 
 
 # ── Retrieval Schemas ──────────────────────────────────────────────────────────
 
 class RetrievedChunk(BaseModel):
-    """A LegalChunk enriched with retrieval scores."""
+		"""A LegalChunk enriched with retrieval scores."""
 
-    chunk: LegalChunk
-    vector_score: float | None = None     # cosine similarity from pgvector
-    rerank_score: float | None = None     # cross-encoder score from FlashRank
-    retrieval_source: str = "vector"         # "vector" | "graph" | "metadata"
-    graph_path: Optional[str] = None
-    is_pinned: bool = False
+		chunk: LegalChunk
+		vector_score: float | None = None     # cosine similarity from pgvector
+		rerank_score: float | None = None     # cross-encoder score from FlashRank
+		retrieval_source: str = "vector"         # "vector" | "graph" | "metadata"
+		graph_path: Optional[str] = None
+		is_pinned: bool = False
 
 
 # ── Response Schemas ───────────────────────────────────────────────────────────
 
 class Citation(BaseModel):
-    """Traceable citation attached to every answer — non-negotiable."""
+		"""Traceable citation attached to every answer — non-negotiable."""
 
-    section_id: str
-    doc_name: str
-    jurisdiction: Jurisdiction
-    effective_date: date | None
-    source_url: str
-    chunk_id: UUID
+		section_id: str
+		doc_name: str
+		jurisdiction: Jurisdiction
+		effective_date: date | None
+		source_url: str
+		chunk_id: UUID
+
+
+class ChatMessage(BaseModel):
+		"""A single conversational message."""
+
+		role: Literal["user", "assistant"]
+		content: str
 
 
 class CivicSetuResponse(BaseModel):
-    """The immutable public response contract. Shape never changes between phases."""
-
-    answer: str
-    citations: list[Citation] = Field(min_length=1)
-    confidence_score: float = Field(ge=0.0, le=1.0)
-    query_type_resolved: QueryType
-    conflict_warnings: list[str] = Field(default_factory=list)
-    amendment_notice: str | None = None
-    disclaimer: str = (
-        "This is AI-generated information, not legal advice. "
-        "Consult a qualified lawyer for your specific situation."
-    )
-
-    @computed_field
-    @property
-    def confidence_level(self) -> ConfidenceLevel:
-        if self.confidence_score >= 0.75:
-            return ConfidenceLevel.HIGH
-        elif self.confidence_score >= 0.50:
-            return ConfidenceLevel.MEDIUM
-        return ConfidenceLevel.LOW
+		"""The immutable public response contract. Shape never changes between phases."""
+
+		answer: str
+		citations: list[Citation] = Field(min_length=1)
+		confidence_score: float = Field(ge=0.0, le=1.0)
+		query_type_resolved: QueryType
+		conflict_warnings: list[str] = Field(default_factory=list)
+		amendment_notice: str | None = None
+		session_id: str | None = None
+		disclaimer: str = (
+				"This is AI-generated information, not legal advice. "
+				"Consult a qualified lawyer for your specific situation."
+		)
+
+		@computed_field
+		@property
+		def confidence_level(self) -> ConfidenceLevel:
+				if self.confidence_score >= 0.75:
+						return ConfidenceLevel.HIGH
+				elif self.confidence_score >= 0.50:
+						return ConfidenceLevel.MEDIUM
+				return ConfidenceLevel.LOW
 
 
 class InsufficientInfoResponse(BaseModel):
-    """Returned when no citation can be found. Prevents hallucinated answers."""
+		"""Returned when no citation can be found. Prevents hallucinated answers."""
 
-    answer: str = "Insufficient information found in indexed documents."
-    searched_query: str
-    disclaimer: str = (
-        "This is AI-generated information, not legal advice. "
-        "Consult a qualified lawyer for your specific situation."
-    )
+		answer: str = "Insufficient information found in indexed documents."
+		searched_query: str
+		session_id: str | None = None
+		disclaimer: str = (
+				"This is AI-generated information, not legal advice. "
+				"Consult a qualified lawyer for your specific situation."
+		)
 
 
 # ── API Request Schemas ────────────────────────────────────────────────────────
 
 class QueryRequest(BaseModel):
-    query: str = Field(min_length=5, max_length=1000)
-    session_id: str | None = None
-    jurisdiction_filter: Jurisdiction | None = None
-    top_k: int = Field(default=5, ge=1, le=20)
+		query: str = Field(min_length=5, max_length=1000)
+		session_id: str | None = None
+		jurisdiction_filter: Jurisdiction | None = None
+		top_k: int = Field(default=5, ge=1, le=20)
 
 
 class IngestRequest(BaseModel):
-    source_url: str
-    doc_name: str
-    jurisdiction: Jurisdiction
-    doc_type: DocType
-    effective_date: date | None = None
-    gazette_number: str | None = None
+		source_url: str
+		doc_name: str
+		jurisdiction: Jurisdiction
+		doc_type: DocType
+		effective_date: date | None = None
+		gazette_number: str | None = None
+
+# ── Graph API Schemas ──────────────────────────────────────────────────────────
+
+class GraphNode(BaseModel):
+		chunk_id: str
+		section_id: str
+		title: str
+		jurisdiction: str
+		doc_name: str
+		is_active: bool
+		connection_count: int
+
+
+class GraphEdge(BaseModel):
+		source: str   # chunk_id
+		target: str   # chunk_id
+		edge_type: str  # "REFERENCES" | "DERIVED_FROM"
+
+
+class GraphTopologyResponse(BaseModel):
+		nodes: list[GraphNode]
+		edges: list[GraphEdge]
+		stats: dict
+
+
+class SectionChunkOut(BaseModel):
+		chunk_id: str
+		text: str
+		page_number: int
+
+
+class ConnectedSectionOut(BaseModel):
+		section_id: str
+		title: str
+		jurisdiction: str
+		edge_type: str  # REFERENCES_OUT | REFERENCES_IN | DERIVED_FROM_OUT | DERIVED_FROM_IN
+
+
+class SectionContentResponse(BaseModel):
+		section_id: str
+		title: str
+		doc_name: str
+		jurisdiction: str
+		effective_date: str | None
+		source_url: str
+		chunks: list[SectionChunkOut]
+		connected_sections: list[ConnectedSectionOut]
+
+
+class SectionContextQueryRequest(BaseModel):
+		query: str = Field(min_length=5, max_length=1000)
+		section_id: str
+		jurisdiction: str
+		session_id: str | None = None

src/civicsetu/prompts/generator.py

@@ -1,4 +1,4 @@
-GENERATOR_PROMPT = """Answer the following legal question using ONLY the provided context.
+GENERATOR_PROMPT = """{conversation_history_block}Answer the following legal question using ONLY the provided context.
 
 Question: {query}
 
@@ -7,7 +7,7 @@ Context:
 
 Respond with JSON:
 {{
-  "answer": "",
+  "answer": "<markdown-formatted answer>",
   "confidence_score": <0.0 to 1.0 based on how well context supports the answer>,
   "cited_chunks": [<1-based indices of ONLY the context items you actually used in your answer>],
   "amendment_notice": null,
@@ -16,6 +16,9 @@ Respond with JSON:
 
 Rules:
 - Only use information present in the context above
+- Format the answer field as GitHub-flavored Markdown
+- Prefer concise markdown paragraphs and bullet lists; use tables only when comparing provisions or jurisdictions
+- Do not wrap the answer in markdown code fences
 - Reference specific section numbers in your answer (e.g. "Section 18", "Rule 3")
 - In cited_chunks, list ONLY the [N] indices you directly drew from — not every item in context
 - If you used [1] and [3] but not [2], [4], [5] → cited_chunks: [1, 3]
@@ -23,4 +26,4 @@ Rules:
 - Never invent section numbers or legal provisions
 - conflict_warnings: list any direct contradictions found between provisions across jurisdictions
 - amendment_notice: note if any provision appears superseded or amended, otherwise null
-"""
+"""

src/civicsetu/retrieval/__init__.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import structlog
+
+from civicsetu.ingestion.embedder import Embedder
+from civicsetu.retrieval.cache import embedding_cache, make_key
+
+log = structlog.get_logger(__name__)
+_embedder = Embedder()
+
+
+def cached_embed(query: str) -> list[float]:
+    """Embed query text with a short-lived in-process cache."""
+    key = make_key(query)
+    cached = embedding_cache.get(key)
+    if cached is not None:
+        log.debug("embedding_cache_hit", query=query[:60])
+        return cached
+
+    log.debug("embedding_cache_miss", query=query[:60])
+    embedding = _embedder.embed_query(query)
+    embedding_cache[key] = embedding
+    return embedding
+
+
+def warm_embedding_model() -> None:
+    """Load the embedding model during startup instead of the first user request."""
+    cached_embed("warmup")

src/civicsetu/retrieval/cache.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import hashlib
+
+from cachetools import TTLCache
+
+embedding_cache: TTLCache = TTLCache(maxsize=512, ttl=3600)
+retrieval_cache: TTLCache = TTLCache(maxsize=256, ttl=900)
+graph_cache: TTLCache = TTLCache(maxsize=256, ttl=900)
+
+
+def make_key(*parts: object) -> str:
+    """Return a stable SHA-256 cache key for normalized stringified parts."""
+    normalized = "|".join(str(part).strip().lower() for part in parts)
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()

src/civicsetu/retrieval/graph_retriever.py

@@ -5,6 +5,7 @@ import structlog
 
 from civicsetu.models.enums import Jurisdiction
 from civicsetu.models.schemas import RetrievedChunk
+from civicsetu.retrieval.cache import graph_cache, make_key
 from civicsetu.stores.graph_store import GraphStore
 from civicsetu.stores.relational_store import AsyncSessionLocal
 from civicsetu.stores.vector_store import VectorStore
@@ -48,13 +49,26 @@ class GraphRetriever:
         query: str,
         jurisdiction: Jurisdiction | None = None,
         depth: int = 2,
+        source_section_id: str | None = None,
     ) -> list[RetrievedChunk]:
-        section_id = GraphRetriever._extract_section_id(query)
+        section_id = source_section_id or GraphRetriever._extract_section_id(query)
 
         if not section_id:
             log.info("graph_retriever_no_section_found", query=query[:80])
             return []
 
+        jurisdiction_key = jurisdiction.value if jurisdiction else "all"
+        cache_key = make_key(section_id, jurisdiction_key, depth)
+        cached = graph_cache.get(cache_key)
+        if cached is not None:
+            log.debug(
+                "graph_retrieval_cache_hit",
+                section_id=section_id,
+                jurisdiction=jurisdiction_key,
+                depth=depth,
+            )
+            return cached
+
         # Explicit filter → search only that jurisdiction.
         # No filter → search all jurisdictions (CENTRAL first).
         jurisdictions_to_search = (
@@ -168,6 +182,7 @@ class GraphRetriever:
             pinned=len(pinned),
             deduped_total=len(deduped),
         )
+        graph_cache[cache_key] = final
         return final
 
     @staticmethod

src/civicsetu/stores/graph_store.py

@@ -384,6 +384,38 @@ class GraphStore:
             )
             return await result.data()
 
+    @staticmethod
+    async def get_topology() -> tuple[list[dict], list[dict]]:
+        driver = await _get_driver()
+        async with driver.session() as session:
+            edges_result = await session.run(
+                """
+                MATCH (s:Section)-[r]->(t:Section)
+                WHERE type(r) IN ['REFERENCES', 'DERIVED_FROM']
+                  AND s.is_active = true AND t.is_active = true
+                RETURN s.chunk_id AS source, t.chunk_id AS target, type(r) AS edge_type
+                """
+            )
+            nodes_result = await session.run(
+                """
+                MATCH (s:Section)-[r]-()
+                WHERE type(r) IN ['REFERENCES', 'DERIVED_FROM']
+                  AND s.is_active = true
+                WITH s, count(r) AS conn_count
+                RETURN DISTINCT
+                    s.chunk_id AS chunk_id,
+                    s.section_id AS section_id,
+                    s.title AS title,
+                    s.jurisdiction AS jurisdiction,
+                    s.doc_name AS doc_name,
+                    s.is_active AS is_active,
+                    conn_count AS connection_count
+                """
+            )
+            edges = await edges_result.data()
+            nodes = await nodes_result.data()
+            return nodes, edges
+
     @staticmethod
     async def graph_stats() -> dict:
         driver = await _get_driver()
@@ -400,3 +432,4 @@ class GraphStore:
             )
             record = await result.single()
             return dict(record) if record else {}
+

src/civicsetu/stores/vector_store.py

@@ -9,6 +9,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from civicsetu.config.settings import get_settings
 from civicsetu.models.enums import DocType, Jurisdiction
 from civicsetu.models.schemas import LegalChunk, RetrievedChunk
+from civicsetu.retrieval.cache import make_key, retrieval_cache
 
 log = structlog.get_logger(__name__)
 settings = get_settings()
@@ -36,6 +37,17 @@ class VectorStore:
                 f"got {len(query_embedding)}"
             )
 
+        cache_key = make_key(str(query_embedding), jurisdiction, doc_type, top_k, active_only)
+        cached = retrieval_cache.get(cache_key)
+        if cached is not None:
+            log.debug(
+                "vector_retrieval_cache_hit",
+                jurisdiction=str(jurisdiction) if jurisdiction else None,
+                doc_type=str(doc_type) if doc_type else None,
+                top_k=top_k,
+            )
+            return cached
+
         # Build dynamic WHERE clause
         filters = []
         params: dict = {
@@ -101,6 +113,7 @@ class VectorStore:
             results=len(retrieved),
             jurisdiction=jurisdiction,
         )
+        retrieval_cache[cache_key] = retrieved
         return retrieved
 
     @staticmethod

tests/conftest.py

@@ -6,7 +6,7 @@ from datetime import date
 import pytest
 
 from civicsetu.models.enums import ChunkStatus, DocType, Jurisdiction, QueryType
-from civicsetu.models.schemas import Citation, LegalChunk, RetrievedChunk
+from civicsetu.models.schemas import Citation, ChatMessage, LegalChunk, RetrievedChunk
 
 
 def _make_chunk(
@@ -55,6 +55,7 @@ def _base_state(**overrides) -> dict:
         "session_id": "test-session",
         "jurisdiction_filter": None,
         "top_k": 5,
+        "messages": [ChatMessage(role="user", content="What are promoter obligations?")],
         "query_type": None,
         "rewritten_query": None,
         "retrieved_chunks": [],