DEV Community: Raj Navakoti

Work on the Circuit Board, Don't Box It Yet

Raj Navakoti — Tue, 14 Apr 2026 14:57:06 +0000

Your multi-agent system isn't ready for a UI. And that's fine.

The Temptation

Every enterprise I've seen in the last 18 months does the same thing: they build an agent, it works in a prototype, and immediately someone says "let's make this an app." A nice UI, a button, maybe some charts. Box it up, hand it to users, move on.

I get it. There's a product manager somewhere who just watched the demo and their eyes lit up. "Can we put this in front of customers by Q3?" And the engineer who built it feels the pull too — a polished app feels like real work, a terminal feels like hacking.

But multi-agent orchestration is still in the circuit board stage. And boxing a circuit board is how you kill trust in AI across your entire organisation.

What a Circuit Board Looks Like

I run 17 projects with AI agents. Not through apps. Through terminal sessions and tmux panes.

Here's what a typical multi-agent session looks like on my screen:

┌─────────────────────────┬──────────────────────────┐
│ Agent: Architect        │ Agent: Code Reviewer     │
│                         │                          │
│ > Reading CLAUDE.md...  │ > Waiting for PR...      │
│ > Found 3 context files │ >                        │
│ > Reasoning: "The API   │ >                        │
│   contract suggests     │ >                        │
│   this is a bounded     │ >                        │
│   context for orders,   │ >                        │
│   not fulfillment"      │ >                        │
│ > Tool call: Read       │ >                        │
│   /models/order.yaml    │ >                        │
│ > ...                   │ >                        │
├─────────────────────────┴──────────────────────────┤
│ Orchestrator Log                                    │
│ 14:23:01 architect → code-reviewer: handoff         │
│ 14:23:01 context: 3 files, 2847 tokens              │
│ 14:23:02 code-reviewer: starting review...          │
└─────────────────────────────────────────────────────┘

It's ugly. It's not something you'd demo to a VP. But I can see everything:

What context the agent loaded
How it reasoned about the problem
When it handed off to another agent
What got passed in the handoff
Where it's stuck

That visibility is the entire point. Because agents fail — and right now, they fail in ways you need to see to fix.

The Failure Modes You Can't See Through a UI

Here's what actually goes wrong in multi-agent systems:

The wrong tool call. Agent picks search_confluence when it should have picked read_api_contract. Through a UI, you see a bad answer. Through the circuit board, you see exactly which tool was selected and why — and you fix the tool selection logic.

The handoff fumble. Agent A passes context to Agent B, but drops a critical piece. The user sees a weird response. You see... nothing, because the UI doesn't show inter-agent communication. On the circuit board, the handoff is logged line by line.

The infinite loop. Agent asks for clarification, gets a response, asks for clarification again, gets the same response, asks again. Through a UI, the spinner just keeps spinning. Through tmux, you see the loop happening in real time and kill it at iteration 3, not iteration 47.

The confidence problem. Agent is 30% confident in its answer but presents it with 100% certainty. The UI shows a clean response. The circuit board shows the reasoning chain that led there — and you see the hedging, the contradictions, the "I'm not sure about this but..."

Every one of these is a real failure I've hit in the last six months. Every one of them was caught because I could see the circuit board. None of them would have been visible through a dashboard.

"But Our Users Need an App"

I hear this constantly. And the answer is: which users?

Power users and engineers should be on the circuit board. They're the ones who can spot failures, provide feedback, and help the system improve. Give them terminal access, tmux sessions, or at minimum a verbose logging view. They'll love it — it's like having X-ray vision into the AI's brain.

Business users are a different story. They need something simpler. But "simpler" doesn't mean "a polished app." It means a carefully constrained interface for a narrow, proven workflow.

The mistake is jumping from "prototype works in terminal" straight to "let's build a full app for everyone." There's a middle ground:

STAGE 1: Circuit Board
  Who: Engineers, power users
  Interface: Terminal / tmux
  Goal: Find failure patterns, refine agents
  Duration: Weeks to months

