draft

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

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 the following output formats:

To install GraphViz to your favorite OS, please, follow this link https://graphviz.gitlab.io/download/.

Components

a picture is worth a thousand words

... and this is particularly true in regard to complex IT architectures.

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'  
  Provider  string `yaml:"provider,omitempty"`  // optional - you can use this to specify the cloud provider
  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
  Rounded   bool   `yaml:"rounded,omitempty"`   // optional - set to true if you wants rounded shapes
}

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 cloud provider using the provider attribute (ie: provider: AWS)
  • 💡 components with the same provider will be 'grouped'

Below is a list of all the components currently implemented.

Component	Kind	YAML	Output
Client	client	👉 examples/client.yml
Microservice	service	👉 examples/service.yml
Gateway	gateway	👉 examples/gateway.yml
Firewall	waf	👉 examples/waf.yml
Container Service	cos	👉 examples/waf.yml
Message Broker	broker	👉 examples/broker.yml
Queue Service	queue	👉 examples/queue.yml
Object Storage	storage	👉 examples/storage.yml
Function	function	👉 examples/function.yml
Database	database	👉 examples/database.yml
Load Balancer	balancer	👉 examples/balancer.yml
CDN	cdn	👉 examples/cdn.yml
DNS	dns	👉 examples/dns.yml
Custom Html	html	👉 examples/custom_image.yml

For custom HTML components (kind: html) only these tags are supported:

• <b>, <br/>, <font>, <hr>, <i>, <img> (in <td>…</td> only)
• <o>, <s>, <sub>, <sup>, <table>, <tr>, <u>

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

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

A connection has the following properties:

type Connection struct {
  Origin struct {
    ComponentID string `yaml:"componentId"`
  } `yaml:"origin"`
  Targets []struct {
    ComponentID string `yaml:"componentId"`
    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"`
}

Example 1 - Message Bus Pattern

The draft architecture descriptor YAML file is here 👉 ./examples/message-bus-pattern.yml

Running draft with this command:

draft message-bus-pattern.yml | dot -Tpng > message-bus-pattern.png

Will generate this output:

Example 2 - AWS Cognito Custom Authentication Flow

The draft architecture descriptor YAML file is here 👉 ./examples/aws-cognito-custom-auth-flow.yml

Running draft with this command:

draft aws-cognito-custom-auth-flow.yml | dot -Tpng > aws-cognito-custom-auth-flow.png

Will generate this output:

Example 3 - Getting the pre-signed URL to Upload a file to Amazon S3

The draft architecture descriptor YAML file is here 👉 ./examples/s3-upload-presigned-url.yml

Running draft with this command:

draft s3-upload-presigned-url.yml | dot -Tpng > s3-upload-presigned-url.png

Example 4 - A system view

The draft architecture descriptor YAML file is here 👉 ./examples/system-view.yml

Running draft with this command:

draft system-view.yml | dot -Tpng > system-view.png

Others examples

Check out the 👉 ./examples/ folders for more draft architecture descriptor YAML examples.

(c) 2020 Luca Sepe http://lucasepe.it. MIT License