Related docs: Methodology · Agent Architecture · Graph Schema · Toolchain · Provenance System
Large software systems accumulate years of undocumented logic. Programs call other programs. Databases grow to hundreds of tables. Business rules live inside conditional branches no one alive can fully explain. When the team that built the system moves on, the organisation is left with a codebase it can operate but no longer understand.
This is not a niche problem. It is the default state of most long-lived enterprise software. The consequences are real: modernisation projects stall because architects cannot map what exists, new team members spend months reverse-reading code, compliance audits demand documentation that doesn't exist, and every new feature carries hidden risk because its blast radius is unknown.
Many documentation and static-analysis tools address only part of this problem: signatures, dependencies, or generated narrative. CodeGraph focuses on connecting structural facts to business-facing documents while retaining a visible evidence trace and explicit human-review gaps.
CodeGraph is a methodology and toolchain specification for transforming an undocumented codebase into a navigable, evidence-grounded knowledge base. It makes claims traceable and gaps visible; traceability alone does not certify that evidence entails a claim or that extraction is complete.
flowchart TD
SRC["🗂️ Source Codebase"]
subgraph P1["Phase 1 — Source Ingestion"]
GB["Graph Builder"]
DE["Document Extractor"]
end
NEO[("🔵 Neo4j\nKnowledge Graph")]
subgraph P2["Phase 2 — Domain Documentation"]
VPA["VP Author Agents"]
DV["Documentation Validator"]
VT["Validation Triad"]
CA["Citation Auditor"]
end
subgraph P3["Phase 3 — Reference Layer"]
RE["Reference Expert Agents"]
RG["Reference Generators"]
end
subgraph P4["Phase 4 — Process Discovery"]
E2E["E2E Discovery Engine"]
SC["Screen Process Discoverer"]
CT["Candidate Triage"]
end
subgraph P5["Phase 5 — Vault Assembly"]
WL["Vault Wikilinker"]
VO["Vault Optimizer"]
VV["Vault Verifier"]
end
VAULT["📚 Documentation Vault"]
LD["🤖 Living Documentation"]
SRC --> P1
P1 --> NEO
NEO --> P2
NEO --> P3
NEO --> P4
P2 --> P3
P3 --> P4
P2 --> P5
P3 --> P5
P4 --> P5
P5 --> VAULT
VAULT <--> LD
style NEO fill:#008CC1,color:#fff
style VAULT fill:#2d6a4f,color:#fff
style LD fill:#6a0572,color:#fff
These principles govern every design decision. They are non-negotiable constraints, not guidelines.
Provenance-first. Every factual claim must be traceable to its source — a specific line in a source file, an edge in the knowledge graph, a field in a schema definition. Claims without provenance are not written. They are marked for human review.
Evidence grounding by construction. The system requires citations rather than relying only on a prompt not to hallucinate. Documentation agents have read-only evidence access, validation agents cannot modify the document under review, and a Citation Auditor checks tag resolution. These controls reduce unsupported output; they do not by themselves prove semantic entailment, extractor completeness, or business correctness. See Provenance System.
Evidence-only documentation. The framework documents what the code actually does — not what a system of this type typically does. Industry norms and assumed behaviour are explicitly excluded unless confirmed by source evidence.
Repeatable tools, re-validatable agents. Deterministic structural tools should produce the same logical result on identical input; run metadata may differ. LLM output is not assumed deterministic. Regenerated output must pass the same gates and record its profile, model, and evidence versions.
Source evidence governs implemented-code claims. Documentation is generated from graph and source evidence, and graph facts inherit extractor limits. Operational knowledge that code cannot establish remains an explicit SME gap. The public baseline does not define a universal conflict-resolution hierarchy between source, runtime observations, and SME attestations.
Honest gaps. Where source evidence is insufficient, the gap is tagged [SME-REVIEW-REQUIRED] with a unique ID. Gaps are tracked, counted, and assigned for human review. They are never silently filled.
flowchart LR
subgraph INGESTION["Ingestion Layer"]
SRC["Source Files"]
SCH["Schema Files (.df)"]
XRF["Compiler XRef Files"]
end
subgraph GRAPH["Graph Layer"]
NEO[("Neo4j\nKnowledge Graph")]
JSON["graph.json"]
EXT["extraction.json"]
end
subgraph AGENTS["Agent Layer"]
AUTH["Author Agents"]
VAL["Validation Triad"]
AUD["Citation Auditor"]
ENR["Enrichment Agents"]
end
subgraph OUTPUT["Output Layer"]
VAULT["Markdown Vault"]
MOC["Maps of Content"]
SME["SME Dashboard"]
end
subgraph LIVE["Living Docs Layer"]
QA["Q&A Agent"]
CORR["Correction Loop"]
end
SRC --> JSON
SCH --> JSON
XRF --> JSON
JSON --> NEO
JSON --> EXT
NEO --> AUTH
EXT --> AUTH
AUTH --> VAL
VAL --> AUD
AUD --> VAULT
ENR --> VAULT
VAULT --> MOC
VAULT --> SME
VAULT --> QA
QA --> CORR
CORR --> VAULT
CodeGraph uses GraphRAG — Retrieval-Augmented Generation where the retrieval source is a property graph rather than a vector store. This matches the origin method's emphasis on explicit program, table, screen, and document relationships.
The key architectural decision is that the LLM generates documentation from pre-defined graph traversal results — it does not generate or execute graph queries itself.
flowchart LR
REQ["Document\nSection Request"]
TMPL["Cypher Query\nTemplate Library"]
NEO[("Neo4j")]
CTX["Structured Context\n(query results)"]
LLM["Claude Agent"]
DOC["Document Section\n+ Citation Tags"]
AUD["Citation Auditor\nVerification"]
REQ --> TMPL
TMPL -->|"parameterised\nCypher query"| NEO
NEO -->|"structured\nresult set"| CTX
CTX --> LLM
LLM --> DOC
DOC --> AUD
AUD -->|"pass ✓"| DOC
AUD -->|"fail ✗"| LLM
Why templated Cypher over LLM-generated queries: generated Cypher can reference node labels and relationship types that do not exist, return empty results on schema mismatches, and be difficult to audit. Pre-defined templates can be tested against a known graph contract. The repository currently ships only a reconstructed seed library, not the original full PoC library.
flowchart TD
DOC["Document\n(authored by VP Agent)"]
subgraph TRIAD["Validation Triad — all read-only"]
DEF["🛡️ Defender\nArgues document is correct"]
CHAL["⚔️ Challenger\nIdentifies gaps and errors"]
JUDGE["⚖️ Judge\nIssues binding verdict"]
end
AUDIT["🔍 Citation Auditor\nVerifies every tag · Read-only"]
CORR["Corrections applied\nby original Author Agent"]
DOC --> DEF
DOC --> CHAL
DEF --> JUDGE
CHAL --> JUDGE
JUDGE -->|"Required corrections"| CORR
CORR -->|"Updated document"| AUDIT
AUDIT -->|"All tags verified ✓"| DOC
style DEF fill:#1a6b3c,color:#fff
style CHAL fill:#8b1a1a,color:#fff
style JUDGE fill:#1a3a6b,color:#fff
style AUDIT fill:#555,color:#fff
No agent in the validation triad can write to the document under review. Corrections are issued as a verdict and applied by the original authoring agent. The Citation Auditor runs after the triad and operates independently. See Agent Architecture for full details.
Status: design specification. The Q&A agent, correction validator, and update engine are not among the published tool implementations, and the PoC conflict- resolution behavior has not been recovered. The diagram preserves the documented design; changing its trust policy is a separate experiment.
flowchart TD
VAULT["📚 Knowledge Vault\nMarkdown · Mermaid · Wikilinks"]
GRAPH[("🔵 Neo4j Graph")]
USER["👤 User"]
QA["🤖 Q&A Agent\nGraphRAG · Citation-grounded answers"]
VA["🔍 Validation Agent\nVerifies corrections against graph"]
UE["✏️ Update Engine\nPatches markdown · Propagates wikilinks"]
USER -->|"natural language question"| QA
QA -->|"GraphRAG query"| GRAPH
QA -->|"search"| VAULT
QA -->|"answer + citation tags"| USER
USER -->|"correction or feedback"| VA
VA -->|"verify against graph"| GRAPH
VA -->|"contradicts recorded evidence\n→ reject (documented design)"| USER
VA -->|"confirmed\n→ approve"| UE
UE -->|"patch + propagate"| VAULT
style QA fill:#6a0572,color:#fff
style VA fill:#1a3a6b,color:#fff
style UE fill:#1a6b3c,color:#fff
CodeGraph originated in a real-world legacy manufacturing-system engagement: a 15-year-old codebase written in a proprietary fourth-generation language and parsed with regex-based detection. The repository reports the results below. The original artifacts, exact denominators, and evaluation protocol are not published, so the table is a case-study record rather than an independently reproducible benchmark.
| Metric | Result |
|---|---|
| Sprints to complete | 15 |
| Source files analysed | ~3,900 |
| Validation packages produced | 19 |
| Programs documented | 851 (~99% coverage) |
| Business rules extracted | 572 |
| User stories produced | 248 |
| Screens catalogued | 506 |
| End-to-end processes discovered | 18 |
| Compliance gaps surfaced | 5 critical |
| Hallucinations detected on first complete pass | 0 reported; protocol not published |
| SME review items flagged | 191 (honest gaps, not hallucinations) |
| Total documentation lines | 165,970 |
Reported architectural finding: The E2E discovery process led the engagement team to conclude that modules integrated through shared staging tables rather than direct calls. The team reported that this previously undocumented conclusion had significant implications for the modernisation plan. The public repository does not contain the graph snapshot and review evidence needed to reproduce it.
- Methodology — The 5-phase pipeline in depth
- Agent Architecture — Agent roles, constraints, and the adversarial validation pattern
- Graph Schema — Node types, edge types, and the provenance model
- Toolchain — Interface specifications for 36 unshipped Python tools by phase
- Provenance System — Citation tags, checks, and limitations