STAGE 2: Guided Circuit Board
  Who: Technical users, early adopters
  Interface: Simple web UI with visible reasoning
  Goal: Validate with real workflows, broader feedback
  Duration: Weeks

STAGE 3: Protective Case
  Who: Business users, general audience
  Interface: Polished app with "inspect reasoning" option
  Goal: Production use
  Prerequisite: Reliability metrics from Stage 1-2

Most enterprises try to skip to Stage 3. They end up back at Stage 1 anyway — just with more sunk cost and more disappointed users.

The Maturity Test

How do you know when an agent workflow is ready to graduate from circuit board to boxed app? Here's the checklist I use:

[ ] Agent succeeds on 90%+ of cases in its target domain
[ ] Failure modes are known and documented (not "it sometimes breaks")
[ ] Recovery from failure is automated or gracefully handled
[ ] Handoffs between agents are consistent and auditable
[ ] A non-engineer has used it successfully for 2+ weeks
[ ] You can explain every tool call the agent makes, not just the output
[ ] You've watched it fail and know exactly why each time

If you can't check all of these, you're not ready to box it. And that's fine. The circuit board isn't a limitation — it's where the learning happens.

What This Means for Your Enterprise

If you're building multi-agent systems right now, here's the practical takeaway:

Don't invest in agent UIs yet. Invest in observability. Build logging, tracing, and inspection tools. Make the circuit board visible and navigable. That's your competitive advantage — not a pretty dashboard.

Let engineers live in the terminal. The feedback loop from "I saw the agent fail" to "I fixed the prompt" is minutes in a terminal. It's days through a bug report from a UI.

Resist the demo pressure. When leadership asks for a demo, show them the tmux session. Explain what they're seeing. The honest demo — "here's the agent thinking, here's where it struggled, here's how we fixed it" — builds more trust than a polished UI that hides the mess.

Plan for the box, but don't build it yet. Know what the eventual app looks like. Design the API. Sketch the UI. But don't build it until the circuit board tells you it's ready.

One Takeaway

We're in the circuit board era of multi-agent AI. The agents work — sometimes brilliantly — but they fail in ways that require human eyes on the wiring. The enterprises that win won't be the ones that boxed it fastest. They'll be the ones that stayed on the circuit board longest, learned the failure patterns, and only boxed it when it was genuinely reliable.

Ship the circuit board. Let people see it work. The box can wait.

Are you boxing agents too early? Or have you found the right moment to graduate from terminal to app? I'm running 17 agent projects from tmux panes and I'm curious what's working for others at scale.

Contained Chaos: A Prototyping Operating Model for the AI Era

Raj Navakoti — Wed, 01 Apr 2026 16:13:17 +0000

Your enterprise has a prototyping problem. Not too little. Too much. Here's how to channel it.

The Fire Just Got More Fuel

Claude just announced 1 million token context. OpenAI keeps raising limits. Every month, the barrier to building something drops further. And the name of the fire this fuels isn't "AI adoption." It's prototyping.

I'm deliberately not calling this vibe-coding. Vibe-coding is one leg of a much bigger thing. Prototyping is what happens when AI tools get good enough that anyone — not just engineers — can translate an idea into something that works. Product managers are building internal tools. Designers are generating functional front-ends. Business analysts are wiring up data pipelines. The ability to prototype is no longer a technical skill. It's a social right.

And right now, people in your enterprise are prototyping like rats on cocaine.

I've seen it first-hand. Across a large enterprise with hundreds of engineering teams, I watched the prototyping volume go from "a few side projects" to "we genuinely don't know how many AI-powered tools people have built" in under a year. Not because anyone approved it. Because the tools got good enough and the problems were obvious enough that people just... started building.

The Two Choices (Both Wrong)

As an enterprise, you're staring at this and you have two instincts. Both are bad.

Choice 1: "If I don't look, it's not there."

