DEV Community

Cover image for Nobody updates the architecture diagram, so I made the system draw its own
Abodunrin Ayodeji
Abodunrin Ayodeji

Posted on AI-assisted

Nobody updates the architecture diagram, so I made the system draw its own

When we build a product, the engineers map out the system architecture first. We draw the services, how they connect and what they depend on. The diagram gets reviewed and approved, and then we build.

After that, nobody goes back to update it.

Before long, the diagram is obsolete. Then an auditor comes around and asks to see the system, and we either show them something stale or rush to redraw it. Developers don't like updating diagrams. Most developers don't like documentation at all.

I've been through this enough times that I wanted a different answer. So I built Ritele.

Let the system draw itself

The idea is simple. Your services already send telemetry. Once a service is instrumented, OpenTelemetry traces record the calls it makes to other services, its database queries, the messages it publishes to queues and its requests to third-party APIs. That's the real architecture, written down by the system itself, all the time.

So Ritele takes that telemetry and draws the architecture from it: the actual services, the actual dependencies, and the actual things they connect to.

Ritele architecture map drawn from live OpenTelemetry traces
A Ritele map of a real system. Service names are changed.

Whether you're an engineer, an engineering manager or a CTO, you get visibility into what is actually running. You can see which service talks to which. If a service is connected to something it isn't supposed to be connected to, you see that too, and can make an informed decision about it instead of finding out during an incident or an audit.

Then it grew

A map tells you what is connected. The next questions are always the same: is it healthy, which request was slow, and what happened inside it? So I added tracing, logs and metrics.

Now you can start from the architecture and drill down: click a component and see its health, open the requests behind a number, follow one request through every service it touched and see how long each hop took, then jump to the log lines from that exact span.

A component's health, request rate, errors and latency, opened from the map

After that came the question every team asks before a big launch or a peak season: how much can this architecture actually take? So Ritele can simulate traffic on the architecture it has mapped (this one is on the paid plans). What happens if we get ten times today's requests at peak? Where do the bottlenecks show up first?

What it is now

The goal is one place for observability. If you want to see what is running in your environment, you go to Ritele and it's there. If you need to troubleshoot, it's there too. It runs on your own servers, so your telemetry stays with you.

Over the next few posts in this series I'll walk through each step on a real system with the names changed: from the map, to a component's metrics, to the slow request, to the log line that explains it.

If you've ever presented a stale diagram to an auditor, I'd like to hear how you handled it. Tell me in the comments.


Ritele has a free plan with no time limit: ritele.io

Top comments (4)

Collapse
 
xiangc_92294 profile image
xiangc •

Using live trace spans as the click-through entry point is neat—definitely beats maintaining Confluence screenshots every sprint.

The catch I've always run into with trace-generated topology is cognitive load. When you sketch a diagram in Draw.io or C4, you're not documenting network packets; you're communicating intent. You collapse 15 services into a single clean "Checkout" box because humans need abstraction to grok the system without getting overwhelmed.

OTel gives you absolute truth, but once you throw in retries, async queues, and third-party webhooks, the graph turns into a giant bowl of spaghetti. Ironically, that level of dense, raw detail feels like it's almost more useful fed directly into an AI agent as debugging context than for a human trying to onboard or explain things to an auditor.

How are you handling grouping in Ritele? Can teams collapse things into logical domains/subnets, or do engineers usually just navigate the raw mesh?

Collapse
 
abodunrin_ayodeji profile image
Abodunrin Ayodeji •

You've put your finger on the real problem. A raw trace graph is accurate and unreadable, and a diagram is readable because someone chose what to leave out.

Ritele handles it in three ways:

Spans become components. The map never draws spans. Every span from a service folds into one box, and the databases, caches, queues and third-party APIs it calls are inferred from client span attributes (db.system.name, server.address, the messaging attributes). A million requests with retries are still a single line between two boxes, carrying a rate, error rate and p99.

Components become domains. Set a ritele.domain resource attribute and the map groups components into that boundary, so your 15 services become one "Checkout" box. Without it, grouping falls back to the Kubernetes namespace or cloud account. A database inherits the domain of the services that call it, and if two domains call it, it's shown as shared, which is usually worth knowing. Above 25 components the map opens folded by domain; you expand the one you care about, or switch to just the busiest components.

One flow at a time. For onboarding or an auditor, the whole graph is the wrong view anyway. Pick a service and "How it works" shows the sequence of calls behind each of its operations, built from real traces, which is close to what you'd have sketched by hand.

And you're right that the dense raw detail suits an agent better than a person. That's where I'm heading: the human gets the abstraction, the machine gets everything underneath.

How do you draw the line today, by team ownership or by business capability?

Collapse
 
raju_dandigam profile image
Raju Dandigam •

Following a component from the map into the exact span and logs is a useful debugging path. One edge case for a trace-derived diagram is a cold path: sampling or low traffic can make a real dependency disappear from the observed graph. Do you show each edge’s last-seen window, or distinguish observed dependencies from declared ones, so “no span yet” is not mistaken for “no dependency”?

Collapse
 
abodunrin_ayodeji profile image
Abodunrin Ayodeji •

Good edge case, and it's one I had to design around early. Three things keep "no span yet" from reading as "no dependency":

Sampling doesn't touch the map. The Collector runs two pipelines. The graph is built from every span before any sampling; only the example traces you click into are tail-sampled. So a low sample rate thins out the traces you can open, not the dependencies you can see.

Edges age, they don't vanish. Each edge keeps its first-seen and last-seen times. It's active for 24 hours, then stale but still drawn for 30 days, and only then treated as gone. A monthly batch job's dependency stays on the map between runs, marked as quiet instead of disappearing.

Declared is separate from observed. A service can declare what it's meant to depend on (a ritele.intended_dependencies resource attribute), and you can save an intended design. A declared dependency that has never been called shows up as missing until the first span arrives, so it's visibly "expected, not yet seen". The reverse also holds: a call nobody declared is flagged as drift.

The gap that remains is the truly cold path that's neither declared nor called in the last 30 days, like a disaster-recovery failover. Traces can't know about that one; it has to be declared.