Skip to content

Knowledge graph

Responsibility

backend/domains/graph/ owns scanning, node and edge construction, projection, adapters, and service orchestration. graph_service.py is the stable facade used by the API, agent, and scheduler.

The graph projects explicit knowledge relationships and optional semantic suggestions into an interactive network. It supports navigation and discovery; it is derived from the Vault and is not a separate source of truth.

The strictly typed features/graph/ owns route state, filters and page composition behind a public lazy entry. Its panels and model modules are private. shared/graph/ owns the reusable renderer, minimap, geometry, keyboard navigation, edge presentation and semantic overlay. Graph routes and embedded Vault graphs import the same renderer directly, without an eager aggregate. The reviewed relocation places reusable graph filters in shared/graph/filtering/ and Vault filters in shared/filtering/. Shared code must not depend on feature or app modules, even through type imports. Projections, configuration keys, navigation, camera handles and styles remain unchanged contracts; source relocation still requires integration verification.

Graph construction

Nodes originate from indexed pages. Edges originate from wikilinks, relations, tags or other configured metadata, and optional similarity results. Graph service reads prefer index metadata and guard direct file access so an unavailable directory produces a partial graph instead of a total failure.

Unresolved wikilink targets remain representable as distinct nodes. They are not silently discarded or merged by display label because doing so would hide broken knowledge relationships.

Semantic overlay

Semantic suggestions compare document representations and produce scored candidates. Suggestions are an overlay: accepting or materializing a relation must use an explicit content-writing flow. Model unavailability disables the overlay without changing the explicit graph.

Frontend rendering

GraphViewer maps graph data into Graphology and Sigma. Layout settings control force simulation, repulsion, attraction, gravity, collision avoidance, label thresholds, edge thickness, cluster colors, and isolated-node placement.

Hover emphasis is intentionally limited to one hop. Multi-hop emphasis makes dense graphs unreadable and obscures the selected neighborhood. Isolated nodes receive enough padding and stable positioning to remain visible.

flowchart LR
    Index["Page index"] --> Explicit["Wikilink and relation edges"]
    Index --> Semantic["Optional similarity suggestions"]
    Explicit --> API["Graph API"]
    Semantic --> API
    API --> Sigma["Graphology + Sigma"]
    Sigma --> Interaction["Hover, filter, select, navigate"]

Invariants

  • Node identity uses stable page identity, not title alone.
  • Display labels may collide; identifiers may not.
  • Derived semantic edges are distinguishable from explicit relationships.
  • Layout state cannot modify Vault content.
  • Partial scans are labeled and are not cached as complete.
  • Directory-level EDEADLK and EAGAIN failures are isolated.

Verification focus

Test unresolved nodes, isolated nodes, cluster legend consistency, front-matter fallback, semantic suggestion thresholds, cloud-directory failures, one-hop hover behavior, and graph navigation back to the correct page.