Let’s face it: having a good model for visualizing your architecture is not the same as having a good architectural visualization. In our previous article, we introduced the model we use for creating architecture diagrams, and here we will look at how we make documentation part of our development process.
The Case for Architecture Visualization
Shifting Left on Architecture Visualization
As developers, we are often tempted to jump straight into problem-solving mode and leave tasks like documentation for last.
However, integrating architecture visualization into the early stages of development can help achieve clarity and alignment, saving time and effort later. Shifting documentation and visualization to the start of the process ensures that teams collaborate effectively and identify potential issues early.
Operationalizing Visualization with Backstage
Backstage Software Templates
We use Backstage as our IDP (Internal Developer Platform) to streamline our development process and Revision for creating architecture diagrams.
The Revision plugin in Backstage lets us integrate these diagrams directly into our platform, keeping everything in one place.
When implementing a new integration system, we start by creating the System Context Diagram and System Component Diagram in Revision. This step isn’t just about creating documentation—it’s about thinking collaboratively, catching issues early, and ensuring everyone is on the same page before we write code.
Introduction to Templates
To operationalize this approach, we have built a set of software templates in Backstage. These templates provide a skeleton implementation of all our system archetypes and are the starting point of all new development efforts.
These templates save time by reducing repetitive setup and enforcing consistent standards across teams.
Each template is designed to:
- Collect essential implementation details.
- Require references to architecture diagrams in Revision to ensure all systems are well-documented from the start.
- Generate a skeleton implementation that adheres to our standards and best practices.
Embedding references to architecture diagrams within the templates ensures they are prerequisites for any new development work. This approach helps us catch design issues early.
The template catalog: Finding the Right Starting Point
To demonstrate how the templates work in practice, let’s walk through creating a new implementation of the Pub/Sub archetype called Syndicator using our Backstage Software Templates.
In Backstage, we can browse all available templates to find one that matches our needs.
Here, we browse our templates to find the right one for our Syndicator implementation. You should usually select one of the recommended templates to ensure we stay aligned with organizational standards.
Filling in the Details: Using the Backstage Wizard
Once we select the Syndicator template, we’re guided through a wizard where we fill in key details, such as links to architecture diagrams. This ensures that documentation is part of the process from the start.
By linking our diagrams directly in the wizard, we ensure that every new system is well-documented and its architecture is easy to find later.
In our case, we are using GitLab as our version control system (VCS). At this step, we decide where we want to create the new repository in our GitLab structure.
The Results: A Fully Registered System with Linked Diagrams
With the template executed, we have a fully configured repository and an automated pipeline. The system is registered to our integration catalog, which ensures that our processes are repeatable and scalable.
Here, we see the system registered in the integration catalog in Backstage.
This shows that our architecture diagrams are linked.
We can see that we have a pipeline registered, and we can also see its run history directly from the integration catalog.
Once the pipeline run is completed, we will have a Markdown document site with some default documentation deployed and available from the integration catalog.
Conclusion
Integrating architecture visualization into our development workflow and leveraging Backstage templates ensures every system starts with a solid foundation. This approach reduces rework, fosters collaboration, and keeps documentation at the center of the process.