Forem: Agustín Abero

Mapping the Territory

Agustín Abero — Mon, 09 Mar 2026 13:07:12 +0000

We thought the "Multi-Repo Verse" would save us from spaghetti code. Instead, we traded a tangled web of single files for a labyrinth of repositories, modules, and remote state. The boundaries were supposed to give us clarity, but suddenly, understanding a single depends_on rule became an archaeological dig through half a dozen browser tabs. The code was perfectly structured, but the reality was invisible.

A quick recap

In Part 1 of the "Making Invisible Infrastructure Visible" series, I talked about "The Fog of Code": that overwhelming anxiety of flying blind when making changes to modern, distributed infrastructure. Tab Fatigue is real. The fear of the Butterfly Effect is real.

To stop flying blind, I needed a map. Not just a text search across repositories, but a true semantic map of the territory. I needed to turn static syntax into a dynamic, queryable reality.

Here is exactly how I built the foundation of Infra-Graph to do just that.

The harsh reality of parsing HCL

When I first sat down to solve this, the plan felt straightforward: parse the .tf files, find the references, and draw the lines.

Then I actually looked at the Abstract Syntax Tree (AST).

You open a file and see a seemingly simple string: depends_on = [aws_security_group.web.id]. But to a machine, that’s just text. To build a visualization tool, you have to map every variable, module output, and resource attribute into a rigid, structured schema.

I started using python-hcl2 to turn .tf files into Python dictionaries. For simple files, it worked beautifully. But real-world infrastructure isn't simple. When dealing with nested module calls, interpolations, and dynamic blocks, regex fails spectacularly. The AST is a deeply nested, unforgiving nightmare of dictionaries and lists.

To give you an idea of what I was looking at, a simple 6-line resource block like this:

resource "aws_lb" "main" {
  name               = "${var.project_name}-alb-${var.environment}"
  internal           = false
  load_balancer_type = "application"
  security_groups    = [aws_security_group.alb.id]
  subnets            = [aws_subnet.public.id]
}

...becomes this deeply nested list-of-dictionaries format in python-hcl2:

{
  "resource": [
    {
      "aws_lb": {
        "main": {
          "name": "${var.project_name}-alb-${var.environment}",
          "internal": false,
          "load_balancer_type": "application",
          "security_groups": [
            "${aws_security_group.alb.id}"
          ],
          "subnets": [
            "${aws_subnet.public.id}"
          ]
        }
      }
    }
  ]
}

The realization hit hard: translating disjointed, human-written infrastructure code into a rigid database schema wasn't going to be a quick hack. It was going to be technical trench warfare.

Designing the Schema

To map the territory, I needed a database that understood relationships natively. Relational databases, with their rigid tables and expensive JOINs, were the wrong tool for a system defined by its interconnectedness. I chose Neo4j because it is built from the ground up for graph traversal, allowing me to naturally model and query recursive dependencies like depends_on chains without writing thousands of lines of SQL CTEs.

I designed the graph schema around three core Neo4j entities:

Nodes: These represent the blocks of HCL.
- A Resource (e.g., aws_instance) uniquely identified by its file_path and logical_name.
- A Module uniquely identified by its module_id.
- Variable and Provider nodes.
Properties: The metadata attached to nodes, housing the actual configuration (names, files, line numbers, and AWS-specific attributes).
Relationships: This is the wiring:
- [:DEPENDS_ON] connects explicit resource references.
- [:USES_VAR] connects resources and modules to the variables they consume.
- [:CONTAINS] links modules to their internal components.

// The explicit wiring of the Multi-Repo Verse
(:Module {id: "vpc"})-[:CONTAINS]->(:Resource {type: "aws_subnet", name: "main"})
(:Resource {type: "aws_subnet"})-[:USES_VAR]->(:Variable {name: "region"})
(:Resource {type: "aws_instance"})-[:DEPENDS_ON]->(:Resource {type: "aws_security_group"})
(:Resource {type: "aws_instance"})-[:PROVIDED_BY]->(:Provider {name: "aws"})

It looks clean on a whiteboard. In practice, it required an intense normalization logic (an internal mapping script) to flatten the chaotic HCL dictionaries into clean, standardized dataclasses before they ever touched the database.

The Mechanical Grind

Populating the graph brought its own set of friction. It wasn't enough to just CREATE nodes. If you run a scan twice, you don't want a duplicated infrastructure graph.

Writing the Cypher ingestion queries was an exercise in idempotency. I lived and breathed the MERGE clause, ensuring the graph updated existing nodes rather than cloning them. I batched transactions to handle hundreds of resources without locking up the database.

MATCH (source:Resource {id: $sid})
MATCH (target:Resource {type: $ttype, name: $tname})
MERGE (source)-[:DEPENDS_ON]->(target)

It was a mechanical, unglamorous grind. Traversing the ASTs, writing the parsing logic, and meticulously wiring the explicit pointers across files felt farther from "saving DevOps" than I had hoped. I was just moving data from text files into a graph.

Connecting the Dots

And then came the moment that made it all worth it.

