Skip to main content

System Auto-Documentation

đź“Ś If you have any questions shoot us an email or join us on Discord! đź’ś

Overview​

With Multiplayer’s System Auto-Documentation you can automatically discover, track, and document your entire system architecture - including all components, APIs, dependencies, platforms, and environments.

You don’t have to manually create diagrams or check for drift in your documentation anymore. Just enable Auto-Documentation and we'll reverse engineer and document your entire system architecture.

How Auto-Documentation Works​

Multiplayer Auto-Documentation is a feature of the System Dashboard. When it's enabled it automatically discovers all components, APIs, dependencies, platforms, and environments within your software system and lists them within the dashboard.

To enable Auto-Documentation you need to integrate with OpenTelemetry (OTel) using the Multiplayer tokens. Multiplayer leverages the OpenTelemetry Collector - a proxy that receives, processes, and exports telemetry data - to receive the distributed traces data you export.

We store raw OTel traces in ClickHouse. After processing (i.e. extracting the component name, environments, dependencies, etc.), data is stored in a different database in ClickHouse.

Thanks to Auto-Documentation the information in the System Dashboard is updated automatically, every time a change happens in the real-world system.

Getting Started with Auto-Documentation​

To set up the Auto-Documentation follow these steps:

  • Open your project
  • In the left-side menu, click "System" to open the System Dashboard
  • Click "Enable Auto-Docs + Debugger"
  • Name your integration
  • Hit "Create"
  • An OpenTelemetry (OTel) token will be created for your OTel integration.
  • Follow these steps to configure OpenTelemetry

ℹ️ The Platform Debugger and System Auto-Documentation both leverage OpenTelemetry. That’s why they share a set up window.

Reading the Auto-Documentation statuses​

When Auto-Documentation is configured in the System Dashboard, next to each Component and API in your System Dashboard you will see a status icon.

  • 🟢 In Sync = The component exists in Multiplayer and has been detected by Auto-Documentation. Your System Dashboard is showing full sync between the information manually added to your Multiplayer project and the information automatically detected in your system by Auto-Documentation.
  • ⬜️ Documented = The component exists in Multiplayer and has not been detected by Auto-Documentation. This may happen when you manually add components in your Multiplayer project (e.g. by editing a platform or through a system design review) that do not yet exist in your software system or that have a different name. To prevent naming confusion, you can add multiple aliases to components.
  • 🟣 Detected = The component has been detected by Auto-Documentation, but does not exist in Multiplayer. If “Auto-add” is configured in your Otel configuration, Auto-Documentation will automatically create newly detected components that are not currently present in your Multiplayer project, in the selected platform.

When to Use Auto-Documentation​

Auto-Documentation is the ideal solution if you're looking to solve these challenges:

(1) Eliminating the Overhead of Manual Documentation Manually maintaining accurate architecture diagrams and API documentation becomes nearly impossible as systems grow and evolve—especially in complex distributed environments managed by geographically dispersed teams. Multiplayer automates this process by continuously discovering and documenting components, dependencies, and APIs, ensuring your system is always up-to-date.

(2) Making Sense of Legacy Systems Legacy systems are notoriously hard to understand due to missing or outdated documentation, layers of interconnected components, and the departure of the original developers. Multiplayer's auto-documentation helps reverse engineer these systems by automatically generating accurate architecture information. This empowers your team to confidently modernize legacy systems, address technical debt, and safely evolve your infrastructure.

(3) Preserving Institutional Knowledge Teams often suffer from knowledge loss due to undocumented tribal knowledge, outdated documentation, or employees leaving the organization. Multiplayer safeguards institutional knowledge by centralizing and automatically documenting your system’s architecture. This ensures critical system insights are always accessible, reducing the reliance on specific individuals or ineffective documentation practices.

(4) Avoiding Architectural Technical Debt Lack of a clear, up-to-date view of the system leads to uninformed changes, which can quickly result in architectural technical debt. Multiplayer provides the necessary visibility to make safe, informed decisions, helping teams proactively evolve their system while minimizing the risk of introducing inefficiencies or bottlenecks.

(5) Identifying Drift in Your Manually Designed Architecture In Multiplayer, you can design and visualize your system architecture by manually creating a platform. This is ideal when you're designing a greenfield application or discussing architecture refactoring with your team. However, relying solely on a manually designed platform, may introduce a drift with your running software system.

Multiplayer bridges this gap with Auto-Documentation: it reviews component names (and their aliases) in your project and compares them to your real-world system data, immediately highlighting any drift.

Next Steps​

You did it! What’s next?