The Ostrich. Head in the sand. Let people do whatever they want. Meanwhile, someone in a corner of your organisation has already solved a million-dollar problem and can't ship it because the PO told them the Jira ticket is the priority. Someone else, knowingly or unknowingly, just published confidential customer data to a public API because the prototype needed "real data to feel real."

You didn't see it. So it didn't happen. Until it did.

Choice 2: "I see you. All of you. All the time."

The Empire. Lock it down. Approved tools lists. Usage policies. Mandatory reviews. Kill every unsanctioned experiment before the ideas even seed. Congratulations — you've eliminated the security risk and the innovation at the same time. The Force is strong with governance, but the Rebellion has better ideas.

I watched an organisation do exactly this. They sent a company-wide email banning all "unapproved AI tool usage." Within a week, the same engineers were using the same tools — they'd just stopped talking about it. The prototyping didn't stop. The visibility did.

The Third Way

Is there a path where you channel this energy instead of ignoring it or crushing it? Where you turn contained chaos into enterprise value?

Yes. But before you say "you're a genius" — let's make sure you actually need this. Let's look at what you've probably already tried, and why it didn't work.

What You've Already Done (And Why It Didn't Work)

Hackathons.

Every enterprise's first move. Put people in a room for a day, high adrenaline, end-of-day presentations, a few standouts, investment promises from leadership, applause.

Next morning: new dawn, new day, back to the same work.

Hackathons are top-down events dressed up as bottom-up innovation. Most organisations run them for AI adoption and awareness, not for sustained value creation. They reward speed over substance. They produce demos, not products. And there's no path from "you won the hackathon" to "here's a team and a budget." Winning means a trophy, not traction.

The Death Star looked impressive too. Didn't survive contact with a thermal exhaust port.

Announcements and policies.

"Please be careful using unauthorised AI tools. Here are our data protection policies." Sent via email. Nobody reads it. The people who need it most are the ones who've already found their own tools and aren't looking at their inbox for permission.

AI awareness events.

Expensive. Low retention. The people who attend are already interested. The people who need it don't show up. I sat through one that cost more than a junior developer's annual salary. Three months later, I asked ten people what they remembered from it. Nobody could name a single takeaway.

AI governance and adoption teams.

They exist somewhere in your org chart. Most people don't know where. These teams do important work — tooling evaluation, risk assessment, vendor management — but they operate in the background. They're not connected to the people actually building things. I once asked a developer if they knew their company had an AI governance team. "We have a what?"

None of these are wrong. They're just incomplete. They address pieces of the problem but none of them answer the real question: how do you systematically absorb the prototyping energy and turn it into value?

The Prototyping Operating Model

Here's the model. Three parts: the system, the team, and the infrastructure.

Part 1: The System

A rolling submission model with quarterly selection.

Not a one-day event. Not "submit your ideas by Friday." A continuous, open pipeline where people prototype at their own pace and submit when they're ready.

Why rolling? Because good ideas don't arrive on schedule. The engineer who cracks a problem at 2am on a Tuesday shouldn't have to wait for the next hackathon to show anyone. And people should be able to submit as many ideas as they want — the evaluation process filters, not the submission process.

The submission rule: prototypes only.

This is the critical filter. And it's inspired by something Jeff Bezos understood early: the best way to evaluate an idea isn't to read a pitch deck about it — it's to use it.

Submissions are not ideas. If it's just a sketch on a napkin, it's too early — go build it first. Submissions are also not deployed projects. If it's already running in production, you've skipped the process entirely and we need a different conversation.

A submission is a prototype: an idea translated to a minimum working level. It runs. It demonstrates the concept. It's rough. That's fine. But it exists.

What a submission looks like:

Every submission is a pull request. The PR description follows a standardised template:

# Prototype Submission

> **Submission Title:** AI-Powered Inventory Alert System
> **Submitter:** Alex Chen / @achen
> **Date:** 2026-02-14
> **Category:** ai-ml