After days of wrestling with dictionaries and Cypher queries, I wrapped the Neo4j database with a FastAPI backend and built an interactive Angular frontend using D3.js.

I pointed the parser at a sprawling, complex Terraform directory, the kind that normally requires six open editor windows to mentally model, and initiated the first full infrastructure scan.

When the web interface finally rendered, the result was immediate. The unreadable chaos of HCL text files organized itself into a clear visual model. The nodes snapped into a physics-based, force-directed graph. Solid lines perfectly connected the explicit depends_on rules, variable references, and module outputs.

Selecting a node instantly populated the sidebar with its exact configuration, pulling its properties directly from the local Neo4j instance.

The "Tab Fatigue" vanished. The sprawling "Multi-Repo Verse" was no longer an invisible labyrinth; it was a single, zoomable UI. I could trace an interconnected path from an API Gateway to a subnet, without opening a single text file.

I had mapped the territory.

But as I stared at the perfect structural map, I realized something was missing. The map only showed what was written. It didn't show what it was meant. It didn't connect a security group port 80 to the load balancer that implicitly relied on it. It was strictly explicit.

Next up in Part 3: how I integrated local AI to discover the hidden truth.

Making Invisible Infrastructure Visible series index

The Oracle

Agustín Abero — Thu, 05 Mar 2026 02:57:45 +0000

I thought I was done. After days of wrestling with Neo4j and flattening deeply nested Terraform ASTs, I finally had a beautiful, physics-based graph of my entire infrastructure. It was a masterpiece of explicit dependencies. But when I looked at the graph and asked myself a simple question: Is my database actually exposed to the internet? My masterpiece couldn't show me the answer. It just stared silently back at me, rendering explicit syntax while missing the semantic truth.

I had built a perfect map of my code, but code is not reality.

A quick recap

In Part 1, I talked about that overwhelming anxiety of flying blind when making changes to modern, distributed infrastructure. Tab Fatigue is real. The fear of the Butterfly Effect is real. To stop flying blind, I needed a map. In Part 2, I showed you how I built that map. I created a Terraform parser that flattens deeply nested ASTs into a clean, normalized JSON format. I then imported that data into Neo4j, creating a physics-based graph where every resource is a node and every dependency is an edge and built a D3.js frontend that renders this graph in real-time, allowing me to visually trace connections across repositories and services.

It was beautiful. It was explicit. And it was incomplete.

The Limits of the "Perfect" Graph

My Neo4j graph meticulously plotted every depends_on block and every explicitly passed variable. If an ECS task definition referenced a specific Subnet ID, the D3.js frontend drew a solid, satisfying line between them. But modern infrastructure is defined just as much by what isn't explicitly linked.

When I configure a Security Group to allow inbound traffic on port 80, I am implicitly connecting it to a Load Balancer or a web server. To a human engineer, that dependency is obvious:

resource "aws_security_group" "alb" {
  name        = "${var.project_name}-alb-sg"
  description = "Controls access to the ALB"
  vpc_id      = aws_vpc.main.id

  ingress {
    protocol    = "tcp"
    from_port   = 80
    to_port     = 80
    cidr_blocks = ["0.0.0.0/0"]
  }

  egress {
    protocol    = "-1"
    from_port   = 0
    to_port     = 0
    cidr_blocks = ["0.0.0.0/0"]
  }
}

resource "aws_lb" "main" {
  name               = "${var.project_name}-alb-${var.environment}"
  internal           = false
  load_balancer_type = "application"
  security_groups    = [aws_security_group.alb.id]
  subnets            = [aws_subnet.public.id]
}

resource "aws_lb_target_group" "app" {
  name        = "${var.project_name}-tg"
  port        = 80
  protocol    = "HTTP"
  vpc_id      = aws_vpc.main.id
  target_type = "ip"

  health_check {
    path = "/health"
  }
}

resource "aws_lb_listener" "front_end" {
  load_balancer_arn = aws_lb.main.arn
  port              = "80"
  protocol          = "HTTP"

  default_action {
    type             = "forward"
    target_group_arn = aws_lb_target_group.app.arn
  }
}

To my parser, they were just two isolated nodes floating in the void. An explicit map could tell me the database existed, but it couldn't trace the complex web of routing tables, internet gateways, and security groups to tell me if that database was bleeding data to the public internet.

The frustration hit hard. I didn't just want to look at my infrastructure; I wanted to understand it. I realized that if I wanted answers to the richest, most critical questions, I couldn't just stare at a static map. Who better to explain the infrastructure to me than the infrastructure itself? What if I could talk to it?

The structural map was built, but it needed an intelligence layer. It needed an Oracle.

Building the Oracle

To build this intelligence layer, I knew I needed an LLM capable of deep semantic reasoning. But I also knew it had to be completely local. The entire point of Infra-Graph is sovereign visibility. I wasn't about to start piping my infrastructure blueprints to a third-party API, at least not yet. So, I integrated Ollama running Llama 3 locally.

