{"id":34082256,"url":"https://github.com/foliant-docs/archeme","last_synced_at":"2026-04-04T08:34:36.681Z","repository":{"id":57411293,"uuid":"242133008","full_name":"foliant-docs/archeme","owner":"foliant-docs","description":"Tool to describe and visualize architechture schemes. May be used as a Python module and as a stand-alone command-line tool.","archived":false,"fork":false,"pushed_at":"2020-04-06T21:25:19.000Z","size":2202,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-04T09:26:08.941Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/foliant-docs.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-21T12:21:03.000Z","updated_at":"2023-10-26T14:19:42.000Z","dependencies_parsed_at":"2022-09-09T22:23:08.960Z","dependency_job_id":null,"html_url":"https://github.com/foliant-docs/archeme","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/foliant-docs/archeme","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Farcheme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Farcheme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Farcheme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Farcheme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foliant-docs","download_url":"https://codeload.github.com/foliant-docs/archeme/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Farcheme/sbom","scorecard":{"id":406049,"data":{"date":"2025-08-11","repo":{"name":"github.com/foliant-docs/archeme","commit":"19b41a89aa8e2dfe5e1bc7a508f57f87da64923d"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3,"checks":[{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":0,"reason":"Found 0/20 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}}]},"last_synced_at":"2025-08-18T21:17:26.659Z","repository_id":57411293,"created_at":"2025-08-18T21:17:26.659Z","updated_at":"2025-08-18T21:17:26.659Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27728040,"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","status":"online","status_checked_at":"2025-12-14T02:00:11.348Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-12-14T12:09:51.244Z","updated_at":"2025-12-14T12:09:53.354Z","avatar_url":"https://github.com/foliant-docs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Archeme\n\nArcheme is a tool to describe and visualize schemes and diagrams. It’s designed primarily for architectural schemes.\n\nArcheme may be used as a stand-alone command-line tool, or as a Python package.\n\nTo describe schemes and diagrams, Archeme provides YAML-based DSL (domain-specific language).\n\nTo draw them, Archeme uses [Graphviz](https://www.graphviz.org/). The engines `dot`, `neato`, and `fdp` are supported.\n\nIn fact, Archeme provides some new abstraction level over Graphviz. Unlike PlantUML, Archeme almost doesn’t limit your ability to use the flexible functionality of Graphviz. However, Archeme provides more convenient means to describe elements of the same types using classes, to specify the relative positions of elements, etc. Using YAML as the base of DSL makes it possible to work with diagram descriptions as with data structures—in Archeme itself and in applications integrated with it. So, Archeme can easily combine several scheme descriptions into one.\n\nBy using SVG as an output format, you may assign hyperlinks to scheme elements and thereby organize relationships between schemes—for example, in accordance with the [C4 methodology](https://c4model.com/).\n\n## Installation\n\nTo install Archeme, run the command:\n\n```bash\n$ pip install archeme\n```\n\nAfter installation, the command `archeme` will be available in your system.\n\n## CLI Usage\n\nCurrently Archeme provides 2 actions (commands):\n\n* `generate`—to generate graph description that can be drawn with Graphviz from YAML-based DSL source;\n* `merge`—to merge (combine, join) multiple DSL sources into a single DSL source.\n\n### The `generate` Command Syntax\n\nGeneralized syntax of the `generate` command is the following:\n\n```bash\n$ archeme generate [-c|--config \u003cconfig_file\u003e] -i|--input \u003cinput_file\u003e -o|--output \u003coutput_file\u003e [-d|--draw \u003cformat\u003e]\n```\n\nThe `-i`/`--input` and `-o`/`--output` arguments are required, other arguments are optional.\n\nThe `-i`/`--input` parameter is used to specify YAML-based DSL source.\n\nThe `-o`/`--output` parameter points to the output file—graph description for Graphviz.\n\nYou may specify an optional config file by using the `-c`/`--config` argument. Both config and scheme description files use the same YAML-based DSL. It’s recommended to use a separate config file to specify some common settings that may be reused in multiple scheme descriptions of the same style. If both config file and scheme description set the parameter of the same name, the value specified in scheme description will override the value specified in config.\n\nIf the `-d`/`--draw` argument is given, Archeme will try to call Graphviz to draw an image from generated graph description, and the Graphviz calling command will be displayed. By default, Archeme doesn’t call Graphviz to visualize generated graph descriptions. The `-d`/`--draw` argument may take any output format value allowed by Graphviz (`png`, `svg`, etc.). By default, the `dot` engine is used. You may specify the necessary engine explicitly in DSL, see below.\n\n### The `merge` Command Syntax\n\nGeneralized syntax of the `merge` command is more simple:\n\n```bash\n$ archeme merge -i|--input \u003cinput_file\u003e -o|--output \u003coutput_file\u003e\n```\n\nThe command takes 2 mandatory arguments: `-i`/`--input` for input YAML-based DSL file, and `-o`/`--output` for output YAML-based DSL file. Output files of the `merge` command should be used as input files for the `generate` command. YAML-based DSL is described below.\n\n## YAML-Based DSL\n\n* See also: [Archeme DSL Quick Reference](https://github.com/foliant-docs/archeme/blob/master/dsl_reference.md)\n\nTo describe schemes and diagrams, YAML-based DSL is provided.\n\nDSL, same as Graphviz, operates the graph theory terms: so, *graph* is the whole drawing; *node* is a functional component of a scheme or a diagram; *cluster* is a group of nodes that is usually highlighted visually; *edge* is a line that represents a relation between two nodes.\n\nDSL may be used to:\n\n* specify common settings of multiple elements;\n* define scheme structure and relations between elements;\n* describe each separate element—node, cluster, edge;\n* set relative positions of elements;\n* describe how it’s needed to combine multiple scheme descriptions into a single one.\n\n### Common Setting\n\nCommon settings for multiple elements usually should be specified in the config file.\n\n#### Graphviz Engine\n\nThe `engine` parameter sets the certain Graphviz engine to draw images. Archeme supports the `dot`, `neato`, and `fdp` engines. The default engine is `dot`.\n\nCode example:\n\n```yaml\nengine: neato\n```\n\nYou may read about the difference between engines in the [Graphviz documentation](https://www.graphviz.org/about/).\n\nIn relation to architectural schemes:\n\n* `dot` is suitable for models with hierarchical relations; using `dot`, you can’t strictly control relative positions of elements—the positions depend of ranks of elements; `dot` supports clusters;\n* `neato` allows to set strict fixed positions to each node; it doesn’t support clusters;\n* `fdp` is similar to `neato` but it supports clusters; however, if clusters are used, `fdp` re-calculates the positions of nodes, they can’t be strictly fixed.\n\n#### Settings Of Elements\n\nIn `elements` section, you may specify common settings of the element of different types—graph, node, cluster, edge. In the simplest case, DSL maps to Graphviz syntax. DSL code example:\n\n```yaml\nelements:\n    graph:\n        newrank: true\n        rankdir: TB\n    node:\n        shape: box\n        fixedsize: true\n        width: 4\n        height: 1\n        style:\n            - filled\n            - rounded\n    edge:\n        dir: both\n        arrowtail: dot\n```\n\nThis example will be converted into the following description for Graphviz:\n\n```\ngraph [newrank = \"true\", rankdir: \"TB\"]\nnode [shape = \"box\", fixedsize = \"true\", width = \"4\", height = \"1\", style = \"filled, rounded\"]\nedge [dir = \"both\", arrowtail = \"dot\"]\n```\n\nAll available parameters for graphs, nodes, edges are described in the [Graphviz documentation](https://www.graphviz.org/doc/info/attrs.html).\n\nIn addition to `graph`, `node`, and `edge` parameters, Archeme supports the analogous `cluster` parameter that allows to specify default settings for clusters. Code example:\n\n```yaml\nelements:\n    cluster:\n        labelloc: b\n        labeljust: l\n        shape: box\n```\n\nNote that you may reduce the number of lines of YAML-based DSL code. So, node settings from the example above may look like this:\n\n```yaml\nnode {shape: box, fixedsize: true, width: 4, height: 1, style: [filled, rounded]}\n```\n\nArcheme allows to specify parameters that take lists of values, in different ways. The constructions `style: [filled, rounded]`, `style: filled, rounded`, `style: [filled]`, `style: filled` are valid.\n\nNote that if a node, cluster, or edge has some custom `style` or another parameter with a list of values, it will **fully** override the default `style` or whatever. This is how it works in Graphviz, and Archeme doesn’t change this behavior for compatibility reasons.\n\nFor example, if the default `style` for nodes is `[filled, rounded]`, and the custom `style` of some node is `dashed`, only `dashed` will be applied to this node.\n\nTo control the settings of elements more flexible, classes are provided.\n\n##### Classes Definition\n\nYou may define one or more classes for each type of elements (`node`, `cluster`, `edge`), and then assign any combination of defined classes to any separate element. Code example:\n\n```yaml\nelements:\n    node:\n        fixedsize: true\n        penwidth: 3\n        classes:\n            generic:\n                shape: box\n                width: 4\n                height: 1\n                style: rounded\n            database:\n                shape: cylinder\n                width: 3\n                height: 3\n            external_network:\n                shape: circle\n                width: 2.5\n                height: 2.5\n                style: filled\n                fillcolor: '#f0f0f0'\n```\n\nIn this example, 3 classes of nodes with the names `generic`, `database`, and `external_network` are defined. Note that using of classes doesn’t disallow to use global default settings.\n\n##### Grid Settings\n\nTo control the relative positions of elements, Archeme provides the ability to describe nodes arrangement as a text grid. In the `elements` section of common settings you may define the horizontal and vertical intervals of the grid step. Code example:\n\n```yaml\nelements:\n    grid:\n        spacing_x: 400\n        spacing_y: 250\n```\n\nThe `spacing_x` parameter sets the horizontal interval and defaults to `500`; the `spacing_y` parameter sets the vertical interval and defaults to `200`. Grid spacing units are *points*; 1 point equals to 1/72 inch.\n\nNote that `neato` and `fdp` engines use different units for the `pos` attribute: points and inches respectively. Archeme takes it into account. If you specify `engine: neato`, do not try to draw the resulting graph description with `fdp`, and vice versa. The `dot` engine doesn’t support positioning at all.\n\n### Scheme Description\n\nTo describe a scheme or a diagram, it’s needed to:\n\n* specify scheme structure—define nodes and clusters;\n* specify relations between nodes—define edges;\n* control the relative positions of nodes:\n    * define a text grid, if the `neato` or `fdp` engine is used;\n    * specify which nodes should have the same rank, if the `dot` engine is used.\n\n#### Structure\n\nTo define nodes and clusters, Archeme DSL provides the `structure` section. You may assign Graphviz attributes and Archeme classes to any node and any cluster. For nodes, the `id` parameter is only required. All other parameters are optional. The `id` parameter is used to assign a text identifier to a certain node.\n\nSimple code example:\n\n```yaml\nstructure:\n    - node:\n        id: first\n    - node:\n        id: second\n```\n\nIn this example, 2 nodes with the identifiers `first` and `second` are defined.\n\nNote that the value of the `structure` parameter must be a list. If the `dot` engine is used, the order of nodes matters for their positioning. If the `neato` or `fdp` engine is used, the order of nodes doesn’t matter.\n\nClusters should be specified at the same level as nodes. Each cluster has nested `structure` that may include nodes and nested clusters. Code example:\n\n```yaml\nstructure:\n    - node:\n        id: first\n    - node:\n        id: second\n    - cluster:\n        structure:\n            - node:\n                id: third\n            - node:\n                id: fourth\n```\n\nThe following code example shows how it’s possible to assign Graphviz attributes and Archeme classes to nodes and clusters:\n\n```yaml\nstructure:\n    - node:\n        id: first\n        label: The First Node\n        class:\n            - amazing\n            - awesome\n    - cluster:\n        label: The Wonderful Cluster\n        style: filled\n        fillcolor: '#cccccc'\n        class: wonderful\n        structure:\n            ...\n```\n\nSingle class name may be specified as a string; multiple class names should be specified as a list.\n\nArcheme merges attributes of classes. Suppose 2 classes are defined as the following:\n\n```yaml\nclasses:\n    amazing:\n        shape: box\n        width: 4\n        height: 1\n        style:\n            - rounded\n            - filled\n    awesome:\n        height: 2\n        style:\n            - dashed\n        fillcolor: '#99ccff'\n```\n\nIf both styles are assigned to some node in the order: `[amazing, awesome]`, the resulting attributes assigned to the node will be:\n\n```yaml\nshape: box\nwidth: 4\nheight: 2\nstyle:\n    - rounded\n    - filled\n    - dashed\nfillcolor: '#99ccff'\n```\n\nSo, the `style` attributes will be combined. Contradicting values of the attributes of the same names will be taken from the last class in the sequence (like `height` in this example).\n\n#### Relations\n\nTo show relations between nodes, edges are used. To define a list of edges, use the `edges` section. Simple code example:\n\n```yaml\nedges:\n    -   tail: first\n        head: second\n    -   tail: second\n        head: third\n```\n\nIn this example, 2 edges are defined. These edges specify relations between 3 nodes with the identifiers `first`, `second`, and `third`.\n\nArcheme uses directed graphs only. So each edge should have a tail (“source,” “beginning”) and a head (“target,” “ending”). For example, if an edge represents interaction between a client and a server, it will be alright if a tail will be assigned to a client, and a head—to a server. However, client requests and server responses may be shown as two different counter-directed edges.\n\nYou may assign Graphviz attributes and classes to edges like in case with nodes and clusters. Example:\n\n```yaml\nedges:\n    -   tail: first\n        head: second\n        label: HTTP API\n        class: two_arrows\n```\n\nArcheme provides extended syntax for the `label` and `xlabel` attributes of edges. You may specify protocol and describe transferred data:\n\n```yaml\n    -   tail: first\n        head: second\n        label:\n            protocol: HTTP\n            data: Admin API\n```\n\nThis code will be transformed into the following construction in a graph description:\n\n```\n\"first\" -\u003e \"second\" [label = \u003c\u003cb\u003eHTTP\u003c/b\u003e\u003cbr /\u003eAdmin API\u003e];\n```\n\n#### Positioning\n\nArcheme implements a powerful concept to control relative positions of scheme elements. Positioning may be described as a multiline text grid. Suppose you have 10 nodes with the identifiers from `first` to `tenth`. Feel free to set their positions in this visual way:\n\n```yaml\ngrid: |\n    -        -    second    sixth\n    first         third\n                  fourth               eighth\n                                       ninth\n                  fifth     seventh\n                                       -\n                                       tenth\n```\n\nIf the engine `neato` or `fdp` is used, the nodes will be strictly positioned with the `pos` attribute. Positions will be calculated using the values of the `elements.grid.spacing_x` and `elements.grid.spacing_y` parameters. A hyphen (`-`) means skipped step if it’s necessary not to place any nodes to the respective horizontal or vertical coordinate.\n\nGrid steps are defined by start positions of node identifiers. So, the nodes `second`, `third`, `fourth`, and `fifth` from the example will be placed to the third horizontal step of the grid.\n\nThe `dot` engine ignores the `pos` attribute, but it allows to place nodes with the same rank to the same hierarchy level of the resulting layout. If the `dot` engine is used, Archeme analyzes a grid and defines groups (subgraphs) of nodes with the same ranks. For the example above and the `elements.graph.rankdir` attribute set to `LR` (left to right), Archeme will generate the following groups:\n\n* `second`, `third`, `fourth`, `fifth`;\n* `sixth`, `seventh`;\n* `eighth`, `ninth`, `tenth`.\n\nIf the `elements.graph.rankdir` attribute is set to `TB` (top to bottom, default in Graphviz), for the example above Archeme will make the following groups:\n\n* `second`, `sixth`;\n* `first`, `third`;\n* `fourth`, `eighth`;\n* `fifth`, `seventh`.\n\nIf you don’t plan to use the engines `neato` and `fdp` to draw a certain scheme, and use only `dot`, you don’t need to describe grids. For `dot`, instead of using grids, you may define groups of nodes of the same ranks explicitly. Example of code that represents the last described case:\n\n```yaml\ngroups:\n    -   - second\n        - sixth\n    -   - first\n        - third\n    -   - fourth\n        - eighth\n    -   - fifth\n        - seventh\n```\n\n### Combining Multiple Schemes\n\nTo combine multiple schemes or diagrams into a single one, the `merge` Archeme command is used. Archeme merges multiple scheme descriptions using the concept of modules.\n\nA module is a scheme description that is used as a part of the structure of the resulting combined scheme description. Optionally some nodes of a certain module may be excluded from the resulting combined scheme description.\n\nEach module should have an identifier. To avoid conflicts when some nodes have the same identifiers in different modules, node identifiers are combined with module identifiers in the resulting scheme description. For example, the node `api` from the module `backend` will get the identifier `backend.api` in the resulting combined scheme description.\n\nArcheme works with modules that are described in separate files. To include some module into the resulting scheme structure, you should specify module identifier and module description file. Code example:\n\n```yaml\nstructure:\n    - module:\n        id: backend\n        file: path/to/backend.yml\n    - module:\n        id: frontend\n        file: path/to/frontend.yml\n```\n\nIt seems most convenient to describe modules in separate files, if Archeme is used as a stand-alone command-line tool. However, Archeme allows to specify a module description directly as a value of the `description` parameter that should be used instead of the `file` parameter. This way may be preferred when Archeme is used as a Python package in a third-party application.\n\nIn this example, 2 modules with the identifiers `backend` and `frontend` are added to the resulting structure.\n\nIf you need not to include some module nodes into the resulting structure, use the optional `exclude` parameter:\n\n```yaml\nstructure:\n    - module:\n        id: frontend\n        file: path/to/frontend.yml\n        exclude:\n            - client_device\n            - cdn\n```\n\nIn this example, the nodes with the identifiers `client_device` and `cdn` of the module `frontend` will not be taken into account in the resulting combined scheme description.\n\nFeel free to add nodes, clusters, and edges to the resulting scheme description in the usual way:\n\n```yaml\nstructure:\n    - module:\n        id: backend\n        file: path/to/backend.yml\n    - module:\n        id: frontend\n        file: path/to/frontend.yml\n    - node:\n        id: middleware\nedges:\n    -   tail: frontend.application\n        head: middleware\n    -   tail: middleware\n        head: backend.api\n```\n\nArcheme provides smart merging of grids. Suppose you need to combine 4 modules with the identifiers `one`, `two`, `three`, and `four`. You may describe a grid that should be used in the resulting scheme description:\n\n```yaml\ngrid: |\n    one      two\n    three    four\n```\n\nArcheme will generate the resulting grid in which, for example, the leftmost nodes of the module `two` will be placed at the same horizontal position as the leftmost nodes of the module `four`.\n\nWhen merging modules, Archeme deeply processes the `structure`, `edges`, `grid`, and `groups` parameters of each module. Common parameters for multiple elements such as `engine` and `elements` will be merged using the simplest algorithm. It’s best to specify them in a separate config file that will not be involved in the merge process.\n\n## Examples\n\nArcheme repository includes [some examples](https://github.com/foliant-docs/archeme/tree/master/examples/) of architectural schemes.\n\nEach example is located in its own folder that has the following structure:\n\n* `source/*`—YAML-based DSL sources;\n* `target/*`—generated graph descriptions for Graphviz, and resulting PNG images;\n* `draw.sh`—shell script that executes the commands which create target files.\n\nPNG images drawn with Graphviz are shown below.\n\n### 1. Foliant Architecture, Simple, Drawn With `neato`\n\n* [Directory with the example files](https://github.com/foliant-docs/archeme/tree/master/examples/01_foliant_architecture_simple/)\n\n![](https://raw.githubusercontent.com/foliant-docs/archeme/master/examples/01_foliant_architecture_simple/target/architecture.png)\n\n### 2. Foliant Architecture, Pretty, Drawn With `neato`\n\n* [Directory with the example files](https://github.com/foliant-docs/archeme/tree/master/examples/02_foliant_architecture_pretty/)\n\n![](https://raw.githubusercontent.com/foliant-docs/archeme/master/examples/02_foliant_architecture_pretty/target/architecture.png)\n\n### 3. Foliant Architecture, With A Cluster, Drawn With `fdp`\n\n* [Directory with the example files](https://github.com/foliant-docs/archeme/tree/master/examples/03_foliant_architecture_with_cluster/)\n\n![](https://raw.githubusercontent.com/foliant-docs/archeme/master/examples/03_foliant_architecture_with_cluster/target/architecture.png)\n\n### 4. Foliant Architecture, With More Clusters, Drawn With `fdp`\n\n* [Directory with the example files](https://github.com/foliant-docs/archeme/tree/master/examples/04_foliant_architecture_more_clusters/)\n\n![](https://raw.githubusercontent.com/foliant-docs/archeme/master/examples/04_foliant_architecture_more_clusters/target/architecture.png)\n\n### 5. Foliant Architecture, With Many Nested Clusters, Drawn With `dot`\n\n* [Directory with the example files](https://github.com/foliant-docs/archeme/tree/master/examples/05_foliant_architecture_many_nested_clusters/)\n\n![](https://raw.githubusercontent.com/foliant-docs/archeme/master/examples/05_foliant_architecture_many_nested_clusters/target/architecture.png)\n\n### 6. Digital Television System, Two Subsystems, Two Styles, Drawn With `dot`\n\n* [Directory with the example files](https://github.com/foliant-docs/archeme/tree/master/examples/06_digital_tv_architecture/)\n\n#### Style 1\n\n##### Subsystem 1\n\n![](https://raw.githubusercontent.com/foliant-docs/archeme/master/examples/06_digital_tv_architecture/target/style_1/ott_dvr_subsystem.png)\n\n##### Subsystem 2\n\n![](https://raw.githubusercontent.com/foliant-docs/archeme/master/examples/06_digital_tv_architecture/target/style_1/service_backend.png)\n\n##### Whole System, Reuses Subsystems Descriptions\n\n![](https://raw.githubusercontent.com/foliant-docs/archeme/master/examples/06_digital_tv_architecture/target/style_1/combined.png)\n\n#### Style 2\n\n##### Subsystem 1\n\n![](https://raw.githubusercontent.com/foliant-docs/archeme/master/examples/06_digital_tv_architecture/target/style_2/ott_dvr_subsystem.png)\n\n##### Subsystem 2\n\n![](https://raw.githubusercontent.com/foliant-docs/archeme/master/examples/06_digital_tv_architecture/target/style_2/service_backend.png)\n\n##### Whole System, Reuses Subsystems Descriptions\n\n![](https://raw.githubusercontent.com/foliant-docs/archeme/master/examples/06_digital_tv_architecture/target/style_2/combined.png)\n\nClouds and client devices icons are made by [iconixar](https://www.flaticon.com/authors/iconixar/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoliant-docs%2Farcheme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoliant-docs%2Farcheme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoliant-docs%2Farcheme/lists"}