## Problem Statement
Our regional warehouse network (12 locations) relies on manual stock checks
and static reorder thresholds to manage inventory across 8,400 SKUs.
Warehouse coordinators spend 2-3 hours daily reviewing spreadsheets and ERP
dashboards to identify items approaching stockout.

## Dollar Value Framing
- **Value type:** Cost saving
- **Estimate:** $680,000/year
  - Stockout reduction: 340 events/quarter x 60% reduction x $320 avg
    emergency freight premium = $261,120/year
  - Labor savings: 12 coordinators x 1.5 hrs/day saved x 250 days x
    $48/hr = $216,000/year
- **Confidence level:** Medium

## Working Prototype
- **Link:** github.com/achen/inventory-alert
- **Tech stack:** Python, scikit-learn, PostgreSQL, Slack SDK, Streamlit
- **How to run it:** `docker compose up` → load data → train → dashboard

## Effort So Far
- **Time invested:** ~60 hours over 5 weekends
- **People involved:** Alex Chen (ML), Dana Torres (warehouse ops, domain)
- **What was hardest:** Demand signal for promotional periods — model
  treated promo spikes as anomalies, not patterns.

## What's Needed to Graduate
- **Team size:** 2 engineers + 1 ops lead for 3 months
- **Budget:** ~$85,000
- **Key risks:** ERP API access may require 6-8 week security review

Notice the structure. Dollar value framing forces people to think about whether the problem is worth solving before they submit. Effort transparency shows skin in the game. Graduation requirements keep expectations realistic. This isn't a wish list — it's an engineering proposal.

Quarterly evaluation and selection.

Every quarter, the organising team reviews all submissions from that cycle. Each submission gets scored against five criteria:

Criterion	Score	What It Measures
Business Value	/5	Real problem? Credible dollar framing?
Technical Feasibility	/5	Can this actually reach production?
Resource Efficiency	/5	Lean ask relative to value?
Strategic Alignment	/5	Fits org priorities?
Innovation Factor	/5	Novel approach or new-to-us?
Total	/25

The scoring isn't a beauty contest. It's a structured way to compare apples to oranges — an ML inventory system against a meeting decision recorder against a compliance automation tool. Every evaluator fills in the same template. Comments are mandatory. The numbers create ranking; the comments create accountability.

From the scores, they select:

Top 5 to reward — public recognition, small prizes, visibility to leadership
Top 15 to invest — dedicated time, resources, or team allocation for the next cycle

The rest get documented feedback. Every submission gets a response. No idea goes into a void.

Graduation paths:

Every selected prototype gets one of four outcomes:

Graduate — fund it, staff it, put it on a product roadmap. It's real now.
Iterate — promising but not ready. Gets another cycle with more support.
Shelve — valuable concept, wrong timing. Archived with documentation. Can be resurrected.
Kill — learned what we needed. Thank the team, archive the code, close the loop.

Every decision gets a graduation record:

# Graduation Decision

> **Submission:** AI-Powered Inventory Alert System
> **Cycle:** Q1-2026
> **Evaluation Score:** 21/25 (ranked 3rd of 42 submissions)

## Outcome: GRADUATE
Fund it, staff it, integrate into product roadmap.

## Reasoning
Strong dollar value framing backed by real backtesting data (78% of
stockout events flagged with 5-day lead time). Low resource ask relative
to projected $680K/year savings. Warehouse ops champion already lined up.
Primary risk (ERP API access) is a known 6-week process, not a blocker.

## Next Steps
- [ ] Assign product owner: Maria Gonzalez
- [ ] Allocate team: 2 engineers + 1 ops lead, 3 months
- [ ] Schedule kickoff by 2026-04-01
- [ ] Define MVP scope: pilot at 2 locations

The key: every path has closure. People know what happened and why. No prototype enters zombie state — alive enough to haunt you, dead enough to not ship.

Part 2: The Operating Team

Two groups make this work: a leadership team and an organising team.

The leadership team has one job: investment authority. They review the organising team's recommendations, make funding decisions, and connect graduated prototypes to product roadmaps. They don't evaluate submissions — that's the organising team's job. They make it possible for good ideas to actually become real things.

