Awesome
Draft
A commandline tool that generate High Level microservice & serverless Architecture diagrams using a declarative syntax defined in a YAML file.
- Works on linux, macOS, windows
- Just a single portable binary file
- Input data in flat YAML text files
- Usable with shell scripts
Why?
I prefer to think in terms of capabilities rather than specific vendor services.
- "do we need a DNS?" instead of "do we need Route 53?"
- "do we need a CDN?" instead of "do we need Cloudfront?"
- "do we need a database? if yes? what type? Relational? No SQL" instead of "do we need Google Cloud Datastore?"_
- "do we need some serverless function?" instead of "do we need an Azure Function"
...and so on.
How draft works?
draft takes in input a declarative YAML file and generates a dot script for Graphviz
draft backend-for-frontend.yml | dot -Tpng -Gdpi=200 > backend-for-frontend.png
Piping the draft output to GraphViz dot you can generate different output formats:
| format | command |
|---|---|
| PNG | <code>draft input.yml | dot -Tpng > output.png</code> |
| JPEG | <code>draft input.yml | dot -Tjpg > output.jpg</code> |
| PostScript | <code>draft input.yml | dot -Tps > output.ps</code> |
| SVG | <code>draft input.yml | dot -Tsvg > output.svg</code> |
To install GraphViz to your favorite OS, please, follow this link https://graphviz.gitlab.io/download/.
Installation Steps
To build the binaries by yourself, assuming that you have Go installed, here the steps:
Clone the repo,
git clone https://github.com/lucasepe/draft.git
Move to the 'cmd' directory:
cd draft/cmd
Generate the static assets
go generate ../...
Build the binary tool
go build -o draft
Components
The basic unit of each draft design is the component, has these attributes:
| Name | Required | Scope | Notes |
|---|---|---|---|
| id | no | used for the connecttions | autogenerated if omitted (read more for details...) |
| kind | yes | identify the component type | see all available kinds |
| provider | no | get the specific provider icon | see using custom icons |
| label | no | text below the component icon | can contain basic HTML tags |
| outline | no | tag to group components | |
| impl | no | text above the icon | can use this to specify the provider implementation |
| fontColor | no | the label text color | hex color code - supports transparency too |
Notes about a component id
- you can define your component
idexplicitly (i.e. id: MY_SERVICE_A) - or you can omit the component
idattribute and it will be autogenerated
How is auto-generated a component id?
An auto-generated component id has a prefix and a sequential number
- the prefix is related to the component
kind- examples waf1, ..., wafN or ser1, ..., serN etc.
List of all available kinds
Draft uses a set of symbols independent from the different providers (AWS, Microsoft Azure, GCP).
Below is a list of all the components currently implemented.
Clients
Sample YAML file examples/clients.yml.
draft -impl -verbose examples/clients.yml | dot -Gdpi=110 -Tpng > examples/clients.png
Networking
Sample YAML file examples/networking.yml.
draft -impl -verbose examples/networking.yml | dot -Gdpi=110 -Tpng > examples/networking.png
Compute
Sample YAML file examples/compute.yml.
draft -impl -verbose examples/compute.yml | dot -Gdpi=110 -Tpng > examples/compute.png
Database
Sample YAML file examples/database.yml.
draft -impl -verbose examples/database.yml | dot -Gdpi=110 -Tpng > examples/database.png
Storage
Sample YAML file examples/storage.yml.
draft -impl -verbose examples/storage.yml | dot -Gdpi=110 -Tpng > examples/storage.png
Security
Sample YAML file examples/security.yml.
draft -impl -verbose examples/security.yml | dot -Gdpi=110 -Tpng > examples/security.png
Using custom icons
Here how to render components with specific aws, google and azure icons.
-
Download the <u>PNG</u> icons of your cloud provider AWS, GCP, Azure
-
Take only the icons related to the components supported by draft
-
Make a directory with the provider name (i.e.
/draft/icons/aws,/draft/icons/google,/draft/icons/azure) -
Rename each icon as draft components
kind(i.e.dns.png,cdn.pngand so on...) -
Run draft specifyng the icons folder using the environment variable
DRAFT_ICONS_PATH
- example:
DRAFT_ICONS_PATH=/draft/icons draft my-file.yml | dot > ark-aws.png
👉 I have already done all the work for points 1 to 4. So you can avoid it by copying the directory icons 👈
Connections
The arrows that join the components.
To connect an origin component with one or more targets component you need to specify at least each id.
A connection has the following properties:
| Attribute | Type | Required | What is it? |
|---|---|---|---|
| origin | string | yes | id of the starting component |
| targets | object | yes | one or more destinations |
Each target has the following properties:
| Attribute | Type | Required | What is it? |
|---|---|---|---|
| id | string | yes | target component id |
| label | string | no | text on the connection |
| labeldistance | float | no | distance of the label from the connection tail |
| labelangle | float | no | determine the label position relative to the tail |
| minlen | float | no | sets the minimum connection length |
| num | int | no | usefult to track an order path on your graph |
| color | string | no | label color (hex color string) |
| dashed | bool | no | if true the connection line will be dashed |
| dir | string | no | arrows direction (forward, back, both, none) |
| highlight | bool | no | if true makes the arrow thicker |
Sample YAML file examples/connections.yml.
draft examples/connections.yml | dot -Gdpi=110 -Tpng > examples/connections.png
Changelog
👉 Record of all notable changes made to a project
Examples
👉 Collection of draft architecture descriptor YAML files
(c) 2020 Luca Sepe http://lucasepe.it. MIT License