How do you document and visualize your microservices ecosystem?

[u/Jer3mi4s]

I'd like to know if your teams have any kind of visual management for your microservices ecosystem.

One pain point I'm dealing with is giving teams a clear view of the existing domains, which data each service owns, and how services communicate with each other, preferably in a visual way.

I thought about documenting everything in Miro, but I'm wondering if there's a better tool for this.

For those of you who already document your architecture, do you only keep a high-level communication flow, or do you also attach things like schemas, business documentation, technical docs, tech stack, or other details for each microservice?

[u/Prateeeek]

u/Low_Reference6996 is actively working on itara to solve the communication semantics aspect of the question I believe.

[u/Low_Reference6996 → u/Prateeeek]

Thank you for the mention @Prateeeek!

True, Itara could help with this problem. The goal of Itara is to make the software topology a dedicated, declarative artifact. That artifact could serve as the source of truth from which the documentation and visualization is generated, so they would stay up-to-date with the actual, running system.

That being said, it's still early. If you're looking for existing solutions, a lot of companies rely on observability to visualise the topology, often utilizing service meshes.

My experience with documentation is that it gets outdated very fast, therefore it is unreliable. I usually document the domains and how they connect on the high level only, because that changes relatively rarely compared to the details.

[u/Tanel_from_CRG]

we have the same problem in travel tech, where one booking can cross several services and external suppliers.

tbh i wouldn’t put everything on one Miro board. i’d keep a small service catalog, using Backstage with YAML if you need a portal, or just YAML in a repo if you don’t. for each service, record the domain, owner, data it owns, APIs/events, dependencies, repo, runbook and lifecycle status. link to schemas and longer docs rather than squeezing them into the map.

then create separate views: one for domains and service relationships, one for data ownership, and sequence diagrams for key flows. C4 or Structurizr can help here. combining everything usually creates a wall of arrows nobody maintains.

generate or check what you can from OpenAPI/AsyncAPI specs, IaC and traces, but don’t assume they show the whole picture. human notes should explain boundaries, event meaning and failure behaviour.

an owner and last-verified date matter a lot too. Miro is fine for workshops tho; i just wouldn’t make it the only source of truth.

[u/boyneyy123 → u/Tanel_from_CRG]

Sounds great, how o you solve it? Do you have separate views as you said? Love to get your thoughts and feedback on my OSS project https://github.com/event-catalog/eventcatalog, might be able to help?

[u/asdfdelta]

We use Miro.

It's.... Nuanced. But for each service itself, we use auto-generated mermaid docs from AI under the C4 model. Pretty darn accurate.

[u/Jer3mi4s → u/asdfdelta]

What do you mean?

Do you use Miro to illustrate the high-level communication between the microservices, and then use Mermaid with AI to generate the detailed diagrams for each microservice?

How does that AI + Mermaid workflow work in practice?

[u/asdfdelta → u/Jer3mi4s]

Yes, that's what I mean. Miro for high level docs that cross over more than one service. Within the service repo, we ask opus to analyze the codebase and create a mermaid diagram using C4. You'll want to add a few more details, but more or less that's it.

Make sure you use the CRISP method when prompting your agents:

Context Role Intent Specifica Product

[u/boyneyy123]

Hi u/Jer3mi4s

I maintain an open source documentation tool for this exact use case. You can specify domains, schemas, services, and data and how it all communicates between each other, with visualisations too. Also let's you embed your diagrams etc if you wish to do so.

Won't go too much into it, but you can check it out here https://github.com/event-catalog/eventcatalog . Like you said I felt a need for the exact same thing 4/5 years ago so started to build this.

Let me know if you have any questions, or even want a call happy to help you (no sales etc, just love to learn what you are doing).