Package: diagrams-as-code
Diagrams as code: declarative configurations usingYAMLfor drawing cloud system architectures.Table of content:IntroductionRoadmapGetting StartedHow to InstallExamplesSyntax HighlightingPyCharmVSCodeUsageCommand Line InterfaceGuideDisclaimerIntroductionDiagrams as codeis essentially the process of managing diagrams through code rather than interactively drawing them
on specific web services such asdraw.io. It lets you generate the cloud system architecture
in adeclarativeway with widely usedYAMLsyntax (which is de facto a standard for infrastructure and
configurations).Declarative method of describing things means that a user simply describes the solution they need, how it should look,
and everything that would be in the state of the final solution, leaving the process for the software to decide.Diagrams as codebrings you the following benefits compared to drawing architecture on your own, it:Does not require any knowledge about how to properly draw an architecture diagram. Basically, you just define a set of
resources, compose them into groups and set relationships, the rest is done for you.Allows you to track architecture diagram changes with a version control systems such asGit.Moves collaboration to the next level: updating an architecture diagram through a pull request with a code review
instead of a video session and/or screen sharing.Reduces costs on further updating of an initial architecture diagram. Basically, when you create an image on a web
service you have to eventually store two files:PNG-like to put into your documentation andXMLto be able to
adjust your image in the future. So, there is no need to care aboutXMLanymore.Backups you in case of losingXMLfiles asYAMLfiles are always stored in a repository.Improves consistency as now a diagram is stored along the code in a repository, the place you visit and work on
frequently, and it is easier to keep it up-to-date.Currently, the following components are provided:Major cloud providers: AWS, Azure, GCP, IBM, Alibaba, Oracle, OpenStack, DigitalOcean and so on.On-Premise, Kubernetes, Firebase, Elastic, SaaS.Programming languages and frameworks.RoadmapAdd support ofC4.Add support ofCustom.Add IDEs plugins and/or web user interface for live editing.Add theJSON SchematoJson Schema Store.Research Confluence integration to update images from the CI-builds directly.Research ChatGRT integration.Getting StartedHow to installAs the project usesGraphvizto render the diagram, you need to install it:ForLinux—https://graphviz.gitlab.io/download/#linuxForWindows—https://graphviz.gitlab.io/download/#windowsFormacOS—https://graphviz.gitlab.io/download/#macAfter, you can install the project itself with the following command usingpip3:$pip3installdiagrams-as-codeExamplesYou can find examples ofYAMLconfigurations in theexamplesfolder. Below are placed are few of them (click on the name to redirect to the configurations file).Web Services on AWSWeb Services On-PremiseExposed Pods on KubernetesMessage Collecting on GCPEvents Processing on AWSWorkers on AWSSyntax HighlightingWhen you will be writing your ownYAMLfiles, you likely need a syntax highlighting. Currently, there is no mapping
of theYAMLfiles to a specific schema to enable the syntax highlighting automatically. So, there is a need for
manual operation here.PyCharmForPyCharm, open the settings and proceed toLanguages & Frameworks, then toScheams and DTDs, then toJSON Schema Mappings. After, create a new schema, name itDiagrams as code, chooseJSON Schema version 7, pastehttps://raw.githubusercontent.com/dmytrostriletskyi/diagrams-as-code/main/json-schemas/0.0.1.json`to theSchema file or URLfield and clickApply:Open IllustrationRight after then, open aYAMLfile and click onNo JSON schemaat to bottom-right corner:Open IllustrationIt will open a panel where you can choose the newly created schema with the nameDiagrams as code:Open IllustrationAs a result, you will experience syntax highlighting when typing:Open IllustrationVS CodeForVS Code, install theRedHat YAMLextension and include the following line in the top of your diagrams yaml file:# yaml-language-server: $schema=https://raw.githubusercontent.com/dmytrostriletskyi/diagrams-as-code/main/json-schemas/0.0.1.jsonUsageCommand Line InterfaceTo draw an architecture, calldiagrams-as-codecommand line interface, providing a path to aYAMLfile with
configurations. The drawing will be saved in the folder the command line interface was executed from.$diagrams-as-codeexamples/web-services-aws.yamlGuidePlease, checkall-fields.yamlas the example to see all possible configurations
before diving into a detailed explanation about them (andthisis the result image).AYAMLfile conceptually contains two configurations: generic information such as a name of a diagram, a format of an
image to be generated, style and resources themselves such asAWSandKubernetesresources,Nginx,ElasticSearchand all other things you actually want to draw, and relationships among them.diagram:name:Web Services Architecture on AWSfile_name:web-services-architecture-awsformat:jpgdirection:left-to-rightstyle:graph:splines:orthonode:shape:circleedge:color:'#000000'label_resources:falseopen:trueresource:...Generic information schema looks like this:FieldTypeRequiredRestrictionsDefaultDescriptionnameStringYes-PNGA name of the diagram which is shown in the image.file_nameStringNo--A file name of the image that would be created.formatStringNopng,jpg,svg,pdf,dotpngA format of the image that would be created.directionStringNoleft-to-right,right-to-left,top-to-bottom,bottom-to-topleft-to-rightA direction of the diagram's resource.styleObjectNo--Style of the diagram.label_resourcesBooleanNo-falseWhether to label the diagram's resources such asEC2orPodConfig.openBooleanNo-falseWhether to open the diagram's image after creating it.resourcesListYes--Resources of the diagram.styleis responsible for styling overall diagram such as a background color or choosing between curvy or straight
arrows. It should go as a nested object of parameters as key/value ofGraphviz's attributes.Its schema looks like:FieldTypeRequiredRestrictionsDefaultDescriptiongraphObjectNoThoseparameters as key/value.-A graph styling.nodeObjectNoThoseparameters as key/value.-A node stylingedgeObjectNoThoseparameters as key/value.-An edge styling.resourcesis responsible for specifying a list of resources on a diagram and relationships among them. Each resource
has a unique identifier, name and type. Name will be shown on a diagram under the specific resource:diagram:resources:-id:elbname:ELBtype:aws.network.ELBOpen IllustrationIdentifier will be used by other resources to set a relationship direction's type among them:diagram:resources:-id:dnsname:DNStype:aws.network.Route53relates:-to:elbdirection:outgoing-id:elbname:ELBtype:aws.network.ELBOpen IllustrationThere is also a type namedgroup. It is not a specific resource, it is rather a groupofresources. It is needed
for other resources to be able to have a relationship with all group's resources at once. Each group's resource can have
separate relationships as well:diagram:resources:-id:elbname:ELBtype:aws.network.ELBrelates:-to:graphql-apidirection:outgoing-id:graphql-apiname:GraphQL APItype:groupof:-id:first-apiname:GraphQL API №1type:aws.compute.ECS-id:second-apiname:GraphQL API №2type:aws.compute.ECS-id:third-apiname:GraphQL API №3type:aws.compute.ECSOpen IllustrationThere is also a type namedcluster. It is needed to separate multiple resources or groups logically: for instance,
there might be a cluster of different APIs composed as groups, a cluster of databases and a cluster of caches.Pay attention that to refer a cluster resource, there are the following identifiersweb-services.graphql-apiandweb-services.rest-apiwhat means that you need to chain identifiers of nested resources through a dot to identify a
resource you build a relationship with.diagram:resources:-id:elbname:ELBtype:aws.network.ELBrelates:-to:web-services.graphql-apidirection:outgoing-to:web-services.rest-apidirection:outgoing-id:web-servicesname:Web Servicestype:clusterof:-id:graphql-apiname:GraphQL APItype:groupof:-id:first-apiname:GraphQL API №1type:aws.compute.ECS-id:second-apiname:GraphQL API №2type:aws.compute.ECS-id:third-apiname:GraphQL API №3type:aws.compute.ECS-id:rest-apiname:REST APItype:groupof:-id:first-apiname:REST API №1type:aws.compute.EC2-id:second-apiname:REST API №2type:aws.compute.EC2-id:third-apiname:REST API №3type:aws.compute.EC2-id:databasesname:Databasestype:clusterof:-id:leadername:Leadertype:aws.database.RDSrelates:-to:databases.followerdirection:undirected-id:followername:Followertype:aws.database.RDSOpen IllustrationBasically, to recap and also clarify:There are resources, groups (of resources or other groups) and clusters (of resources, groups or other clusters).You can build a relationship between resource to resource and resource to group (and vice versa), it is impossible to
relate to a cluster.You should chain identifiers of nested resources through a dot to identify a resource you build a relationship to.resourcesschema looks like this:FieldTypeRequiredRestrictionsDefaultDescriptionidStringYes--A unique identifier of the resource.nameStringYes--A name of the resource.typeStringYesOne of thethose.-A type of the resource.relatesObjectNo--A relationship to a resource or a group.This is the table of all available types by a category:NameDocsAlibaba Cloudalibaba_cloud.mdAWSaws.mdAzureazure.mdDigitalOceandigital_ocean.mdElasticelastic.mdFirebasefirebase.mdFlowchartflowchart.mdGCPgcp.mdGenericgeneric.mdIBMibm.mdKuberneteskubernetes.mdOCIoci.mdOn-Premiseon_premise.mdOpenStackopen_stack.mdOutscaleoutscale.mdProgrammingprogramming.mdSaaSsaas.mdrelatesschema looks like:FieldTypeRequiredRestrictionsDefaultDescriptiontoStringYes--A chain of identifiers to a resource via a dot from root.directionStringYesincoming,outgoing,bidirectional,undirected-A direction of a relationship.labelStringNo--A label of a relationship.colorStringNoHexadecimal colorwith the#symbol.#2D3436A color of a relationship.styleStringNo--A style of a relationship.Disclaimerdiagrams-as-codeis a wrapper around the originaldiagrams. The originaldiagramslets you draw the cloud system architecture inPythoncode. It was born for prototyping a new system architecture
design without any design tools. Under the hood,diagrams-as-codeparse aYAMLfile and map to a specific set ofdiagrams's functions and classes, and execute them in proper order.But you don't have to worry aboutdiagramsbecausediagrams-as-codeis self-contained and encapsulates it well.