Why use a DaC tool?

Imagine being part of a development team on a complex microservices project. In a crucial planning meeting, you must present the proposed architecture to collect feedback and advance the development. However, the lack of a user-friendly, speedy tool for prototyping ideas can make the process difficult and lengthy.

Without a DaC solution, the team would have to resort to traditional drawing tools, consuming valuable time for visual adjustments. Additionally, keeping visual documentation aligned with architectural changes becomes a tedious and often neglected task. A DaC tool would allow for drawing the architecture through code, significantly speeding up the process, ensuring consistency between code and visual representation, and facilitating dynamic adjustments during the meeting.

Image of an event processing architecture on AWS.

What are the benefits of using a DAC tool?

Using DaC, instead of traditional tools like DrawIO, offers several notable advantages for software architecture development. The DaC method aligns architecture design with the actual code, ensuring consistency between ongoing system changes and what gets implemented. This approach avoids the frequent mismatch that occurs when using external tools like DrawIO to maintain up-to-date visual documentation.

Moreover, adopting DaC enhances efficiency as it enables automated diagram generation, which saves significant time compared to manual creation in traditional tools. The feature of versioning and tracking code changes greatly simplifies the maintenance of documentation, a task that is often challenging with external tools.

Another significant advantage is the scalability and flexibility provided by DaC. As the system evolves, code can be quickly updated to reflect architectural changes ensuring that visual documentation remains current.

In summary, adopting DaC, especially with libraries like Diagrams, represents an easy and efficient approach to creating and maintaining software architectures, overcoming the limitations of traditional tools like DrawIO.

What are the disadvantages?

While DaC offers many advantages, it's important to consider some challenges that may arise. The transition to using such tools can pose a significant learning curve for those unfamiliar with Python syntax and the used library, requiring time and effort for adaptation.

Furthermore, reliance on external libraries can pose potential issues. While DaC eases the creation and maintenance of diagrams, an increased dependency on external tools or libraries can lead to challenges. This is particularly problematic if these tools or libraries cease to be updated or are discontinued, thereby affecting DaC's effectiveness.

Another challenge to consider is the requirement of programming knowledge. While Python is famous for its user-friendliness, it could still pose a hurdle for those without any coding experience or familiarity. These aspects should be thoroughly assessed when deciding to implement DaC in a particular context.

Hands-On

Let's proceed to a practical hands-on session to create an architecture using AWS components through DaC.

Our goal is to construct an architecture for executing SQL migrations via GitHub Action on AWS. Once we complete the code, we will have a diagram representing the GitHub Actions CI/CD process sending a file to AWS S3. This will then automatically trigger a Lambda function and apply SQL scripts to the database running on AWS RDS.

Step 1: Environment Configuration

Ensure that you have Python (3.7 or later) and the pip package manager installed in your environment. Next, install the Diagrams library by running:

pip install diagrams

Step 2: Creating the Python File

Create a file named cloud_migrations.py.

Step 3: Python Code

The Diagrams library includes various add-ons for different clouds and tools, and it's even possible to add custom components. In our case, it won't be necessary to add any external component as what we need is already provided by default.

Add the following code to the file created in the previous step:

from diagrams import Cluster, Diagram

from diagrams.aws.compute import LambdaFunction as Lambda

from diagrams.aws.database import RDSPostgresqlInstance as RDS

from diagrams.aws.storage import S3

from diagrams.onprem.ci import GithubActions

with Diagram("Cloud Migrations", show=False, direction="LR"):

github = GithubActions("Github Actions")

with Cluster("AWS"):

s3 = S3("/migrations")

lambda_function = Lambda("Lambda Migrator")

rds = RDS("RDS")

github >> s3

s3 >> lambda_function

lambda_function >> rds

Step 4: Generating the Image

After saving the changes, execute the following command to create an image of the architecture:

python cloud_migrations.py

Upon running this command, you should find a newly created file named cloud_migrations.png.

Open this image to view the resulting diagram:

Done! We now have our architecture expressed in a diagram that can be versioned using a tool familiar to us developers.

Conclusion

The Diagram as Code (DaC) approach presents several advantages and some disadvantages compared to traditional drawing tools. It ensures consistency between the visual representation and the actual implementation of the system. The ability to version and track changes in the code, as well as the efficiency of automatically generating diagrams, are significant benefits that speed up development and ease communication between teams.

Utilizing DaC allows developers to create and maintain software architectures efficiently, aligning with DevOps best practices. The flexibility to depict simple or complex architectures shows how this approach can adapt to current software development requirements.

Given the continuous evolution in development practices, integrating DaC offers a robust and contemporary solution for architecture documentation and visualization. This enhances efficiency and collaboration within development teams.