Skip to content

Frontend

Rupak Chakraborty edited this page May 20, 2026 · 1 revision

Frontend

The frontend is a Next.js 15.5 application using the App Router, React 19, TypeScript, and TailwindCSS 4. It communicates with the backend exclusively via the REST API and SSE stream.


Directory structure

frontend/src/
β”œβ”€β”€ app/                        # Next.js App Router
β”‚   β”œβ”€β”€ layout.tsx              # Root layout β€” providers, theme, fonts
β”‚   β”œβ”€β”€ page.tsx                # Home page β€” search box + results
β”‚   β”œβ”€β”€ sessions/               # Session management pages
β”‚   └── admin/                  # Admin-only pages (user management)
β”œβ”€β”€ components/
β”‚   β”œβ”€β”€ graph/
β”‚   β”‚   β”œβ”€β”€ CausalGraph.tsx     # Main React Flow wrapper
β”‚   β”‚   β”œβ”€β”€ EventNode.tsx       # Custom node component
β”‚   β”‚   └── CausalEdge.tsx      # Custom edge component
β”‚   β”œβ”€β”€ results/
β”‚   β”‚   β”œβ”€β”€ StreamingNarrative.tsx  # Markdown + streaming text display
β”‚   β”‚   └── SourceCitations.tsx     # Citations panel, grouped by tier
β”‚   β”œβ”€β”€ search/
β”‚   β”‚   β”œβ”€β”€ SearchBox.tsx       # Query input with submit
β”‚   β”‚   └── PresetPrompts.tsx   # 12 starter question cards
β”‚   β”œβ”€β”€ timeline/
β”‚   β”‚   └── D3Timeline.tsx      # D3 zoomable timeline
β”‚   └── sessions/
β”‚       β”œβ”€β”€ SessionList.tsx     # Sidebar session list
β”‚       └── SaveDialog.tsx      # Name-and-save modal
β”œβ”€β”€ hooks/
β”‚   β”œβ”€β”€ useStreamingQuery.ts    # SSE connection + event parsing
β”‚   β”œβ”€β”€ useGraph.ts             # React Flow state management
β”‚   β”œβ”€β”€ useSessions.ts          # Session CRUD
β”‚   └── usePresets.ts           # Preset question fetching
β”œβ”€β”€ lib/
β”‚   β”œβ”€β”€ api.ts                  # Typed fetch wrappers for all API calls
β”‚   β”œβ”€β”€ sse.ts                  # SSE client utilities
β”‚   β”œβ”€β”€ types.ts                # Shared TypeScript types
β”‚   └── utils.ts                # Helpers (classnames, date formatting)
└── providers/
    β”œβ”€β”€ AuthProvider.tsx        # JWT context + login/logout
    └── ThemeProvider.tsx       # next-themes dark/light wrapper

Next.js App Router structure

The app uses the App Router (not Pages Router). Route segments:

  • / β€” the main analysis page (search + results)
  • /sessions β€” session list and session detail view
  • /admin β€” user management (redirects non-admins)

Client components (those using hooks, browser APIs, or event handlers) are marked with "use client". Server components are used for static layout, metadata, and font loading.


Zustand store

State is managed by a single Zustand store (frontend/src/lib/store.ts or similar). The store holds:

  • currentQuery β€” the active question string
  • sessionId β€” active session UUID
  • narrative β€” accumulated streaming text
  • nodes / edges β€” React Flow graph state
  • timeline β€” D3 timeline data
  • sources β€” citation list
  • isStreaming β€” boolean, true while SSE is open
  • streamingPhase β€” current phase number (1–4), used for progress indicator

The store is not persisted to localStorage β€” sessions are persisted server-side. On page reload, the last active session is re-fetched from the API.


Custom hooks

useStreamingQuery

frontend/src/hooks/useStreamingQuery.ts

Opens an SSE connection to POST /api/query, parses each event type, and dispatches to the Zustand store. Key behaviours:

  • Uses the Fetch API with ReadableStream (not the EventSource API) so POST requests with a body are supported β€” EventSource only does GET
  • Maintains an internal buffer to handle cases where multiple SSE events arrive in the same chunk
  • On narrative events: appends the chunk to the narrative store field
  • On first graph event: sets nodes and timeline, leaves edges empty
  • On second graph event: merges edges into existing node state
  • On done or error: sets isStreaming = false, closes the stream
  • Exposes a cancel() function that aborts the fetch and closes the stream

