draft

README

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:

format	command
GIF	draft input.yml | dot -Tgif > output.gif
JPEG	draft input.yml | dot -Tjpg > output.jpg
PostScript	draft input.yml | dot -Tps > output.ps
PSD	draft input.yml | dot -Tpsd > output.psd
SVG	draft input.yml | dot -Tsvg > output.svg
WebP	draft input.yml | dot -Twebp > output.webp

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'  
  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
  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	cli	👉 examples/cli.yml
Microservice	ser	👉 examples/ser.yml
API 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

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 gcp ./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!

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

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

Documentation

Index

• type Component
  • func (co *Component) BottomTop() bool
• type Connection
• type Draft
  • func NewDraft(r io.Reader) (*Draft, error)
  • func (ark *Draft) BottomTop(val bool)
  • func (ark *Draft) Ortho(val bool)
  • func (ark *Draft) Provider(name string)
  • func (ark *Draft) Sketch() (string, error)

Types

type Component

type Component struct {
	ID        string `yaml:"id,omitempty"`
	Kind      string `yaml:"kind"`
	Label     string `yaml:"label,omitempty"`
	Impl      string `yaml:"impl,omitempty"`
	Outline   string `yaml:"outline,omitempty"`
	FillColor string `yaml:"fillColor,omitempty"`
	FontColor string `yaml:"fontColor,omitempty"`
	Rounded   bool   `yaml:"rounded,omitempty"`
	// contains filtered or unexported fields
}

Component is a basic architecture unit.

func (*Component) BottomTop

func (co *Component) BottomTop() bool

BottomTop return true if this component must be sketched in a bottom top layout

type Connection

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"`
}

Connection is a link between two components.

type Draft

type Draft struct {
	Title           string       `yaml:"title,omitempty"`
	BackgroundColor string       `yaml:"backgroundColor,omitempty"`
	Components      []Component  `yaml:"components"`
	Connections     []Connection `yaml:"connections,omitempty"`
	Ranks           []struct {
		Name       string   `yaml:"name"`
		Components []string `yaml:"components"`
	} `yaml:"ranks,omitempty"`
	// contains filtered or unexported fields
}

Draft represents a whole diagram.

func NewDraft

func NewDraft(r io.Reader) (*Draft, error)

NewDraft returns a new decoded Draft struct

func (*Draft) BottomTop

func (ark *Draft) BottomTop(val bool)

BottomTop enable the bottom top layout

func (*Draft) Ortho

func (ark *Draft) Ortho(val bool)

Ortho if true edges are drawn as line segments

func (*Draft) Provider

func (ark *Draft) Provider(name string)

Provider sets the Cloud Provider name (one of: aws, gcp, azure).

func (*Draft) Sketch

func (ark *Draft) Sketch() (string, error)

Sketch generates the GraphViz definition for this architecture diagram.