← All articles

    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.

    1. Source book

      • Software Architecture: The Hard Parts (2nd Ed.)
      • O'Reilly
    2. Extract

      • Table of contents: chapters, sub-headings, pages
      • Index: keywords, keyphrases, pages

      Headings · keywords · page references

    3. Graph the content

      • Chapter
      • Section
      • Text chunk
      • Keyword

      Preserve hierarchy and context

    4. Distil & link

      • LLM
      • Summaries

      Summaries · definitions · relationships

    5. 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:

    1. How to develop architecture ontology stored in a Architecture KG - Part 1, and
    2. 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(&#x2460 Concepts)
            E(&#x2461 Architecture KG)
        end
        F(Codebase KG)
        subgraph Architecture KG Part 2
            D(&#x2462 Prompt construction)
            G(&#x2463 LLM)
            H(&#x2464 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, Word docs, 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.)

    Software Architecture: THe Hard Parts (2ed.)

    Step 1: Extracting concepts from a PDF

    Pipeline Overview

    flowchart TB
        subgraph Architecture KG
        A(Book PDF)-->C("`&#x2460 Traverse *TOC*
         - extract text`")
        A-->B("`&#x2461 Traverse *Index*
        - extract keywords`")
        B-->|Upload CSV|D(&#x2462 Neo4J)
        C-->|Upload CSV|D
        D-->|Embeddings|E(&#x2463 Node Vectors) 
        E-->|Lexical and Cosine Similarity|F(&#x2464 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:

    1. Table of Contents (TOC) - chapter heading and sub-headings give us a way to break up content, both consistently, and coherently
    2. 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:

    1. By headings or sub-headings stored in the Section node - that match keywords either:

      • lexically (BM25) - using the Lucene index 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.

    2. By text chunks stored in the TextChunk node - to see which keywords and phrases rank for a piece of text semantically

    3. By keyword stored in IndexEntry node- 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

    Gradio search tool built on top Neo4j
    • 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

    Gradio summarisation tool built on top Neo4j

    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:

    1. What is it?
    2. Why do I need it?
    3. When do I use it?
    4. 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.

    ConceptQuestionAnswerRelated ConceptHeadingPage reference
    architectural decompositionWhat is it?Describes the how of breaking apart a monolithic applicationarchitectural modularityChapter 4. Architectural Decomposition81
    architectural decompositionHow do I use it?Determine if the codebase is decomposablecodebase analysisChapter 4. Architectural Decomposition81
    codebase analysisWhat is it?To assess the codebase’s internal structureafferent and efferent couplingIs the Codebase Decomposable?83
    afferent and efferent couplingWhat is it?Measures the number of incoming connections to a code artifactsabstractness and instabilityAfferent and Efferent Coupling84
    abstractnessWhat is it?The ratio of abstract artifacts (e.g., abstract classes, interfaces) to concrete artifacts (implementation classes).distance from the main sequenceAbstractness and Instability85
    abstractnessHow 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 sequenceAbstractness and Instability85

    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

    Get started

    Want this applied to your codebase?

    Request a discovery call. We’ll talk through your system, where it hurts, and whether a Codebase Knowledge Graph is the right fit.