{"id":16419776,"url":"https://github.com/dmytrostriletskyi/diagrams-as-code","last_synced_at":"2025-04-04T19:13:29.508Z","repository":{"id":182772941,"uuid":"669100940","full_name":"dmytrostriletskyi/diagrams-as-code","owner":"dmytrostriletskyi","description":"Diagrams as code: declarative configurations using YAML for drawing cloud system architectures.","archived":false,"fork":false,"pushed_at":"2024-05-27T01:40:35.000Z","size":27435,"stargazers_count":344,"open_issues_count":3,"forks_count":18,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-28T18:14:37.306Z","etag":null,"topics":["architecture","diagrams","diagrams-as-code","graphviz","python","system-design","yaml"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/diagrams-as-code/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmytrostriletskyi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-21T10:43:31.000Z","updated_at":"2025-03-25T14:28:52.000Z","dependencies_parsed_at":"2024-11-16T14:43:24.063Z","dependency_job_id":null,"html_url":"https://github.com/dmytrostriletskyi/diagrams-as-code","commit_stats":{"total_commits":25,"total_committers":3,"mean_commits":8.333333333333334,"dds":0.12,"last_synced_commit":"f7682bbf8cd82ea250aad6b6779fcdde4372a7d8"},"previous_names":["dmytrostriletskyi/diagrams-yaml","dmytrostriletskyi/diagrams-as-code"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmytrostriletskyi%2Fdiagrams-as-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmytrostriletskyi%2Fdiagrams-as-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmytrostriletskyi%2Fdiagrams-as-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmytrostriletskyi%2Fdiagrams-as-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmytrostriletskyi","download_url":"https://codeload.github.com/dmytrostriletskyi/diagrams-as-code/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247234923,"owners_count":20905854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture","diagrams","diagrams-as-code","graphviz","python","system-design","yaml"],"created_at":"2024-10-11T07:25:57.370Z","updated_at":"2025-04-04T19:13:29.491Z","avatar_url":"https://github.com/dmytrostriletskyi.png","language":"Python","funding_links":[],"categories":["Diagrams as Code","Python"],"sub_categories":[],"readme":"`Diagrams as code`: declarative configurations using `YAML` for drawing cloud system architectures.\n\n[![](https://github.com/dmytrostriletskyi/diagrams-as-code/actions/workflows/main.yaml/badge.svg?branch=main)](https://github.com/dmytrostriletskyi/diagrams-as-code/actions/workflows/main.yaml)\n[![](https://img.shields.io/github/release/dmytrostriletskyi/diagrams-as-code.svg)](https://github.com/dmytrostriletskyi/diagrams-as-code/releases)\n[![](https://img.shields.io/pypi/v/diagrams-as-code.svg)](https://pypi.python.org/pypi/diagrams-as-code)\n\n[![](https://pepy.tech/badge/diagrams-as-code)](https://pepy.tech/project/diagrams-as-code)\n[![](https://img.shields.io/pypi/l/diagrams-as-code.svg)](https://pypi.python.org/pypi/diagrams-as-code/)\n[![](https://img.shields.io/pypi/pyversions/diagrams-as-code.svg)](https://pypi.python.org/pypi/diagrams-as-code/)\n\n![](./assets/configurations-architecture-aligned.png)\n\nTable of content:\n\n* [Introduction](#introduction)\n* [Roadmap](#roadmap)\n* [Getting Started](#getting-started)\n  * [How to Install](#how-to-install)\n  * [Examples](#examples)\n  * [Syntax Highlighting](#syntax-highlighting)\n    * [PyCharm](#pycharm)\n    * [VSCode](#vs-code)\n* [Usage](#usage)\n  * [Command Line Interface](#command-line-interface)\n  * [Guide](#guide)\n* [Disclaimer](#disclaimer)\n\n## Introduction\n\n`Diagrams as code` is essentially the process of managing diagrams through code rather than interactively drawing them\non specific web services such as [draw.io](https://app.diagrams.net). It lets you generate the cloud system architecture\nin a **declarative** way with widely used `YAML` syntax (which is de facto a standard for infrastructure and \nconfigurations).\n\nDeclarative method of describing things means that a user simply describes the solution they need, how it should look, \nand everything that would be in the state of the final solution, leaving the process for the software to decide.\n\n`Diagrams as code` brings you the following benefits compared to drawing architecture on your own, it:\n\n* Does not require any knowledge about how to properly draw an architecture diagram. Basically, you just define a set of \n  resources, compose them into groups and set relationships, the rest is done for you.\n* Allows you to track architecture diagram changes with a version control systems such as `Git`.\n* Moves collaboration to the next level: updating an architecture diagram through a pull request with a code review \n  instead of a video session and/or screen sharing.\n* Reduces costs on further updating of an initial architecture diagram. Basically, when you create an image on a web \n  service you have to eventually store two files: `PNG`-like to put into your documentation and `XML` to be able to \n  adjust your image in the future. So, there is no need to care about `XML` anymore.\n* Backups you in case of losing `XML` files as `YAML` files are always stored in a repository.\n* Improves consistency as now a diagram is stored along the code in a repository, the place you visit and work on\n  frequently, and it is easier to keep it up-to-date.\n\nCurrently, the following components are provided:\n\n* Major cloud providers: AWS, Azure, GCP, IBM, Alibaba, Oracle, OpenStack, DigitalOcean and so on.\n* On-Premise, Kubernetes, Firebase, Elastic, SaaS.\n* Programming languages and frameworks.\n\n## Roadmap\n\n* Add support of [C4](https://diagrams.mingrammer.com/docs/nodes/c4).\n* Add support of [Custom](https://diagrams.mingrammer.com/docs/nodes/custom).\n* Add IDEs plugins and/or web user interface for live editing.\n* Add the `JSON Schema` to [Json Schema Store](https://github.com/fox-forks/schemastore).\n* Research Confluence integration to update images from the CI-builds directly.\n* Research ChatGRT integration.\n\n## Getting Started\n\n### How to install\n\nAs the project uses [Graphviz](https://www.graphviz.org) to render the diagram, you need to install it:\n\n* For `Linux` — https://graphviz.gitlab.io/download/#linux\n* For `Windows` — https://graphviz.gitlab.io/download/#windows\n* For `macOS` — https://graphviz.gitlab.io/download/#mac\n\nAfter, you can install the project itself with the following command using `pip3`:\n\n```bash\n$ pip3 install diagrams-as-code\n```\n\n### Examples\n\nYou can find examples of `YAML` configurations in the [examples](https://github.com/dmytrostriletskyi/diagrams-as-code/tree/main/examples) \nfolder. Below are placed are few of them (click on the name to redirect to the configurations file).\n\n| [Web Services on AWS](https://github.com/dmytrostriletskyi/diagrams-as-code/blob/main/examples/web-services-aws.yaml) | [Web Services On-Premise](https://github.com/dmytrostriletskyi/diagrams-as-code/blob/main/examples/web-services-on-premise.yaml) | [Exposed Pods on Kubernetes](https://github.com/dmytrostriletskyi/diagrams-as-code/blob/main/examples/exposed-pods-kubernetes.yaml) |\n|-----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|\n| ![](./assets/web-services-architecture-on-aws.png)                                                                    | ![](./assets/web-services-architecture-on-premise.png)                                                                           | ![](./assets/exposed-pods-architecture-on-kubernetes.png)                                                                           |\n\n| [Message Collecting on GCP](https://github.com/dmytrostriletskyi/diagrams-as-code/blob/main/examples/message-collecting-gcp.yaml) | [Events Processing on AWS](https://github.com/dmytrostriletskyi/diagrams-as-code/blob/main/examples/events-processing-aws.yaml) | [Workers on AWS](https://github.com/dmytrostriletskyi/diagrams-as-code/blob/main/examples/workers-aws.yaml) |\n|-----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|\n| ![](./assets/message-collecting-architecture-on-gcp.png)                                                                          | ![](./assets/events-processing-on-aws.png)                                                                                      | ![](./assets/workers-architecture-on-aws.png)                                                               |\n\n### Syntax Highlighting\n\nWhen you will be writing your own `YAML` files, you likely need a syntax highlighting. Currently, there is no mapping\nof the `YAML` files to a specific schema to enable the syntax highlighting automatically. So, there is a need for\nmanual operation here.\n\n#### PyCharm\n\nFor `PyCharm`, open the settings and proceed to `Languages \u0026 Frameworks, then to `Scheams and DTDs`, then to\n`JSON Schema Mappings`. After, create a new schema, name it `Diagrams as code`, choose\n`JSON Schema version 7`, paste `https://raw.githubusercontent.com/dmytrostriletskyi/diagrams-as-code/main/json-schemas/0.0.1.json`\nto the `Schema file or URL` field and click `Apply`:\n\n\u003cdetails\u003e\n  \u003csummary\u003eOpen Illustration\u003c/summary\u003e\n\n  ![](./assets/json-schema-settings.png)\n\u003c/details\u003e\n\nRight after then, open a `YAML` file and click on `No JSON schema` at to bottom-right corner:\n\n\u003cdetails\u003e\n  \u003csummary\u003eOpen Illustration\u003c/summary\u003e\n\n  ![](./assets/down-panel-json-schema.png)\n\u003c/details\u003e\n\nIt will open a panel where you can choose the newly created schema with the name `Diagrams as code`:\n\n\u003cdetails\u003e\n  \u003csummary\u003eOpen Illustration\u003c/summary\u003e\n\n  ![](./assets/panel-json-schema.png)\n\u003c/details\u003e\n\nAs a result, you will experience syntax highlighting when typing:\n\n\u003cdetails\u003e\n  \u003csummary\u003eOpen Illustration\u003c/summary\u003e\n\n  ![](./assets/syntax-highlight.png)\n\u003c/details\u003e\n\n#### VS Code\n\nFor `VS Code`, install the [RedHat YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) extension and include the following line in the top of your diagrams yaml file:\n\n```yaml\n# yaml-language-server: $schema=https://raw.githubusercontent.com/dmytrostriletskyi/diagrams-as-code/main/json-schemas/0.0.1.json\n```\n\n## Usage\n\n### Command Line Interface\n\nTo draw an architecture, call `diagrams-as-code` command line interface, providing a path to a `YAML` file with \nconfigurations. The drawing will be saved in the folder the command line interface was executed from.\n\n```bash\n$ diagrams-as-code examples/web-services-aws.yaml\n```\n\n### Guide\n\nPlease, check [all-fields.yaml](./examples/all-fields.yaml) as the example to see all possible configurations\nbefore diving into a detailed explanation about them (and [this](./assets/all-fields.jpg) is the result image).\n\nA `YAML` file conceptually contains two configurations: generic information such as a name of a diagram, a format of an \nimage to be generated, style and resources themselves such as `AWS` and `Kubernetes` resources, `Nginx`, `ElasticSearch`\nand all other things you actually want to draw, and relationships among them.\n\n```yaml\ndiagram:\n  name: Web Services Architecture on AWS\n  file_name: web-services-architecture-aws\n  format: jpg\n  direction: left-to-right\n  style:\n    graph:\n      splines: ortho\n    node:\n      shape: circle\n    edge:\n      color: '#000000'\n  label_resources: false\n  open: true\n  resource:\n    ...\n```\n\nGeneric information schema looks like this:\n\n| Field             | Type    | Required | Restrictions                                                        | Default         | Description                                                            |\n|-------------------|---------|----------|---------------------------------------------------------------------|-----------------|------------------------------------------------------------------------|\n| `name`            | String  | Yes      | -                                                                   | `PNG`           | A name of the diagram which is shown in the image.                     |\n| `file_name`       | String  | No       | -                                                                   | -               | A file name of the image that would be created.                        |\n| `format`          | String  | No       | `png`, `jpg`, `svg`, `pdf`, `dot`                                   | `png`           | A format of the image that would be created.                           |\n| `direction`       | String  | No       | `left-to-right`, `right-to-left`, `top-to-bottom`, `bottom-to-top`  | `left-to-right` | A direction of the diagram's resource.                                 |\n| `style`           | Object  | No       | -                                                                   | -               | Style of the diagram.                                                  |\n| `label_resources` | Boolean | No       | -                                                                   | `false`         | Whether to label the diagram's resources such as `EC2` or `PodConfig`. |\n| `open`            | Boolean | No       | -                                                                   | `false`         | Whether to open the diagram's image after creating it.                 |\n| `resources`       | List    | Yes      | -                                                                   | -               | Resources of the diagram.                                              |\n\n`style` is responsible for styling overall diagram such as a background color or choosing between curvy or straight \narrows. It should go as a nested object of parameters as key/value of [Graphviz's attributes](https://graphviz.org/doc/info/attrs.html). \n\nIts schema looks like:\n\n| Field   | Type   | Required | Restrictions                                                       | Default | Description      |\n|---------|--------|----------|--------------------------------------------------------------------|---------|------------------|\n| `graph` | Object | No       | [Those](https://graphviz.org/docs/graph/) parameters as key/value. | -       | A graph styling. |\n| `node`  | Object | No       | [Those](https://graphviz.org/docs/nodes/) parameters as key/value. | -       | A node styling   |\n| `edge`  | Object | No       | [Those](https://graphviz.org/docs/edges/) parameters as key/value. | -       | An edge styling. |\n\n`resources` is responsible for specifying a list of resources on a diagram and relationships among them. Each resource\nhas a unique identifier, name and type. Name will be shown on a diagram under the specific resource:\n\n```yaml\ndiagram:\n  resources:\n    - id: elb\n      name: ELB\n      type: aws.network.ELB\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eOpen Illustration\u003c/summary\u003e\n\n  ![](./assets/guide-resource.png)\n\u003c/details\u003e\n\nIdentifier will be used by other resources to set a relationship direction's type among them:\n\n```yaml\ndiagram:\n  resources:\n    - id: dns\n      name: DNS\n      type: aws.network.Route53\n      relates:\n        - to: elb\n          direction: outgoing\n    - id: elb\n      name: ELB\n      type: aws.network.ELB\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eOpen Illustration\u003c/summary\u003e\n\n  ![](./assets/guide-resource-relationship.png)\n\u003c/details\u003e\n\nThere is also a type named `group`. It is not a specific resource, it is rather a group **of** resources. It is needed\nfor other resources to be able to have a relationship with all group's resources at once. Each group's resource can have\nseparate relationships as well:\n\n```yaml\ndiagram:\n  resources:\n    - id: elb\n      name: ELB\n      type: aws.network.ELB\n      relates:\n        - to: graphql-api\n          direction: outgoing\n    - id: graphql-api\n      name: GraphQL API\n      type: group\n      of:\n        - id: first-api\n          name: GraphQL API №1\n          type: aws.compute.ECS\n        - id: second-api\n          name: GraphQL API №2\n          type: aws.compute.ECS\n        - id: third-api\n          name: GraphQL API №3\n          type: aws.compute.ECS\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eOpen Illustration\u003c/summary\u003e\n\n  ![](./assets/guide-group.png)\n\u003c/details\u003e\n\nThere is also a type named `cluster`. It is needed to separate multiple resources or groups logically: for instance,\nthere might be a cluster of different APIs composed as groups, a cluster of databases and a cluster of caches.\n\n\u003e Pay attention that to refer a cluster resource, there are the following identifiers `web-services.graphql-api` and \n\u003e `web-services.rest-api` what means that you need to chain identifiers of nested resources through a dot to identify a \n\u003e resource you build a relationship with.\n\n```yaml\ndiagram:\n  resources:\n    - id: elb\n      name: ELB\n      type: aws.network.ELB\n      relates:\n        - to: web-services.graphql-api\n          direction: outgoing\n        - to: web-services.rest-api\n          direction: outgoing\n    - id: web-services\n      name: Web Services\n      type: cluster\n      of:\n        - id: graphql-api\n          name: GraphQL API\n          type: group\n          of:\n            - id: first-api\n              name: GraphQL API №1\n              type: aws.compute.ECS\n            - id: second-api\n              name: GraphQL API №2\n              type: aws.compute.ECS\n            - id: third-api\n              name: GraphQL API №3\n              type: aws.compute.ECS\n        - id: rest-api\n          name: REST API\n          type: group\n          of:\n            - id: first-api\n              name: REST API №1\n              type: aws.compute.EC2\n            - id: second-api\n              name: REST API №2\n              type: aws.compute.EC2\n            - id: third-api\n              name: REST API №3\n              type: aws.compute.EC2\n    - id: databases\n      name: Databases\n      type: cluster\n      of:\n        - id: leader\n          name: Leader\n          type: aws.database.RDS\n          relates:\n            - to: databases.follower\n              direction: undirected\n        - id: follower\n          name: Follower\n          type: aws.database.RDS\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eOpen Illustration\u003c/summary\u003e\n\n  ![](./assets/guide-cluster.png)\n\u003c/details\u003e\n\nBasically, to recap and also clarify:\n\n* There are resources, groups (of resources or other groups) and clusters (of resources, groups or other clusters).\n* You can build a relationship between resource to resource and resource to group (and vice versa), it is impossible to\n  relate to a cluster.\n* You should chain identifiers of nested resources through a dot to identify a resource you build a relationship to.\n\n`resources` schema looks like this:\n\n| Field     | Type   | Required | Restrictions                                                                                        | Default | Description                              |\n|-----------|--------|----------|-----------------------------------------------------------------------------------------------------|---------|------------------------------------------|\n| `id`      | String | Yes      | -                                                                                                   | -       | A unique identifier of the resource.     |\n| `name`    | String | Yes      | -                                                                                                   | -       | A name of the resource.                  |\n| `type`    | String | Yes      | One of the [those](https://github.com/dmytrostriletskyi/diagrams-as-code/tree/main/docs/resources). | -       | A type of the resource.                  |\n| `relates` | Object | No       | -                                                                                                   | -       | A relationship to a resource or a group. |\n\nThis is the table of all available types by a category:\n\n| Name          | Docs                                                  |\n|---------------|-------------------------------------------------------|\n| Alibaba Cloud | [alibaba_cloud.md](./docs/resources/alibaba_cloud.md) |\n| AWS           | [aws.md](./docs/resources/aws.md)                     |\n| Azure         | [azure.md](./docs/resources/azure.md)                 |\n| DigitalOcean  | [digital_ocean.md](./docs/resources/digital_ocean.md) |\n| Elastic       | [elastic.md](./docs/resources/elastic.md)             |\n| Firebase      | [firebase.md](./docs/resources/firebase.md)           |\n| Flowchart     | [flowchart.md](./docs/resources/flowchart.md)         |\n| GCP           | [gcp.md](./docs/resources/gcp.md)                     |\n| Generic       | [generic.md](./docs/resources/generic.md)             |\n| IBM           | [ibm.md](./docs/resources/ibm.md)                     |\n| Kubernetes    | [kubernetes.md](./docs/resources/kubernetes.md)       |\n| OCI           | [oci.md](./docs/resources/oci.md)                     |\n| On-Premise    | [on_premise.md](./docs/resources/on_premise.md)       |\n| OpenStack     | [open_stack.md](./docs/resources/open_stack.md)       |\n| Outscale      | [outscale.md](./docs/resources/outscale.md)           |\n| Programming   | [programming.md](./docs/resources/programming.md)     |\n| SaaS          | [saas.md](./docs/resources/saas.md)                   |\n\n`relates` schema looks like:\n\n| Field       | Type   | Required | Restrictions                                          | Default   | Description                                               |\n|-------------|--------|----------|-------------------------------------------------------|-----------|-----------------------------------------------------------|\n| `to`        | String | Yes      | -                                                     | -         | A chain of identifiers to a resource via a dot from root. |\n| `direction` | String | Yes      | `incoming`, `outgoing`, `bidirectional`, `undirected` | -         | A direction of a relationship.                            |\n| `label`     | String | No       | -                                                     | -         | A label of a relationship.                                |\n| `color`     | String | No       | `Hexadecimal color` with the `#` symbol.              | `#2D3436` | A color of a relationship.                                |\n| `style`     | String | No       | -                                                     | -         | A style of a relationship.                                |\n\n## Disclaimer\n\n`diagrams-as-code` is a wrapper around the original [diagrams](https://github.com/mingrammer/diagrams). The original `diagrams` \nlets you draw the cloud system architecture in `Python` code. It was born for prototyping a new system architecture \ndesign without any design tools. Under the hood, `diagrams-as-code` parse a `YAML` file and map to a specific set of \n`diagrams`'s functions and classes, and execute them in proper order.\n\nBut you don't have to worry about `diagrams` because `diagrams-as-code` is self-contained and encapsulates it well. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmytrostriletskyi%2Fdiagrams-as-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmytrostriletskyi%2Fdiagrams-as-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmytrostriletskyi%2Fdiagrams-as-code/lists"}