useGraph

frontend/src/hooks/useGraph.ts

Wraps React Flow's internal state with the app's graph data. Handles:

  • Receiving node/edge arrays from the store and converting to React Flow format
  • Running Dagre layout when edges are first added
  • Exposing onNodesChange and onEdgesChange handlers for user edits
  • saveGraph() β€” debounced call to PATCH /api/sessions/{id}/graph after user edits
  • exportPNG() β€” uses React Flow's getNodes() + HTML Canvas to export the graph as a PNG file

useSessions

frontend/src/hooks/useSessions.ts

Manages session CRUD:

  • sessions β€” list of the user's sessions
  • loadSession(id) β€” fetches full session detail and restores narrative + graph state
  • saveCurrentSession(name) β€” creates or renames the active session
  • deleteSession(id) β€” deletes and removes from list

usePresets

frontend/src/hooks/usePresets.ts

Fetches the 12 preset questions from GET /api/presets on mount. Simple: no pagination, no caching beyond the component lifecycle.


React Flow integration

CausalGraph.tsx wraps the React Flow <ReactFlow> component with:

  • nodeTypes={{ eventNode: EventNode }} β€” registers the custom node
  • edgeTypes={{ causalEdge: CausalEdge }} β€” registers the custom edge
  • Controls panel (zoom in/out, fit view, export PNG)
  • MiniMap for orientation on large graphs
  • Background grid pattern

EventNode (graph/EventNode.tsx): Renders as a styled card with: event name (bold), date (muted), type badge (colour-coded: political/military/economic/social/cultural), and a truncated description. Handle positions: left (target) and right (source). Selected state shows a highlighted border.

CausalEdge (graph/CausalEdge.tsx): Custom edge component using React Flow's getStraightPath or getBezierPath. Opacity is set from data.confidence (0.3–1.0 β†’ 30%–100% opacity). Edge label shows the relationship type on hover. Colour is determined by relationship type:

  • direct_cause β€” red
  • contributing_factor β€” orange
  • enabling_condition β€” yellow
  • consequence β€” blue
  • feedback_loop β€” purple

D3 timeline integration

D3Timeline.tsx renders a zoomable horizontal timeline using D3.js 7. Events are positioned by their date_numeric value (decimal year). Zoom is handled by d3.zoom() with x-axis rescaling. Clicking a timeline event highlights the corresponding node in React Flow (via shared event ID).

The timeline is rendered into a <svg> element via a useEffect hook that runs D3 imperatively. D3 manages the DOM inside the SVG directly; React manages the container. This is intentional β€” mixing React and D3 for the same DOM nodes causes conflicts.


SSE parsing in useStreamingQuery

The Fetch API returns a ReadableStream<Uint8Array>. The hook reads this with a TextDecoder and accumulates text until it finds complete event: / data: pairs. SSE events are separated by blank lines (\n\n). The parser:

  1. Splits on \n\n
  2. For each complete event block, extracts the event: type and data: JSON
  3. Calls the appropriate Zustand action
  4. Leaves incomplete blocks in a carry buffer for the next chunk

Theme switching

ThemeProvider.tsx wraps next-themes's ThemeProvider. The root layout applies the theme class to <html>. TailwindCSS 4 uses CSS variables for all colour tokens β€” switching theme classes swaps the variable values, no JavaScript rerender needed.

The theme toggle button (in the top navigation) calls useTheme().setTheme(...) from next-themes.


Auth flow and protected routes

AuthProvider.tsx holds the JWT token in memory (not localStorage, to reduce XSS surface area). On mount, it attempts to restore the session from a httpOnly cookie managed by Next.js middleware β€” if the cookie is present and the token is valid, the user is considered logged in without showing the login screen.

Protected routes check useAuth().isAuthenticated. If false, they redirect to the login page. The login form calls POST /auth/login, stores the returned token, and redirects to /.

Admin routes additionally check useAuth().user.is_admin and redirect non-admin users.

Clone this wiki locally