Skip to content

Web UI

Aletheia includes a web-based graph explorer for visually navigating knowledge graphs and reviewing Phronesis investigation traces.

Prerequisites

Before starting the UI, ensure the following services are running:

Service Command Default Port
FalkorDB docker start falkordb 6379
Graphiti MCP cd <graphiti-fork> && uv run mcp_server/main.py --transport http --port 8000 8000
Reasoning MCP python -m aletheia.reasoning.mcp --transport http --port 8001 --log-level WARNING 8001

Setup

cd ui
npm install
npm run dev

The UI starts at http://localhost:3001.

Features

Knowledge Graph Explorer

Select any graph from the browse panel to visualize it as an interactive force-directed graph.

  • Node rendering adapts to zoom level:
    • Zoomed out (< 0.4x): circles only
    • Medium zoom (0.4–1.5x): circles + entity names
    • Zoomed in (> 1.5x): circles + name + type badge + property values
  • Entity type colors are assigned dynamically from the graph schema
  • Edge rendering highlights connections on hover with directional arrows and relationship labels
  • Filter panel (bottom-right) toggles entity types and relationship types on/off
  • Detail panel shows properties, summary, labels, and connections for a selected node

Ontology View

Toggle the Knowledge / Ontology switch in the toolbar to see the graph's type structure. Entity types appear as labeled rectangles with instance counts, connected by their relationship patterns.

Table View

Switch to Table view for a sortable, filterable list of all entities with their properties.

Investigation Traces

Switch to the Investigations tab in the nav rail to browse Phronesis investigation traces. Each trace shows a timeline of steps — queries, reasoning, cross-graph operations, findings, and synthesis — with cycle grouping and status indicators.

Keyboard Shortcuts

Shortcut Action
Cmd+K Focus the Phronesis command bar
Esc Close the detail panel / blur command bar

Architecture

The UI is a Next.js app (ui/) that communicates with MCP servers through API routes:

Browser → Next.js API Routes → MCP Servers (Graphiti + Reasoning)
  • API routes (app/api/) bridge HTTP requests to MCP tool calls via @modelcontextprotocol/sdk
  • Graph rendering uses react-force-graph-2d with custom canvas rendering
  • State is managed at the page level with React hooks — no external state library
  • Styling uses Tailwind CSS v4 with CSS custom properties for the dark theme