Tecton: Architecture-as-Code and Quality Gates for Enterprise Architecture

Source code — https://github.com/senssei/tecton

Over the last few months I wrote a lot about local LLMs, GPUs and benchmarks. This post is about something different, and a bit closer to my day job: enterprise architecture.

Here is a thing that has bothered me for years. We version our code. We version our infrastructure (Terraform, Helm). We version our pipelines. We review all of it in pull requests, and CI refuses to merge it when it is broken.

And the architecture? The model of what systems we have, who owns them, what technologies they run on and what depends on what? That usually lives in a SaaS portal, edited by two or three people, with no review, no diff and no tests.

So I built Tecton.

Gray building during daytime Photo by Jean-Philippe Delberghe / Unsplash

The Paradox of the Closed EAM Repository

Classic EAM tools are good at one thing: showing pretty pictures to people who click around in a browser. Those pictures are generated by analytics — TIME quadrants, redundancy matrices, technology risk heatmaps.

The problem is that the analytics live in the front-end. The API gives you passive CRUD over entities and relations:

┌────────────────────────────────────────────────────────────────────────┐
│                     THE CLOSED EAM REPOSITORY PARADOX                  │
├──────────────────────────────────┬─────────────────────────────────────┤
│ What the Web UI displays:        │ What the programmatic API provides: │
│ • Intelligent TIME scoring       │ • Passive storage of entities/fields│
│ • Graphical redundancy matrices  │ • Zero embedded analytical engines  │
│ • Cascading technology risks     │ • No risk propagation calculations  │
│ • Capability trees with roll-up  │ • Flat lists without aggregation    │
└──────────────────────────────────┴─────────────────────────────────────┘

Want to fail a build because a service depends on a technology that reached end-of-life last quarter? You can’t. The insight is trapped in a browser tab, and the in-portal scripting usually comes with limits like 5 seconds of runtime and 256 MB of RAM. Good luck running graph analytics over thousands of components in that.

What is Tecton?

Tecton is a deterministic, offline-first Enterprise Architecture Intelligence Engine written in Python. It reads architecture described as YAML files in a Git repository (a C4-extended DSL), builds a graph in memory and runs pure, reproducible engines on top of it.

flowchart LR
    A["<b>Git repo (YAML)</b><br/>capabilities.yaml<br/>systems.yaml<br/>components.yaml<br/>technologies.yaml<br/>relationships.yaml"]
    B["<b>Tecton</b><br/>DSL parser + linter<br/>TIME / Redundancy / Lifecycle<br/>BCM / TRM engines<br/>Semantic diff<br/>Exporters + connectors"]
    C["<b>Consumers</b><br/>CI quality gate (exit 0/1)<br/>PR review comment<br/>Mermaid + Markdown<br/>Read-only web portal<br/>ArchiMate / Backstage"]
    A --> B --> C

The design principles are boring on purpose:

Deterministic. Same input, same output — on my laptop, in CI, anywhere. No LLM, no network, no randomness in the engines.
Offline-first. No SaaS, no account, no vendor lock-in.
Hexagonal. Pure domain core, adapters at the edges. I enforce the boundaries with an architecture test, which feels fitting for a tool that enforces architecture.
Safe by default. Anything that mutates something runs as a dry-run unless you say otherwise.

Every one of those is written down as an ADR in docs/adr/. If you read my older posts, you know I like writing down why.

The Quality Gate

This is the part I use the most. tecton validate is a linter for your architecture graph:

# referential integrity, cycles, lifecycle violations
tecton validate examples/c4_eam_workspace

# zero-warning policy — exit code 1 on any warning
tecton validate --strict examples/c4_eam_workspace

# machine-readable report for CI
tecton validate --format json examples/c4_eam_workspace

What does it catch? The same class of bugs you know from code:

Architecture bug	Code equivalent
Relationship pointing to a system that doesn’t exist	Dangling pointer
Circular dependency between components	Import cycle
Application in `active` phase with an `endOfLife` date in the past	Using a removed API
System without an owner	Orphaned module

Running it against Tecton’s own model:

Tecton Architecture Quality Gate & Graph Linter
Scanning directory: examples/dogfood/tecton_c4_workspace
(5 files, 10 capabilities, 1 systems, 15 containers, 9 relationships, 6 technologies)

✓ Architecture valid. No referential integrity errors, cycles, or lifecycle violations.

Semantic Diff — the Killer Feature

A text diff of two YAML files tells you which lines changed. It does not tell you that you just orphaned a business capability.

# compare two Git revisions
tecton diff main HEAD

