LoreGraph

Evidence-backed repository intelligence for VS Code.

LoreGraph extracts the business concepts, configuration dependencies, and code relationships hidden inside complex enterprise codebases, builds them into a knowledge graph, and turns that graph into an interactive visual map and Docusaurus documentation — without ever inventing a fact.

Core thesis: No evidence, no documentation claim. LoreGraph is not a generic AI doc generator. Every entity, relationship, and sentence it produces links back to a specific file and line in your repository.

The problem: tribal knowledge

Large enterprise systems bury years of undocumented knowledge in config files, environment variables, feature flags, Spring classes, Kafka topics, database schemas, comments, acronyms, and half-stale docs. New engineers can't tell what a business term means, where it's implemented, which configs control it, or which docs to trust.

LoreGraph makes that knowledge explicit and auditable.

How it works

Repository Scanner → Config Parser → Code Usage Resolver → Domain Term Extractor
→ Annotation Extractor → Relationship Builder → Knowledge Graph → Confidence Scorer
→ Visual Graph Builder → Documentation Generator → Drift Detector

1. Scan the workspace (skipping node_modules, target, .env, secrets, etc.).
2. Extract entities and relationships with deterministic, regex/AST-light heuristics.
3. Build a knowledge graph where every node and edge carries SourceRef evidence.
4. Score confidence: human annotations = high, multi-source = boosted, naming-only = low.
5. Visualize the graph inside VS Code (React + React Flow).
6. Generate Docusaurus docs from graph-backed claims only.
7. Flag missing/uncertain knowledge as explicit open questions.

Anti-hallucination design

• Documentation claims are generated only from extracted graph evidence.
• Inferred meanings are hedged ("appears to", "is likely related to").
• Insufficient evidence produces an open question, never an invented answer.
• Every generated page has an Evidence section and a confidence badge.
• Existing docs/comments and multiple independent sources raise confidence; naming alone stays low.
• Human @lore annotations produce high-confidence, verified claims.

Human-in-the-loop annotations

Drop @lore comments anywhere (//, #, *, --):

// @lore.term Reconciliation
// @lore.purpose Compares trade records across systems to identify breaks.
// @lore.owner Trade Operations Platform
// @lore.risk Changing retry settings may delay end-of-day break detection.

These become verified, high-confidence graph claims.

Visual Graph Explorer

Four modes, one interactive canvas:

• Concept Graph — Obsidian-style map of business terms ↔ configs, services, topics, tables, docs.
• Config Dependency Map — where each config key is defined, read, and documented.
• Architecture Map — simplified C4 view: API → services → messaging → data & config.
• Flow Map — directional event flows from Kafka producers to consumers.

Search, filter by entity type (click the legend) and confidence, focus a node, click evidence to jump to source, and inspect any node's claims, related entities, and open questions.

Generated documentation

LoreGraph: Generate Documentation Site writes a ready-to-build Docusaurus project:

loregraph-docs/
  docs/
    intro.md
    onboarding/{start-here,knowledge-map}.md
    business-terms/{glossary, <term>.md ...}
    configuration/{overview,config-keys,feature-flags,environment-variables}.md
    architecture/{overview,service-map,concept-map}.md
    flows/{inferred-flows,kafka-flows}.md
    operations/{open-questions,docs-drift-report}.md
  docusaurus.config.ts
  sidebars.ts
  package.json

Every page includes title, status, confidence, summary, evidence-backed claims, related concepts/configs/code, open questions, and a "Needs Human Review" section where applicable.

Setup & running

npm install
npm run compile          # bundles the extension + webview via esbuild
# Press F5 in VS Code → "Run LoreGraph Extension"

The launch config opens the bundled demo repo (examples/demo-enterprise-system) in the Extension Development Host.

Commands (Command Palette → "LoreGraph:")

Run the demo

1. npm install && npm run compile
2. Press F5 to launch the Extension Development Host (opens the demo repo).
3. Run LoreGraph: Analyze Repository — watch the sidebar populate.
4. Run LoreGraph: Open Graph Explorer — explore the four views.
   • Click Reconciliation (🟢 verified) → see its purpose, owner, risk, config keys, and Kafka flow.
   • Click Settlement (🔴 inferred) → note the hedged summary and open questions.
5. Run LoreGraph: Generate Documentation Site → open loregraph-docs/docs/intro.md.
6. Run LoreGraph: Detect Documentation Drift → the deprecated old-reconciliation-notes.md is flagged.

Testing

npm test     # node:test + tsx; covers extraction, scoring, relationships, docs, drift, serialization
npm run lint

Architecture

src/
  extension.ts            graphStore.ts
  commands/               # 8 user commands + internal generate-docs-for-node
  scanners/               # workspace, config, java-spring, kafka, database, docs, typescript
  extractors/             # configKey, envVar, annotation, businessTerm, ownership, usageResolver
  graph/                  # graphTypes, knowledgeGraph, graphBuilder, relationshipBuilder,
                          # confidenceScorer, claimGenerator, evidenceStore, graphSerializer
  visual/                 # concept/config/architecture/flow map builders + layout
  generators/             # docusaurus, glossary, config, architecture, flow, openQuestions, sidebar
  drift/                  # docsDriftDetector, fileHashStore
  views/                  # tree provider, webview provider, node inspector
  ai/                     # llmProvider (interface), localTemplateProvider, prompts, schemaTypes
  config/                 # .loregraph.yml loader
  utils/                  # file, path, line, yaml, text, git helpers
  webview/src/            # React + React Flow app (App, GraphCanvas, Inspector, 4 views, ...)
examples/demo-enterprise-system/   # realistic Java/Spring trade-reconciliation demo
test/                     # node:test suites

Local-first, no external API

The MVP runs entirely offline. The LLMProvider interface exists for future AI providers, but the default LocalTemplateProvider generates all documentation deterministically from the grounded EvidenceBackedPrompt — which, by contract, only ever exposes graph evidence, never raw source.

Roadmap

• Real LLM provider integration (grounded by the same evidence contract)
• GitHub PR documentation drift checks
• Jira/Confluence import
• CODEOWNERS-based ownership mapping (partial today)
• Mermaid / C4 export (Mermaid in architecture docs today)
• Docusaurus deployment workflow
• Team review workflow for verifying generated claims
• Semantic embeddings for better term clustering
• Language Server integration for precise references

Résumé bullets

• Built LoreGraph, a VS Code extension that extracts business concepts, config dependencies, and code relationships from enterprise repositories into an evidence-backed knowledge graph.
• Developed an interactive C4/Obsidian-style visual explorer inside VS Code mapping business terms to services, config keys, Kafka topics, database tables, and documentation pages.
• Designed an anti-hallucination documentation pipeline that generates Docusaurus docs only from source-cited claims, confidence scores, and human-verifiable annotations.

Screenshots

Placeholders — capture from the Extension Development Host:

• docs/screenshots/graph-explorer.png — Concept Graph with the inspector open
• docs/screenshots/config-map.png — Config Dependency Map
• docs/screenshots/generated-docs.png — A generated business-term page

License

MIT