What they should do:

Take time to understand what people are trying to solve, not just what they built
Attend demo sessions, ask questions, show genuine interest
Move fast on graduation decisions — momentum kills if you wait too long

What they should not do:

Treat this as a checkbox exercise — people can tell when leadership is performing interest versus showing it
Sit on graduation decisions for weeks — the engineer who built the prototype on their weekends deserves a timely answer

The organising team is the engine. These aren't managers. These are your rockstars — the people who are already respected across the organisation. A cross-functional mix: product, UX, engineering, data, security. They understand both the technical and the business side.

Think of them as the Jedi Council — except one that actually listens to people instead of dismissing Anakin's concerns. The job is curation, not gatekeeping.

What they should do:

Review submissions with open minds — the best ideas often look weird at first
Group similar submissions together — if five people independently prototyped something similar, that's a signal about a real problem, not a coincidence. Pay attention to that.
Connect people working on adjacent problems — facilitate the conversations that wouldn't happen organically
Look for patterns in what's being built — the aggregate tells you more than any individual submission
Build tooling that helps people prototype faster — shared components, design systems, API templates, even AI-powered extensions for common patterns
Maintain transparency — everyone can see what's been submitted, what's been selected, and why

What they should not do:

Gate-keep based on role or seniority — a business analyst's prototype is as valid as a staff engineer's
Reject ideas for being "too simple" — simple solutions to real problems are the most valuable kind

