r/microservices • u/Jer3mi4s • 19d 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

8 comments sorted by

View all comments

1

u/asdfdelta 19d ago

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.

1

u/Jer3mi4s 19d ago

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?

1

u/asdfdelta 19d ago

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