The case for an Architecture Knowledge Graph (KG): Part 1
In my previous post, I suggested that reverse engineering legacy software into a Codebase KG could give an LLM the right context to perform a task. However a Codebase KG only gives you application code artifacts and the relationships between them. There is still an analytical task that needs to be undertaken to analyse the codebase. So what's the best way to examine a codebase and describe its' system context?
The AI Architecture SeriesPart 1 of 2
From a Book to a Knowledge Graph
Turning architectural knowledge into actionable analysis.
Source book
- Software Architecture: The Hard Parts (2nd Ed.)
- O'Reilly
Extract
- Table of contents: chapters, sub-headings, pages
- Index: keywords, keyphrases, pages
Headings · keywords · page references
Graph the content
- Chapter
- Section
- Text chunk
- Keyword
Preserve hierarchy and context
Distil & link
- LLM
- Summaries
Summaries · definitions · relationships
Operational ontology
- Calculations
- Decision criteria
- Architecture ontology
- Analysis techniques
Source-grounded architectural reasoning
Grounded in sources
Trace concepts back to the book and cite original references.
Built iteratively
Search, summarise, connect and refine.
Designed to act
Link concepts to calculations and decisions.
In my previous post, I suggested that reverse engineering legacy software into a Codebase KG could give an LLM the right context to perform a task.
However a Codebase KG only gives you application code artifacts and the relationships between them. There is still an analytical task that needs to be undertaken to analyse the codebase.
So what’s the best way to examine a codebase and describe its’ system context?
Interacting with the Codebase KG
In the hands of an experienced software architect a Codebase KG is all that is required. Prior knowledge built up over years of designing and refactoring systems inform the type of graph queries that need to be run to answer questions like:
- Which functions are tightly coupled?
- Can I find cohesive units that collectively access the data layer?
- Are there any identifiable UI frameworks being used?
What if experienced individuals are not readily available? Or resource constraints (eg. time & cost), or governance over ‘what’s in the head’ of individuals is necessary? And in today’s world what role does AI have in all of this?
With this backdrop, it makes sense to add an ontological layer above the Codebase KG to serve as a governed resource for architectural knowledge and reasoning - an Architecture KG. Not only can we give precise meaning to terms, but ground the pattern-identification task as well.
Giving precise meaning to terms and activities: an Architecture KG
The formal definition of a term or activity is often called an ontology. Ontologies and KGs have been around for 40+ years. And thanks to AI, there’s considerable renewed interest in them as a means for information and data governance.
However the traditional approach of building ontologies is time-consuming and often unrelated, or not in sync with the underlying systems they are meant to represent.
What’s the point of developing a machine-readable ontology when no machine actually uses it?
In a 2-part post I want to bridge this gap and address:
- How to develop architecture ontology stored in a Architecture KG - Part 1, and
- How can it be used, by both humans and AI agents when interacting with code - Part 2.
Post overview
flowchart TD
A(Source of Architecture Knowledge)
subgraph Architecture KG Part 1
B(① Concepts)
E(② Architecture KG)
end
F(Codebase KG)
subgraph Architecture KG Part 2
D(③ Prompt construction)
G(④ LLM)
H(⑤ Analysis functions)
end
J(Github Repo)
I(Ontology-aware application)
A-->B
B-->E
E-->D
D-->G
G-->H
J-->I
F-->D
F<-->J
H-->F
Where does the architecture knowledge come from?
The first step to building an Architecture KG is finding authoritative sources of architecture knowledge. These could be:
- Corporate wikis -
Confluence,Sharepoint - Technical books -
O'Reilly,Manning,No Starch Press - Policy documents - eg. Architectural Decision Records in
PDFs,Worddocs, etc. - Industry body publications
- Technical standard publications
When we have a direct reference to a source of knowledge, we can cite references to each element of the Architecture KG. This enables alternative interpretations to be modeled explicitly for further discussion and analysis. This is not possible when knowledge is not documented formally.
To illustrate the building of an Architecture KG, I’ll be using the seminal O’Reilly textbook,
Software Architecture: The Hard Parts (2nd Ed.)
Step 1: Extracting concepts from a PDF
Pipeline Overview
flowchart TB
subgraph Architecture KG
A(Book PDF)-->C("`① Traverse *TOC*
- extract text`")
A-->B("`② Traverse *Index*
- extract keywords`")
B-->|Upload CSV|D(③ Neo4J)
C-->|Upload CSV|D
D-->|Embeddings|E(④ Node Vectors)
E-->|Lexical and Cosine Similarity|F(⑤ Ontology design)
F-->G(Architecture KG)
end
Step 2: Storing contents in a graph simplifies contextual search: GraphRAG
With highly edited content like a textbook, we have two pieces of metadata that help with deriving the semantics of long-form content:
- Table of Contents (TOC) - chapter heading and sub-headings give us a way to break up content, both consistently, and coherently
- Index - professionally extracted keywords and keyphrases to help with searching for the most relevant piece of text
We now have a clear and easy way to break apart, and store, text content in a format that preserves the hierarchical nature of chapter titles and sub-titles. The same applies to the information contained in the Index section of the book.
So both the fundamental building blocks for information extraction are in place. Text chunks with their headings, and keywords to search for relevant headings or text chunks.
Book graph schema (Neo4j)
- Book → CONTAINS → Section
- Section → CONTAINS → Section
- Section → HAS_INDEX_ENTRY → IndexEntry
- Section → HAS_TEXT → TextChunk
- IndexEntry → HAS_SUBENTRY → IndexEntry
With text chunks stored in a graph format, we can search for relevant content in 3 ways:
-
By headings or sub-headings stored in the
Sectionnode - that match keywords either:- lexically (BM25) - using the
Luceneindex that powers most full-text search queries, or - semantically - using word embedding models like
qwen3-embedding-8b
The underlying text chunk and any related sub-headings are then extracted via graph queries.
- lexically (BM25) - using the
-
By text chunks stored in the
TextChunknode - to see which keywords and phrases rank for a piece of text semantically -
By keyword stored in
IndexEntrynode- to find which text chunks rank for a particular keyword both lexically or semantically
With the entire book stored in a graph, a simple User Interface overlay speeds up the information extraction process.
Keyword Search Tool
- Search tool built using Gradio and Neo4j
What to do when there are no keyword indexes readily available
There are numerous public industry-sponsored ontologies that can serve as a starting point for keywords - with the added benefit of links between them. For the financial services, there’s the Financial Industry Business Ontology (FIBO), and in the legal domain the Legal Knowledge Interchange Format (LKIF), is popular.
Step 2: From keywords to an ontology (Architecture KG)
Ontologies that are actively used are built progressively and iteratively. Hence it is critical to develop a workflow that let’s you build an ontology-aware application as quickly as possible.
1. Start with a question or problem that needs to be solved
A question or problem statement gives you the keywords to find relevant content. In our case it would be something like:
What are the best practices to decompose an unfamiliar codebase?
Canditate keyword: decompose
Using the Keyword Search Tool, we can quickly surface the top relevant sections of text.
2. Process text chunks quickly - use LLM summaries
Even section-based content can take time to read and understand. This is where text summarisation by an LLM can expedite the process by providing a first pass condensation.
A small model like
Mistral-Small-3.2-24B-Instruct, which can be hosted
locally and incur no token cost, is more than sufficient for this task.
Text summarisation with Mistral 35B
3. Extracting an ontology from text summaries
Ontologies are traditionally associated with the definition of things. However for practical purposes it is more useful to have ontologies that drive action.
This is easiest done by attaching question and answer pairs to each keyword / phrase definition:
- What is it?
- Why do I need it?
- When do I use it?
- How do I use it?
- Not all questions are necessary for every concept
For example the keyphrase - ‘architectural decomposition’ - is associated with text summaries that clearly layout a decision matrix on how to go about decomposition.
| Concept | Question | Answer | Related Concept | Heading | Page reference |
|---|---|---|---|---|---|
| architectural decomposition | What is it? | Describes the how of breaking apart a monolithic application | architectural modularity | Chapter 4. Architectural Decomposition | 81 |
| architectural decomposition | How do I use it? | Determine if the codebase is decomposable | codebase analysis | Chapter 4. Architectural Decomposition | 81 |
| codebase analysis | What is it? | To assess the codebase’s internal structure | afferent and efferent coupling | Is the Codebase Decomposable? | 83 |
| afferent and efferent coupling | What is it? | Measures the number of incoming connections to a code artifacts | abstractness and instability | Afferent and Efferent Coupling | 84 |
| abstractness | What is it? | The ratio of abstract artifacts (e.g., abstract classes, interfaces) to concrete artifacts (implementation classes). | distance from the main sequence | Abstractness and Instability | 85 |
| abstractness | How do I use it? | Calculate the sum of abstract components, over the all components. A low score indicates difficulty to read code. | distance from the main sequence | Abstractness and Instability | 85 |
Linking keywords and phrases by asking definitional questions effectively creates an ontology of semantically linked concepts with a citation to source content. This is the function of the Architecture KG.
However the objective is not just have ‘explainability’ of concepts but a direct mapping to the Codebase KG.
4. Ontological concepts have an analytical counterpart
If we follow the process of semantically linking architecture concepts in the manner outlined above, we will end up with the recommended calculations and decision criteria on how to decompose a codebase:
Keyword: ‘architectural decomposition’
flowchart TB
A(architectural decomposition)
B(codebase analysis)
C(afferent and efferent coupling)
D(abstractness and instability)
E("`abstractness
- **Calculation**`")
F("`instability
- **Calculation**`")
H(decomposable)
I(definable components)
J(component-based decomposition)
K(tactical forking)
L(distributed application)
M("`distance from main sequence
-**Calculation**`")
A-->B
B-->C
C-->F
B-->D
D-->E
D-->F
E-->M
F-->M
M-->|Yes/No|H
H-->|Yes|I
I-->|Yes|J
I-->|No|K
J-->L
K-->L
Calculations and decision criteria are ontological properties which are stored as part of the Architecture KG. These form the basis for application functionality - aka. business requirements.
In Part 2, we link the Architecture KG to the Codebase KG to build what we call an ontology-aware application.
Summary
How do you turn architectural knowledge buried in technical books and the experience of individual architects into something an AI can actually use?
In this first part, I explore building an Architecture KG that connects architectural concepts to the calculations, decision criteria and analytical techniques needed to assess an unfamiliar codebase.
Using Software Architecture: The Hard Parts (2nd Ed.) as a worked example, I show how to transform a book’s table of contents, index and content into a searchable graph, use LLM summaries to distil relevant knowledge, and progressively develop an ontology grounded in its original sources.
The key idea is to make architectural knowledge operational, not just descriptive: concepts such as architectural decomposition should lead to concrete ways of analysing code and deciding what to do next.
Part 2 takes the next step: connecting this Architecture KG to a Codebase KG so that humans and AI agents can apply architectural reasoning directly to real code.
This article shows the thinking behind our Knowledge graph build engagement. A full Codebase KG your team owns.
Discussion