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	draft input.yml | dot -Tpng > output.png
JPEG	draft input.yml | dot -Tjpg > output.jpg
PostScript	draft input.yml | dot -Tps > output.ps
SVG	draft input.yml | dot -Tsvg > output.svg

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 id explicitly (i.e. id: MY_SERVICE_A)
• or you can omit the component id attribute 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.

1. Download the PNG icons of your cloud provider AWS, GCP, Azure

2. Take only the icons related to the components supported by draft

3. Make a directory with the provider name (i.e. /draft/icons/aws, /draft/icons/google, /draft/icons/azure)

4. Rename each icon as draft components kind (i.e. dns.png, cdn.png and so on...)

5. 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