DEV Community: Gert

Building Enola, Part 2: From Source Code to an Architectural Fact Model

Gert — Tue, 04 Aug 2026 19:09:12 +0000

In Part 1, I explained why Enola extracts deterministic architectural facts before an AI agent begins reasoning.

That leaves the next design question:

How should those facts be represented?

The obvious answer is to build a graph containing every symbol, dependency, route, service, and repository.

But the difficult part is not putting nodes and edges into a graph.

It is preserving what those relationships mean.

A function call is not the same as a package dependency. A route registration is not an import. A type reference is not proof that two services share a contract.

If every relationship becomes a generic connection, the resulting graph may be traversable, but it is no longer reliable enough for architectural analysis.

Enola therefore begins with a typed architectural fact model.

Parsing gives us evidence, not architecture

A parser can tell us that a function call, string literal, import, annotation, or method declaration exists.

That is necessary, but it is not yet an architectural fact.

Consider a Go application:

api := router.PathPrefix("/api").Subrouter()
registerCourseRoutes(api)

Elsewhere:

func registerCourseRoutes(router *mux.Router) {
    router.HandleFunc("/courses", listCourses)
}

The parser can expose both string literals and both function calls.

The architectural fact is:

GET /api/courses
  -> handled_by listCourses

Producing that fact requires understanding the framework, how routers compose paths, and how values move through function calls.

The same problem appears in Spring annotations, Rails scopes, Axum routers, Next.js file conventions, generated clients, dependency-injection frameworks, and message-bus configuration.

Enola therefore separates parsing from architectural extraction:

Source code
    ↓
Language and framework interpretation
    ↓
Architectural facts

The parser provides syntax.

The extractor determines what the syntax means within the architecture.

Repository boundaries are extraction scopes

A Git repository is a convenient place to begin analysis.

It provides a source revision, configuration boundary, files, build metadata, and stable source locations.

But it is not necessarily a unit of architectural truth.

A monorepo may contain several independently deployed services. A small repository may depend on schemas, infrastructure, or generated clients maintained elsewhere. Runtime behavior may also depend on deployment configuration outside the application repository.

Enola therefore treats a repository as an independently addressable extraction scope.

Within that scope, Enola may establish facts such as:

Repository contains module
Module contains file
File declares symbol
Function calls function
Package imports package
Type implements interface
Route is handled by symbol
Producer publishes to topic

These facts remain useful even when no other repositories are loaded.

The scope gives each entity a local identity and provenance. It does not imply that the entire architecture is contained inside the repository.

That distinction matters because source ownership boundaries and architectural boundaries are rarely identical.

Different facts require different identity rules

There is no universal identifier that works for every architectural concept.

A symbol may require:

extraction scope;
language;
qualified name;
source location;
source revision.

An HTTP route may require:

method;
normalized path;
service context.

A gRPC method may require:

package;
service;
method.

A Kafka topic may require:

resolved topic name;
namespace or environment context.

This is why names alone are insufficient.

Two repositories may both contain UserDTO without referring to the same contract. Conversely, a Go type called PublicUser and a Swift type called ProfileResponse may represent two sides of the same API.

Enola keeps those entities separate until there is evidence establishing a relationship between them.

Typed relationships preserve the reason two things are connected

A generic graph might represent:

A -> B

But architectural analysis needs to know why that edge exists.

Compare:

CheckoutController
  -> calls PaymentService.authorize

checkout
  -> imports payments

POST /checkout
  -> handled_by CheckoutController

These relationships support different questions.

A call edge may be useful for reachability.

An import edge may be useful for dependency-cycle detection.

A route-to-handler edge may be useful for tracing request execution.

Direction matters as well. A client consumes a route. The route does not consume the client.

Enola therefore represents relationships as typed and directed facts rather than generic connectivity.

That still does not make every extracted edge equally strong.

A relationship should also retain the evidence used to produce it, including:

source locations;
extractor;
resolution method;
source revision;
configuration;
whether it was directly extracted or derived.

Without that evidence, the graph becomes another opaque answer.

One model, several analysis projections

The complete fact model contains more relationships than any single analysis should traverse.

The question determines which subset is relevant.