Part 3: The Infrastructure (It's a GitHub Repo)

This is where I might sound opinionated, but hear me out.

You don't need a platform. You don't need a multi-tenant app with versioning, workflows, approval chains, and a React dashboard. You need a GitHub repository.

I know what you're thinking: "GitHub? For managing enterprise innovation?" Yes. And here's why.

The instinct is to build a tool first. A submissions portal. A review dashboard. An analytics layer. Three months and $200K later, you have a beautiful platform and zero submissions because nobody wants to learn another internal tool. I've seen this happen twice. Both times, the platform outlived the programme.

Git + GitHub gives you almost everything:

prototype-ops/
├── templates/
│   ├── submission-template.md      # What submitters fill in (the PR)
│   ├── evaluation-template.md      # How reviewers score (per submission)
│   └── graduation-template.md      # Decision record (graduate/iterate/shelve/kill)
├── submissions/                    # One branch per submission, merged PRs = archive
├── examples/
│   ├── example-submission-1.md     # AI-Powered Inventory Alert System
│   ├── example-submission-2.md     # Meeting Decision Recorder
│   └── example-submission-3.md     # Compliance Doc Generator
├── docs/
│   ├── guidelines.md               # Do's and don'ts, approved tools
│   ├── ai-tools-guide.md           # What AI tools the company offers + how to use
│   ├── problem-framing.md          # How to think about dollar value and effort
│   └── reference-problems.md       # Org-level problems leadership wants solved
└── dashboard/                      # Simple UI to visualise submissions

Submissions are pull requests. The prototype code lives in the PR. The description follows the submission template. Discussion happens in comments.
Decisions are recorded. Approved, rejected, needs iteration — it's all in the PR history. Reviewers' reasoning is captured.
Everything is in one place. No context-switching between a submissions portal, a Slack channel, an email thread, and a spreadsheet.
Transparency is built in. Anyone can browse open PRs to see what's been submitted. No duplicate ideas because you can search before you submit.
Governance is native. Branch protection, required reviewers, templates — GitHub already has the workflow primitives.

The docs/ directory does the heavy lifting that policy emails never could. guidelines.md tells people what tools they can and can't use — which naturally educates about shadow AI without a single compliance slide. ai-tools-guide.md shows people the power of tools the company already pays for — reducing the incentive to go rogue. problem-framing.md teaches people to think about dollar value and effort before they build — the best filter is self-filtering. reference-problems.md gives direction without being prescriptive: "here are problems leadership wants solved, if you're looking for inspiration."

And yes — you can add AI-powered extensions to the repo that automate submission review, evaluation grouping, status tracking, and reporting. The organising team doesn't spend their time on mechanics. They spend it on judgment.

I've built a starter repo that any organisation can fork to bootstrap their prototyping operating model. It includes the submission templates, evaluation workflows, team manifest, and example submissions.

prototype-ops on GitHub — fork it, adapt the templates to your org, and you're running by next quarter.

Why This Works (When Everything Else Didn't)

The hackathon failed because it was an event. This is a system.

The governance policies failed because they said "don't." This says "do — but here."

The awareness events failed because they were broadcasts. This is a conversation.

The AI adoption teams failed because they were invisible. This is visible by design — every submission, every decision, every outcome is public within the organisation.

And shadow AI? It doesn't disappear. But it surfaces. When people have a legitimate channel for their prototyping energy — with clear guidelines, approved tools, and a path to recognition — the incentive to operate in the shadows drops dramatically. Not because you banned it. Because you made the alternative better.

Like the Rebel Alliance, you don't win by building a bigger Death Star. You win by giving people something worth fighting for. A system that recognises their ideas, resources the good ones, and doesn't waste their time with the rest. That's the Prototyping Operating Model.

One Takeaway

Your people are already prototyping. They're doing it on lunch breaks, on weekends, in the gaps between sprint tickets. The question isn't whether to allow it. The question is whether you channel it into a system that creates value — or ignore it until someone publishes your customer data to a public repo.

Build the operating model. Stand up the team. Fork the repo. Start this quarter.

The dinosaurs are already out. The fence is already down. The only question left is whether you build Jurassic World with better containment — or keep pretending the park is still under control.

If your enterprise is drowning in unsanctioned prototypes — or worse, pretending they don't exist — I'd like to hear how you're handling it. What's working? What spectacularly isn't? And if you've tried hackathons and they didn't stick, you already know why.

What if your context maps, event flows, and dependency graphs just... generated themselves from Markdown?

Raj Navakoti — Tue, 24 Mar 2026 10:18:47 +0000

What if your context maps, event flows, and dependency graphs just... generated themselves from Markdown?

Your architecture diagrams are lying to you. Not intentionally — they were accurate the day someone drew them. But that was six months ago, and since then three services got renamed, two teams reorganised, and the person who maintained the draw.io file left the company. The model still lives in a desktop app that nobody opens, on a Confluence page nobody finds, in someone's head that is now at a different employer.

The tooling is either too heavy (paid enterprise tools that require a two-day training course) or too manual (Markdown ADRs that are great for decisions but tell you nothing about how 40 systems relate to each other). There is a gap between "I have docs" and "I have a living architecture model."

The idea

What if architecture elements were just Markdown files in Git? And what if the relationships you declared in those files were enough for the diagrams to draw themselves?

No diagram tool. No proprietary format. No model-to-code sync problem — the Markdown is the model. You declare what exists and how things connect. A static site build reads those files, resolves the graph, and generates every view automatically.

That is what Architecture Catalog does.

How it works

Three steps. That is the whole thing.

Step 1: Define your schema (one YAML file)
         ↓
Step 2: Add elements (Markdown files with YAML frontmatter)
         ↓
Step 3: Build (npm run build → static site)

The schema file (registry-mapping.yaml) defines your layers, element types, relationships, and branding. The Markdown files are your elements — one file per system, service, domain, or whatever your vocabulary calls them. The build reads both, resolves the graph, and generates an interactive site.

No server. No database. No runtime dependencies.

What you get

Dashboard with domain cards — top-level view across all domains with health indicators, element counts, and quick navigation.
Interactive context maps — search, filter, and focus mode. Click any element to see its first-degree and second-degree relationships. The graph is built from the relationship declarations in your Markdown files.
Animated event flow diagrams — shows which systems publish events, which systems consume them, and how data flows across domain boundaries. Designed for teams that have moved to event-driven architectures and lost track of who owns what.
PlantUML, BPMN, and draw.io viewer — if you have existing diagrams, they render inside the catalog next to the registry elements. You are not forced to throw away what you have.
Element detail pages — every element gets its own page: description, layer, domain, all declared relationships, and links to related diagrams.
Dark mode by default — because architects apparently live at night.
White-label and deploy anywhere — it is a static site. Firebase, S3, GitHub Pages, Netlify — your choice.

See it live

The live demo is at architecture-catalog.web.app. It has 6 domains, 180+ entities, and is fully interactive — context maps, event flows, element drill-down, the lot.

The documentation site is at docs-architecture-catalog.web.app if you want to understand the schema before you start.

Open either one before reading the rest of this post. The 30 seconds you spend clicking around will make the next part more concrete.

The schema-driven part

This is the piece that makes it maintainable at scale.

Everything flows from a single YAML file. Here is the minimal version — a site configuration and one element type:

site:
  name: "My Architecture Catalog"
  description: "Architecture model for Acme Corp"
  accent_color: "#4A90D9"

layers:
  - id: application
    name: Application
    color: "#1E3A5F"
    types:
      - id: service
        name: Service
        icon: "⬡"
        graph_rank: 2
        description: "A deployable service or microservice"

That is it. With this in place, you create Markdown files in the registry-v2/application/services/ folder and they automatically appear in the dashboard, get their own detail pages, and participate in context maps.

Adding a new element type means adding one entry to this YAML file and creating a _template.md. Zero code changes. The UI derives everything — page structure, graph layout, relationship rendering, sidebar navigation — from the schema.

It is also vocabulary-agnostic. You can use ArchiMate, TOGAF, C4, or whatever your organisation invented. The catalog does not care what you call your elements. Rename every type and layer in the YAML and the site still builds and renders correctly.

Validated at scale

I have been running a version of this internally across 30 domains with over 6,000 registered elements. The build still takes under 15 seconds. The output is pure static HTML — no server, no database, no runtime dependencies.

The architecture team stopped manually maintaining diagrams. Context maps generate from what teams declare in their Markdown files. New elements show up in the catalog as soon as the PR merges.

That is the real test — not whether it works on a demo dataset, but whether it holds at enterprise scale without becoming a maintenance burden.

Why Markdown and Git

This is not a new argument, but it is worth making clearly:

Git history is your architecture changelog. Every structural change is a commit. You can diff the architecture between quarters.
PRs are architecture reviews. When a team adds a new service or declares a new dependency, it goes through the same review process as code. No separate approval workflow.
AI can read it without instruction. Plain Markdown with structured frontmatter is natively parseable by any LLM. Ask your AI assistant about a domain — it can read the actual model, not a summary someone wrote last year.
No vendor lock-in. Markdown files in a Git repo will be readable in 20 years. The same cannot be said for every architecture tool on the market today.

Try it

git clone https://github.com/ea-toolkit/architecture-catalog.git
cd architecture-catalog/catalog-ui
npm install
npm run dev

Open localhost:4321 and you will see the dashboard. The demo data is a fictional B2B SaaS CRM — 3 domains, 71 elements — built to show off the features without being distracting.

The README has instructions for pointing it at your own registry. The schema documentation on the docs site walks through every field in registry-mapping.yaml.

Open source, MIT licensed

The project is open source under the MIT license. Contributions are welcome — issues, PRs, feature requests, and feedback on the schema design are all useful.

I am presenting this at DDD Europe 2026, where the talk covers the broader problem: how do you make architecture observable at enterprise scale without creating a second job for the architecture team? The catalog is part of that answer.

If you have opinions on architecture tooling — what is broken, what you have tried, what you wish existed — I would genuinely like to hear them. How does your team track architecture decisions and element relationships today?

One Takeaway

Architecture tooling fails because it separates the model from the thing being modelled. Plain Markdown in Git closes that gap — the model lives where the work lives, changes when the work changes, and reads the same way code does.

The diagrams drawing themselves is a side effect. That is the point.