Skip to content

Latest commit

 

History

History
229 lines (145 loc) · 8.51 KB

README.md

File metadata and controls

229 lines (145 loc) · 8.51 KB
Raw

Draft

A commandline tool that generate High Level microservice & serverless Architecture diagrams using a declarative syntax defined in a YAML file.

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

Clients

Networking

Sample YAML file examples/networking.yml.

draft -impl -verbose examples/networking.yml | dot -Gdpi=110 -Tpng > examples/networking.png

Networking

Compute

Sample YAML file examples/compute.yml.

draft -impl -verbose examples/compute.yml | dot -Gdpi=110 -Tpng > examples/compute.png

Compute

Database

Sample YAML file examples/database.yml.

draft -impl -verbose examples/database.yml | dot -Gdpi=110 -Tpng > examples/database.png

Database

Storage

Sample YAML file examples/storage.yml.

draft -impl -verbose examples/storage.yml | dot -Gdpi=110 -Tpng > examples/storage.png

Storage

Security

Sample YAML file examples/security.yml.

draft -impl -verbose examples/security.yml | dot -Gdpi=110 -Tpng > examples/security.png

Security

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

Connections

Twitter

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