For package-cycle detection:

Nodes: packages
Edges: package dependencies

For symbol reachability:

Nodes: symbols
Edges: calls and references

For route execution:

Nodes: routes, handlers, services
Edges: handled_by and calls

This matters because using every available edge can produce technically connected but architecturally meaningless paths.

Suppose a type belongs to a package, that package depends on another package, and the second package contains an HTTP route.

There is a path through the full graph.

That does not mean the type participates in the route’s execution.

Enola therefore constructs constrained projections for specific analyses instead of treating every traversal as equivalent.

A concrete example: why a generic dependency graph fails

Consider a frontend and backend stored in the same monorepo.

The frontend imports an API client package:

web
  -> depends_on api-client

The backend imports a routing framework:

backend
  -> depends_on router

A conventional dependency graph correctly records both relationships.

But it cannot answer:

Which frontend method consumes POST /api/orders?

The answer requires several additional facts:

submitOrder
  -> makes_request POST /api/orders

POST /api/orders
  -> handled_by CreateOrderHandler

CreateOrderHandler
  -> calls OrderService.Create

The useful architectural path is not a package-dependency path.

It is a projection combining request, route, handler, and call relationships.

That is the reason Enola needs a typed architectural fact model rather than only a repository dependency graph.

The limit of the model

Enola constructs the architecture that can be established from the loaded source and configuration inputs.

It does not claim that source alone describes every aspect of a production system.

Deployment manifests, gateways, service meshes, runtime configuration, reflection, feature flags, and infrastructure may alter the architecture visible at runtime.

The model should therefore distinguish between:

established facts;
derived relationships;
unresolved relationships;
information outside the analyzed scope.

This is important for both developers and agents.

A missing edge does not always mean that no relationship exists. It may mean that the relevant source, configuration, or resolver was unavailable.

What comes next

A typed fact model can explain the architecture inside one extraction scope.

Production systems cross those scopes.

A mobile client calls a backend maintained elsewhere. A service publishes an event consumed by another repository. A generated client implements a contract defined in a separate codebase.

The next post will explain how Enola connects these independently extracted models without merging entities based on names or similarity alone.

Enola is open-source GitHub

Building Enola, Part 1: Why Deterministic Architecture Analysis Matters

Gert — Mon, 20 Jul 2026 19:19:58 +0000

This is the first post in a series about the engineering decisions behind Enola, an open-source architecture analyzer for developers and AI coding agents.

Open source: https://github.com/enola-labs/enola

We did not start Enola because we wanted to build infrastructure for AI coding agents.

We started it while building a golf platform that had grown across club management, memberships, learning, web, mobile, and backend services. Over time, it became increasingly difficult to tell what was still used, what had been abandoned, and what could be removed without breaking something elsewhere.

Tests helped, but they could not prove that an apparently unused API, type, or code path was not consumed by another repository, an older client, or a less obvious integration.

AI coding agents made the problem worse in a different way.

We already used architectural rules and fitness functions to keep generated code within the boundaries we had defined. But an agent could still duplicate an existing module, carry the pattern all the way up to a new API we never needed, and produce code that passed tests and respected every rule.

The implementation looked valid. The architecture remained compliant. The result was still unnecessary code and future maintenance.

What became difficult was not reviewing individual lines. It was knowing whether the agent had done exactly what we asked, whether it had quietly done more, and what that change had actually added to the system.

ASTs, language servers, and RAG provide the pieces

None of the foundations behind Enola were new.

Compilers already had ASTs. Language servers already exposed symbols, definitions, references, and type information. Static analysis tools already built call graphs and dependency graphs.

The industry did not lack parsers.

Once AI coding agents became popular, another pattern appeared everywhere: index files or symbols, add embeddings or search, retrieve relevant fragments, and let the agent work out the rest.

That is useful, but it is not the same as representing the architecture of a system.

An AST describes the syntax of a language. A language server understands code within the boundaries of the language and workspace it supports. A RAG system retrieves fragments that might be relevant to the question.

They provide the pieces. The agent still has to connect them.

Ask what will be affected by changing an API in a backend repository, and retrieval may return the route, handler, request type, client calls, documentation mentioning the endpoint, and similarly named types from other repositories.

