Diagrams As Code

A working example on how to document your architecture and/or system diagrams as code
· Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Contributing

About The Project

Diagrams are often created using visual tools. If its online, then its on another website associated with a specific account. If its offline then its on someone's desktop. In both cases, there is no single source to get the up-to-date document at any given time. There could be multiple versions circulating within the organization spreading misinformation.

Here's why your team should write system/architecture diagrams as code:

• Generation - Automatically generate diagrams writing minimal code; No need to waste time dragging to align blocks or dimensions of blocks.
• Versioning - Track, audit and review your diagrams like you would any piece of code through git
• Single source of truth - Bundled with your source code in the same git repository. If you have 1 source code repo then you have 1 source for the diagrams as well.

(back to top)

Built With

This boilerplate wraps the following projects along with other open-source plugins and tools to give you a complete setup to start working right away.

• PlantUML
• Diagrams
• Visual Studio Code
• Docker

(back to top)

Getting Started

Use this repo as an example or boilerplate to add it to your source code git repo.

Prerequisites

If on MacOS, make sure to have xcode cli installed

xcode-select --install

Installation

1. Clone the repo
2. Permission to execute the script

   chmod +x ./setup-macos.sh

3. Execute

   ./setup-macos.sh

The script will try to install all the dependencies if not present but there might be machine related settings because of which the script might fail. In that case, create an issue or try to read the script to install the requirements manually.

(back to top)

Usage

1. Start with C4 diagrams using PlantUML. Follow the examples Context, Container and Component in this repo.
   • To preview the diagrams : Open VS Code Command Pallette and Select PlantUML : Preview current diagram
2. End with system diagrams using Diagrams. Follow the example diagram in this repo.
   • To preview simply Run All the Jupyter notebook from top toolbar

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)