Streamlining Architecture Documentation: A Dual Diagram Strategy

In the justifai project, maintaining up-to-date and accessible architectural documentation is paramount. As systems evolve, so must their representations. A common challenge arises when balancing the need for visually rich, high-level diagrams with the precision and maintainability of 'diagrams as code'. This post explores how justifai addresses this by implementing a dual diagram strategy.

The Challenge of Evolving Architectures

Architectural diagrams are crucial for understanding a system's structure and flow. However, they are notoriously difficult to keep current. Many teams adopt 'diagrams as code' tools, which allow defining diagrams in text files that can be version-controlled and generated automatically. While powerful, this approach can sometimes conflict with the desire for a highly curated, aesthetically refined visual that serves as the primary overview.

The problem intensifies when a generation script is configured to output an image file with a generic name, like architecture.png. If a team has invested time in creating a detailed, visually distinct architecture.png using a tool like draw.io, an automated script could inadvertently overwrite this primary visual with a new, potentially less refined, code-generated version. This leads to a loss of the carefully crafted visual and confusion about which diagram represents the definitive source of truth.

A Dual Approach: Curated vs. Code-Generated Diagrams

To overcome this, the justifai project adopted a strategy that clearly separates the two types of architectural visuals. The solution involves maintaining a primary draw.io-based architecture.png for a high-level, curated overview, and a distinct architecture-as-code.png for detailed, automatically generated representations.

The key change lies in the diagram generation workflow: instead of outputting to the generic architecture.png, the 'diagram-as-code' script is now configured to generate architecture-as-code.png. This ensures that the primary visual remains untouched and serves its purpose as the main reference point, while the code-generated diagram provides an alternative, automatically updated perspective.

This is akin to having a beautifully rendered, static map for a quick overview (the draw.io diagram) and a dynamic, GPS-driven map for real-time, detailed navigation (the code-generated diagram). Both are valuable, but serve different purposes.

import subprocess
import os

def generate_and_save_diagram(source_file, output_filename):
    """
    Simulates generating a diagram from a text-based source file
    (e.g., Mermaid, PlantUML) and saving it to a specific PNG file.
    In a real scenario, this would invoke a CLI tool like `mmdc` or `plantuml`.
    """
    print(f"Generating diagram from '{source_file}' to '{output_filename}'...")
    try:
        # Placeholder for actual diagram generation command
        # Example: subprocess.run(["mmdc", "-i", source_file, "-o", output_filename])
        with open(output_filename, "w") as f:
            f.write(f"Simulated content for {source_file}\n")
        print(f"Successfully created placeholder: {output_filename}")
    except Exception as e:
        print(f"Error generating diagram: {e}")

# Define the source for the code-generated diagram
diagram_source_file = "architecture.mmd" # e.g., a Mermaid diagram definition

# Specify the distinct output file for the code-generated diagram
output_generated_diagram = "architecture-as-code.png"

# Execute the generation (in a real scenario, this would be part of a CI/CD pipeline)
if __name__ == "__main__":
    generate_and_save_diagram(diagram_source_file, output_generated_diagram)
    print("\nRemember to refer to both diagrams in your documentation:")
    print("- Primary curated visual: architecture.png (from draw.io)")
    print(f"- Code-generated visual: {output_generated_diagram}")

The Python script above illustrates the core idea: directing the output of the diagram generation process to a separate file (architecture-as-code.png) to avoid conflicts. This simple configuration change ensures both types of diagrams can coexist and serve their respective audiences.

Implementation Details and Documentation

Beyond the script adjustment, effective implementation of this strategy requires clear communication. The README and architecture.md files were updated to explain this separation. This documentation now clarifies that:

• architecture.png is the main visual, sourced from an editable draw.io file, offering a high-level overview.
• architecture-as-code.png is the automatically generated diagram, providing a detailed, code-derived view of the architecture.

This explicit documentation prevents confusion and ensures that anyone looking at the project's architecture understands the purpose and origin of each diagram. It establishes a clear convention for managing visual documentation, which is vital in collaborative development environments.

By separating primary visual documentation from programmatically generated views, justifai ensures that its architectural insights remain both visually appealing and accurately reflective of the underlying codebase. This approach fosters better understanding, reduces maintenance overhead, and prevents accidental data loss, ultimately contributing to a more robust documentation ecosystem.

Generated with Gitvlg.com