Knowledge Graph · Veritas

Purpose#

The Veritas Knowledge Graph is a full-screen entity-network workspace. It renders the local Veritas graph fixture, lets a signed-in user filter/search the network, inspect an entity profile, trace a path between entities, and audit graph-level statistics.

Entry points#

• Direct URL / bookmark — /domains/veritas/knowledge-graph (auth required)
• /domains/veritas index — internal Veritas tool grid
• /library / shell navigation — the route can be opened after a shell page and the Close control returns with router.back()

Layout regions#

page.tsx is a client route that renders an sr-only <h1> and mounts <VeritasKnowledgeGraph onClose={() => router.back()} />.

• Overlay root: [data-veritas-knowledge-graph] with current data-veritas-knowledge-graph-view, total nodes/edges, selected node, and reduced-motion state.
• Header: title, [data-veritas-knowledge-close], and tablist [data-veritas-knowledge-tabs].
• Graph view: [data-veritas-knowledge-network] with live filtered node/edge counts, a searchable/type-filtered sidebar, zoom/fit controls, SVG node buttons, visual edges, and a selected-entity summary card.
• Entity profile view: [data-veritas-knowledge-profile-view] with entity selector, metrics, metadata, and keyboardable relationship rows.
• Path finder view: [data-veritas-knowledge-path-view] with start/target selectors and automatic BFS path rendering.
• Stats view: [data-veritas-knowledge-stats-view] with aggregate counters, entity type distribution, most-connected entity, and keyboardable sorted entity rows.

States#

• Authenticated render — route opens through the signed-in shell and renders [data-veritas-knowledge-graph].
• Graph view, all types enabled — total fixture nodes/edges match KNOWLEDGE_GRAPH_DATA.
• Graph view, type-filtered — toggling an entity type updates data-veritas-knowledge-filtered-nodes.
• Graph view, search active — search filters rendered nodes by entity name.
• No explicit selection profile fallback — entity-profile tab renders the first fixture node when no graph node has been selected.
• Entity profile, populated — selected entity name, metrics, and relationship count are asserted from the fixture.
• Path finder, idle/found — selectors expose idle state, then a found path with hop count and rendered path nodes/edge.
• Stats view — total entities, relationships, type buckets, and most-connected entity are fixture-backed.
• Offline — standalone mobile test switches the browser context offline and continues search/profile/path/stats interactions from local data.
• Standalone PWA — mockStandaloneLaunch() restores directly into the route from /?surface=pwa.
• Reduced motion — the force layout skips animation under prefers-reduced-motion; stats bars collapse their transition duration.
• Mobile horizontal overflow — mobile standalone/offline test asserts no document overflow at 390×844.

Interactions#

• Close — [data-veritas-knowledge-close] has an accessible name, 44×44 target, keyboard activation, and returns to /library in the desktop path.
• Tabs — graph, entity-profile, path-finder, and stats expose active state through data-veritas-knowledge-tab-active.
• Type filters — entity-type buttons expose active state and fixture type counts.
• Search — [data-veritas-knowledge-search] filters graph nodes by case-insensitive name match.
• Graph node selection — SVG node groups are keyboardable buttons with selected-node state and accessible names.
• Selected profile action — selected graph card opens entity profile.
• Relationship rows — profile relationship rows are keyboardable and swap the selected profile entity.
• Path selectors — selecting source/target updates path status and renders the BFS path.
• Stats entity rows — sorted entity rows are keyboardable and drill into the profile view.

Data & contracts#

• Reads: KNOWLEDGE_GRAPH_DATA and ENTITY_TYPE_CONFIGS from apps/oshun/web/src/lib/veritas/veritas-simulation-data.ts.
• Fixture shape: KNOWLEDGE_GRAPH_DATA.nodes, .edges, and .stats where stats are derived from the fixture by computeKgStats().
• Types: KnowledgeGraphNode, KnowledgeGraphEdge, KnowledgeEntityType, and KnowledgeRelationType from veritas-types.ts.
• Writes: local React state only (view, selectedNodeId, searchQuery, enabledTypes, zoom/pan, hop depth, path endpoints).
• Realtime / external network: none for the core route; the graph remains usable while the browser context is offline.
• Telemetry: no route-local telemetry import or event dispatch.

Current E2E Evidence#

• apps/oshun/web/e2e/veritas-knowledge-graph.spec.ts
  • Desktop graph state, fixture totals, type filter, search, keyboard node selection, selected profile, and close keyboard flow.
  • Profile relationship metrics, keyboard relationship selection, path tracing, stats totals/type distribution/most-connected entity, reduced-motion bar transition.
  • Standalone PWA restore, offline mobile graph/profile/path/stats use, and no horizontal overflow at 390×844.

Cross-references#

• Component: apps/oshun/web/src/components/domains/veritas/VeritasKnowledgeGraph.tsx
• Route: apps/oshun/web/src/app/domains/veritas/knowledge-graph/page.tsx
• Customer-facing Veritas surfaces: veritas.md
• Feature spec: V1/features.md

Open Questions / Known Gaps#

• Graph state is not persisted in the URL or user profile; selected entity and path endpoints reset on route remount.
• No telemetry currently records entity selection, type filtering, or path tracing.
• Edges are visual-only; the V1 customer contract does not yet specify edge drill-in behavior.
• Live assistive-technology and touch-device manual passes remain outside the automated evidence.