The agent must determine whether a Swift model and a Go model represent the same contract, whether a TypeScript route is a proxy or an unrelated path, which direction the relationships go, and which results are noise.

That is no longer retrieval. It is architectural reconstruction.

Because the agent performs that reconstruction, the answer depends heavily on the agent itself. A stronger model may follow the chain correctly. A smaller one may stop early. One agent may inspect another repository; another may decide it already has enough context.

The same codebase and the same question can therefore produce different architectural conclusions.

For questions involving engineering judgment, that variation is expected.

For questions such as "what calls this?", "which repositories depend on this contract?", or "what became reachable after this change?", it should not be the default.

A codebase is a network of relationships

Source code is stored as files and directories, but architecture does not follow that shape.

A file can contain several unrelated symbols. A package can depend on another package without that relationship being obvious from the directory tree. Two repositories can be connected through an API, event, schema, generated client, route, or data model even though there is no direct import between them.

The useful representation is therefore not another collection of indexed files. It is a graph of explicit relationships.

Functions call other functions. Types reference other types. Packages depend on other packages. Interfaces are implemented by concrete types. Routes connect handlers to application logic. Clients in one repository consume contracts exposed by another.

The important part is not merely extracting those relationships. Individual tools already do that.

The difficult part is combining them into a consistent architectural model across languages, frameworks, and repositories.

A route in Go does not look like a route in TypeScript. A controller in Java is not represented like an endpoint in Swift. The same name may refer to different concepts in different repositories, while two differently named types may represent the same contract.

Placing every AST node into a graph does not solve that problem. Neither does embedding every symbol and asking an agent to infer what the graph probably means.

The relationships need to be discovered, typed, directed, normalised, and connected in a way that remains useful beyond the parser that produced them.

Deterministic where possible

Not every fact in software can be established with complete certainty.

Dynamic dispatch, reflection, configuration, generated code, runtime dependency injection, and external systems all introduce ambiguity. Any tool claiming to understand every possible relationship perfectly would be overstating what static analysis can do.

But a large part of a system’s structure can still be established deterministically, or represented together with the evidence used to infer it.

A symbol is defined in a particular place. An import exists. A function contains a call. A route is registered. A type implements an interface. A client references a path. A package depends on another package.

Enola starts from those facts, then uses language and framework specific analysis to connect them into a broader model.

The purpose is not to remove reasoning from software engineering. It is to stop spending probabilistic reasoning on facts that can be extracted more reliably.

Facts first, reasoning second

There are questions where we want the agent’s judgment:

Should this interface change?
Is this design maintainable?
What is the safest migration path?
Should this dependency be removed?
Is the architectural impact acceptable?

And there are questions that should begin with evidence:

Which symbols exist?
What references them?
Which functions call them?
Which packages depend on each other?
Which relationships cross repository boundaries?
What was added or removed by this change?
What is reachable from this entry point?

An agent can reason much better about the first category when it does not have to reconstruct the second category every time.

This is also where the value goes beyond saving tokens.

A smaller model can work with the same architectural facts as a larger one. Different agents can begin from the same representation of the system. A result does not depend entirely on whether one particular agent happened to search the correct files in the correct order.

The reasoning may still differ.

The underlying architecture should not.

The architectural model becomes a DSL

There is another useful way to look at Enola’s output.

The files Enola generates under .enola are not ordinary documentation, source-code summaries, or chunks prepared for retrieval. Together, they form a domain-specific language for describing the architecture of a software system.

Their vocabulary is intentionally narrower than the vocabulary of the source code itself. They describe architectural concepts such as repositories, modules, symbols, relationships, routes, calls, dependencies, and cross-repository connections without requiring every consumer to parse every language and framework again.

This closely matches the argument Unmesh Joshi makes in DSLs Enable Reliable Use of LLMs. The article describes how a constrained semantic model and domain-specific vocabulary can reduce the number of possible interpretations available to an LLM, while deterministic tooling around the DSL can provide a harness for validating what the model produces. It also argues that, once a suitable abstraction exists, an LLM can act as a natural-language interface to it rather than inventing the domain model from scratch.

