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
• It Does One Thing Well
• 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/.

Components

The basic unit of each draft design is the component:

type Component struct {
  ID        string `yaml:"id,omitempty"`        // optional - autogenerated if omitted (read more for details...)
  Kind      string `yaml:"kind"`                // required - see the table below
  Label     string `yaml:"label,omitempty"`     // optional - works only for: 'queue', 'service', 'storage', 'function', 'database', 'client'  
  Outline   string `yaml:"outline,omitempty"`   // optional - you can use this to groups some components
  Impl      string `yaml:"impl,omitempty"`      // optional - you can use this to specify the implementation
  FillColor string `yaml:"fillColor,omitempty"` // optional - the hex code for the background color 
  FontColor string `yaml:"fontColor,omitempty"` // optional - the hex code for the foreground color
}

Draft uses a set of symbols independent from the different providers (AWS, Microsoft Azure, GCP).

Eventually you can describe...

• the implementation using the impl attribute (ie: impl: 'SQS')
• the group using the outline attribute (ie: outline: AWS)
  • 💡 components with the same outline will be 'grouped'

Below is a list of all the components currently implemented.

Component	Kind	YAML	Output
Client	cli	👉 examples/cli.yml
Microservice	ser	👉 examples/ser.yml
Gateway	gtw	👉 examples/gtw.yml
Firewall	waf	👉 examples/waf.yml
K8s Engine	kub	👉 examples/kub.yml
Pub / Sub	msg	👉 examples/msg.yml
Queue	que	👉 examples/que.yml
Function	fun	👉 examples/fun.yml
Relational DB	rdb	👉 examples/rdb.yml
Document DB	doc	👉 examples/doc.yml
Caching	mem	👉 examples/mem.yml
Load Balancer	lba	👉 examples/lba.yml
CDN	cdn	👉 examples/cdn.yml
DNS	dns	👉 examples/dns.yml
Block Store	bst	👉 examples/bst.yml
Object Store	ost	👉 examples/ost.yml
File Store	fst	👉 examples/fst.yml

Auto filling the component implementation

In your YAML file, leave the impl fields empty and run draft with the -impl flag to let draft found the implementation by provider.

example command	output
draft -impl aws ./examples/dns.yml | dot -Tpng > test.png
draft -impl azure ./examples/dns.yml | dot -Tpng > test.png
draft -impl google ./examples/kub.yml | dot -Tpng > test.png
draft -impl aws ./examples/kub.yml | dot -Tpng > test.png

... and so on for each kind of component!

To render components with specific icons read below.

Rendering components with specific cloud provider 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 -impl and the icons folder using the environment variable DRAFT_ICONS_PATH

• example: DRAFT_ICONS_PATH=/draft/icons draft -impl aws 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 👈

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.

Connections

You can connect each component by arrows.

To be able to connect an origin component with one or more target component you need to specify each id.

A connection has the following properties:

type Connection struct {
  Origin string `yaml:"origin"`
  Targets []struct {
    ID          string `yaml:"id"`
    Label       string `yaml:"label,omitempty"`
    Color       string `yaml:"color,omitempty"`
    Dashed      bool   `yaml:"dashed,omitempty"`
    Dir         string `yaml:"dir,omitempty"`
    Highlight   bool   `yaml:"highlight,omitempty"`
  } `yaml:"targets"`
}

---

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