# render it as a pull-request comment
tecton diff main HEAD --format pr-comment -o pr_review.md

# fail the build if the change makes the architecture worse
tecton diff main HEAD --fail-on-risk

tecton diff compares the graphs, not the files. Added a system but mapped it to no capability? Removed a component that three others depend on? Introduced a breaking regression? It tells you, in the PR, before anyone merges.

That is the moment architecture stops being a document and starts being a reviewable change.

The Engines

Beyond linting, Tecton ships a set of analytic engines — the stuff normally hidden in a portal UI:

TIME classifier — places applications into Gartner’s Tolerate / Invest / Migrate / Eliminate quadrants from functional and technical fit scores, using configurable thresholds.
Redundancy detector — finds overlapping systems using weighted Jaccard similarity across capabilities and user groups:

J(A₁, A₂) = w_c · |C₁ ∩ C₂| / |C₁ ∪ C₂| + w_u · |U₁ ∩ U₂| / |U₁ ∪ U₂|
Capability roll-up (BCM) — aggregates cost, maturity and risk up the capability tree with a post-order traversal, and shows capabilities that nothing realizes.
Technology risk & blast radius (TRM) — pick an obsolete technology and see the direct and transitive set of things that break when it goes away:

tecton trm blast-radius tech-legacy-solaris --source examples/c4_eam_workspace

Data lineage — trace a business data object across producers and consumers, with privacy classifications (GDPR/PII/PCI-DSS) along the way.
Roadmaps — plateaus (As-Is → transitional → To-Be), work packages and Gantt export.

Everything exports as living documentation — Mermaid quadrant charts, flowcharts and Gantt diagrams, plus Markdown reports you can commit next to the code:

tecton apm export-matrix --source examples/c4_eam_workspace --format mermaid
tecton bcm heatmap --source examples/c4_eam_workspace
tecton roadmap export-gantt --source examples/c4_eam_workspace

And there’s a read-only web portal (tecton portal / tecton export portal) if somebody insists on clicking.

Not Another Island: ArchiMate and Backstage

I don’t believe in replacing every tool in a company with mine. So Tecton talks to the ecosystem:

tecton export backstage --source ws -o catalog-info.yaml
tecton export archimate --source ws -o model.xml

tecton import backstage catalog-info.yaml -o imported_workspace/
tecton import archimate model.xml -o imported_workspace/

Round-trips preserve domain IDs, and the ArchiMate Open Exchange export passes strict XSD validation (that was a fun afternoon with xsi:type attributes I’d rather not relive). The Archi exports also come with generated default diagram views, so you open the file and see something instead of a blank canvas.

Dogfooding: Tecton Describes Tecton

The obvious test for an architecture tool is whether it can describe itself. examples/dogfood/tecton_c4_workspace is Tecton’s own architecture: one software system (sys-tecton) with 15 child components, and the technologies they run on.

On GitHub, a workflow called EAM pilot catalog runs on every pull request and on the merge queue:

tecton validate ... --require-owner on the merged result
the pilot scenario tests (add a component, change an owner, remove a component together with its relationship)
a build of the read-only portal as a CI artifact

If I add a component and forget an owner or leave a dangling relationship, my own PR is red. It is very humbling to be blocked by your own linter.

The test suite is 136 tests, 100% offline, and runs in about 3 seconds.

What Tecton Is Not (Yet)

I’d rather be upfront about the limits:

It’s a pilot. The Git-backed catalog is tested on Tecton itself. Whether Git should become an organization’s system of record for EAM is an open question, and it needs a real business-domain pilot, with real architects and real merge conflicts, before I’d claim anything.
No discovery, no sync, no editing forms. Models are YAML, changed through pull requests. That’s the point — but it’s also a barrier for non-engineers.
The portal isn’t fully offline. Its styling and Mermaid diagrams are loaded from a CDN.
Branch protection isn’t in the repo. Requiring the check, an approval from someone other than the author and a merge queue are GitHub settings. A workflow file can’t enforce them.

Try It

git clone https://github.com/senssei/tecton
cd tecton
uv venv .venv && source .venv/bin/activate
uv pip install -e ".[dev]"

tecton validate examples/dogfood/tecton_c4_workspace --require-owner
tecton apm analyze --source examples/dogfood/tecton_c4_workspace
tecton portal --source examples/c4_eam_workspace

If you work with enterprise or solution architecture and ever thought “why is this not in a pull request?” — I’d really like to hear what breaks first when you point it at your own landscape.

GitHub: https://github.com/senssei/tecton
Docs: docs/ in the repo — start with the product vision and the ADRs