First, I tasked the LLM with uncovering the hidden semantic reality. I built an async pipeline that fed isolated resources to the model. Suddenly, the graph woke up. Dotted lines appeared in the UI.

The AI recognized that an IAM policy granting s3:GetObject implied a dependency on a storage bucket. It saw the port 80 ingress rule and confidently drew an inferred connection to the Load Balancer. It was finding the silent links that regex could never catch.

But finding the links wasn't enough. I wanted to ask questions.

I built a conversational interface (a GraphRAG chatbot) directly into the UI. Now, when I asked, "Is my database exposed to the internet?", the system didn't just regurgitate text. It traversed the actual Neo4j graph, pulling the database, the attached security groups, the subnets, and the route tables into a tight, 1-hop context window. It fed that grounded, topological reality to the Llama 3 model.

Because the LLM was grounded in the graph, hallucinations dropped to near-zero. It returned a precise, accurate answer, identifying the exact security group rule and trailing route that caused the exposure, along with actionable recommendations and security best practices to remediate it.

I no longer just had a map. I had an interactive test environment. Before I even ran a terraform plan, I could ask my infrastructure: "If I delete this Security Group, what breaks down?" and get a deterministic answer translated into plain English.

The "Multi-Repo Verse" was no longer a silent, anxiety-inducing labyrinth. I could finally converse with my infrastructure code, and testing configurations became as simple as asking a question.

It's easy to trust the output of a terraform plan to tell the whole story. But building the map and integrating the Oracle showed me that details are often hidden between the lines. What did I learned about the semantics of infrastructure code? What did this experiment in local, conversational infrastructure actually teach me about how we design and manage systems?

Next up in Part 4: we'll explore the practical lessons learned from this journey and discuss the real value of visual sovereignty.

Making Invisible Infrastructure Visible series index

The Fog of Code

Agustín Abero — Thu, 05 Mar 2026 02:51:35 +0000

It starts with a simple question about a single Terraform variable. Soon, you're chasing configurations across dozens of browser tabs and scattered IDE folders, desperately trying to understand the reality of your infrastructure. You are flying blind in the 'Multi-Repo Verse,' and just when you think you've found a lifeline, you realize your AI copilot is confidently feeding you the wrong information.

Making Invisible Infrastructure Visible series introduction

This post is Part 1 of the "Making Invisible Infrastructure Visible" series. Over the next four posts, I will explore the complexity of managing large single or multi-repo Terraform coded infrastructure, the limitations of current tooling, and how I built Infra-Graph, a local-first, AI-powered mapping tool, to bridge the gap between static code and its hidden semantic meaning. If you manage Terraform across multiple repositories, this series is for you.

Navigating the Fog of Code

We’ve all been there. You open your IDE to make what should be a straightforward change: perhaps adjusting an ingress rule on an AWS Security Group. But in modern infrastructure, nothing exists in isolation.

You find the resource block, but the security group ID is passed as a variable. You follow the variable to a terraform.tfvars file, only to realize the actual value is sourced from a remote state data block defined in an entirely different repository. This is the reality of the "Multi-Repo Verse." It’s an architectural pattern designed to enforce boundaries, but the operational reality is a labyrinth.

Within ten minutes, your screen is an overwhelming mosaic of browser tabs, GitHub search results, and overlapping VS Code workspaces. This phenomenon isn't just "context switching", it's Tab Fatigue. It’s the mental exhaustion of trying to hold an entire, fragmented infrastructure state in your short-term memory. And beneath that exhaustion lies a deeper professional anxiety: the fear of the "Butterfly Effect."

Every time you type terraform apply, you brace yourself. If I change this output here, what downstream service in another repository am I going to break? The check-in culture has given us version control, but it has hidden the semantic reality of our infrastructure behind walls of distributed text files. You are an architect, expected to design resilient systems, but on a daily basis, you are flying blind.

So, you do what any modern developer does: you reach for an AI copilot. You paste snippets of your .tf files into the prompt, or maybe you even rely on an advanced copilot with repository-wide visibility, asking, "Is it safe to remove port 80?"

The AI responds immediately, with perfect grammar and absolute confidence. It explains why the change is safe, analyzing the code it has access to. For a brief second, you feel relief.

Then comes the Reality Check.

You realize the AI didn't, couldn't, know about the undocumented legacy load balancer defined in a separate AWS account's repository that relies on that exact port. The AI wasn't helping; it was hallucinating. It was telling you a beautiful, dangerous lie because it lacked the one thing that matters in infrastructure: grounded truth.

LLMs are powerful reasoning engines, but when fed fragmented text files, they are just creative guessers.

"They understand syntax, but they don't understand meaning."

They don't know that an open port implicitly connects two disparate resources.

That was the turning point. I realized that if I wanted to stop flying blind, and if I wanted to actually harness AI without the risk of taking down production, I didn't need a better prompt. I needed a better map. I needed a way to ground the AI, and myself, in the actual reality of the infrastructure.

In short, I needed a semantic map. In the next post, I will show you exactly what that map looks like and why it changes everything.

Next up in Part 2: how I mapped the terraform infrastructure territory, or so I thought...