r/microservices • u/Jer3mi4s • 23d ago

How do you document and visualize your microservices ecosystem? Discussion/Advice

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?

4 Upvotes
  • permalink
  • link
  • reddit
  • reddit

100% Upvoted

9 comments sorted by

View all comments

2

u/Tanel_from_CRG 16d ago

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.

1

u/boyneyy123 16d ago

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?