Enola applies a related idea to software architecture, although the direction is different from a DSL primarily intended for code generation.

It starts with general-purpose source code written across different languages and frameworks, analyzes it, and produces a constrained architectural representation. Developers and agents can then query that representation without reconstructing the underlying architecture from raw source files each time.

The .enola files become a shared vocabulary between the codebase, Enola, developers, and coding agents.

Instead of asking the agent to determine what a Go route, a Swift client, a TypeScript type, and a Java handler might collectively mean, Enola maps them into architectural concepts and relationships first. The agent reasons over a smaller and more explicit domain.

This does not make the model infallible, and it does not turn every architectural question into a deterministic one. But it changes where uncertainty begins.

The extraction and representation of the architecture happen before the agent starts reasoning. Different agents can therefore consume the same architectural DSL, even when their ability to independently search and understand a large multi-repository codebase differs significantly.

The enduring artifact is not the prompt that asked an agent to investigate the system. It is the architectural model extracted from the code.

From repositories to an architectural graph

This deterministic architectural model, and the DSL used to expose it, became the foundation of Enola.

Enola analyzes source code, extracts symbols and relationships within repositories, normalises them into a common representation, and connects repositories where the code provides evidence of a relationship.

The result is not just an index of files, a symbol database, or a collection of disconnected repository graphs.

It is an architectural graph that can represent relationships both inside a repository and across repository boundaries.

Depending on the language and framework, Enola can identify information such as:

Symbol definitions and references
Function and method calls
Type and interface relationships
Module and package dependencies
Routes and handlers
Architectural boundaries
Cross-repository relationships
Change-impact paths

This model can be queried directly by developers or exposed to AI coding agents through MCP.

Enola does not replace ASTs, language servers, search, or coding agents. It uses similar underlying sources of structural information but solves a different problem: turning language- and repository-specific facts into a system-level architectural model.

It also does not make architectural decisions on behalf of the agent. It gives the agent a more reliable representation of the system on which to base those decisions.

Enola is not primarily a visualization tool either. Its data can be used by agents or other tools to generate diagrams, reports, and visualizations, but its core responsibility is extracting, normalising, and connecting the underlying architectural facts.

Why this matters more as systems grow

For a small repository, repeated searching and local code navigation may be enough.

As a system grows across languages, frameworks, services, and repositories, the cost of reconstructing its architecture rises quickly.

The agent must understand that a route in Go, a controller in Java, an endpoint in TypeScript, and a client call in Swift may be parts of the same architectural path, even though they are represented differently in code.

It also has to distinguish between things that share a name but not a meaning.

A UserDTO in one repository may not be identical to a UserDTO in another. Two services may use different representations of the same business concept. A cross-repository connection may exist through an HTTP contract, event, generated client, or schema rather than a direct code reference.

This is where architecture analysis becomes more than parsing syntax, running a language server, or putting embeddings on top of symbols.

The difficult part is building a model that preserves the meaning and direction of relationships across the entire system.

That is the problem Enola is being built to solve.

What comes next

This article explains why deterministic architecture analysis is the starting point.

The next post will look at how Enola represents software as a graph of graphs: why repository-level graphs are not enough, how cross-repository relationships are discovered, and why seemingly identical concepts can mean different things across languages and frameworks.

We are building Enola in the open and will continue documenting the engineering decisions, trade-offs, and mistakes behind it as the project develops.

enola-labs / enola

Architecture intelligence for developers, coding agents, and CI - understand codebases, analyze change impact, and catch architectural regressions.

enola — architectural regression testing for AI-assisted development

The quality gate every agentic loop is missing.

enola gives your agent the real architecture before it writes a line, then grades what it built and returns that verdict, so it fixes its own regression before calling the job done. Every finding comes from a real parser and a graph algorithm, never a model's guess.

AI agents can write more code than you can carefully review. Tests check that behaviour still works. Linters check that style rules are followed. Neither checks whether the structure of the code still makes sense — whether the change coupled two modules that had no business knowing about each other, or closed a dependency loop (a circular dependency). That usually surfaces in review, if someone catches it, or months later when the package is too tangled to refactor.

enola checks structure while the change is still easy…

View on GitHub