{"id":13593597,"url":"https://github.com/skleanthous/C4-PlantumlSkin","last_synced_at":"2025-04-09T05:31:42.717Z","repository":{"id":144143003,"uuid":"174520772","full_name":"skleanthous/C4-PlantumlSkin","owner":"skleanthous","description":"This library provides skinning to create C4 diagrams using PlantUml","archived":false,"fork":false,"pushed_at":"2020-10-06T09:47:55.000Z","size":436,"stargazers_count":76,"open_issues_count":2,"forks_count":14,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-06T15:43:49.305Z","etag":null,"topics":["architecture","architecture-diagram","architecture-doc","architecture-visualization","c4model","diagram","plantuml","uml","uml-diagrams"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/skleanthous.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}},"created_at":"2019-03-08T10:53:45.000Z","updated_at":"2023-12-03T11:07:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"c69eb60c-d035-4d46-81d2-ab7d3bd47126","html_url":"https://github.com/skleanthous/C4-PlantumlSkin","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skleanthous%2FC4-PlantumlSkin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skleanthous%2FC4-PlantumlSkin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skleanthous%2FC4-PlantumlSkin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skleanthous%2FC4-PlantumlSkin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skleanthous","download_url":"https://codeload.github.com/skleanthous/C4-PlantumlSkin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247986756,"owners_count":21028886,"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","architecture-diagram","architecture-doc","architecture-visualization","c4model","diagram","plantuml","uml","uml-diagrams"],"created_at":"2024-08-01T16:01:21.998Z","updated_at":"2025-04-09T05:31:42.366Z","avatar_url":"https://github.com/skleanthous.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# C4-PlantumlSkin\n\nA skin with related guidance for generating [C4](https://c4model.com) diagrams using the [Plantuml](https://plantuml.com) and related tools.\n\n## Prerequisites\n---\n\nBefore you start, you need to be familiar at minimum with:\n\n- [PlantUML](http://plantuml.com/index)\n- [C4 model](https://c4model.com/)\n\nFirst of all you need to have a Plantuml editor up and running. For this you have multiple options (all of which will work with this):\n\n1. [Local installation](http://plantuml.com/starting)\n1. [Free online editor (PlantText)](https://www.planttext.com/?text=5Osn3SCm30HxJv4C4B5nbSf05WYG2MI9i0XJb22ISCQFyjrTSR-fnM5UURcJ9FQCFlXMpBe-0KQyma5MV7V5aPeOYeNKAkZ96CLASuNN-dZpX5dvd2HGeneEs9quGtFhRf3MqFylaRbTbRuanpAteUIfVm00) \u003c-- Online template ready for you to get started creating C4 models right now!!\n1. [Free online editor from PlantUML](http://www.plantuml.com/plantuml/uml/5Oqn3W8X44LxJw47a6csijh42vXu0XOcGdOO2FCdNb-iNbxptcw84zxaSgkQn3Fxb6i1XZs8Plo6JqNnmurdwWfMXDGRsIaS5QMxqNExlsJ9ghpFgjIYWISTNYLJTmm7fIsC_sLdpOi_) \u003c-- Another template, a click away, ready for you to get started creating C4 models right now!!\n1. [VisualStudio Code Plugin](https://github.com/qjebbs/vscode-plantuml): This plugin allows you to \"embed\" diagrams in your markdown files, which is the best of all worlds in my opinion, and hence really recommended.\n\nOnce you have something running (or just went to PlantText online editor), you can start using Plantuml to create text-driven models and diagrams.\n\n## Quickstart\n---\n\nAssuming that you have an environment that you can use Plantuml, add the following line:\n```plantumlcode\n!includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml\n```\nJust below `@startuml`, and then use the following components with the specified stereotype:\n\n| C4 artifact | PlantUml | Stereotype for internal | Stereotype for external |\n|---|---|---|---|\n| Person | `actor` | `\u003c\u003cInternal\u003e\u003e` | `\u003c\u003cExternal\u003e\u003e` |\n| System | `frame` | `\u003c\u003cSystem\u003e\u003e`, \u003cbr\u003e `\u003c\u003cInternal System\u003e\u003e`, \u003cbr\u003e or `\u003c\u003cInternal\u003e\u003e` | `\u003c\u003cExternal System\u003e\u003e` \u003cbr\u003e or `\u003c\u003cExternal\u003e\u003e` |\n| System | `rectangle` | `\u003c\u003cSystem\u003e\u003e` \u003cbr\u003e or `\u003c\u003cInternal System\u003e\u003e` | `\u003c\u003cExternal System\u003e\u003e` |\n| Containers | `component` | `\u003c\u003cContainer\u003e\u003e`, \u003cbr\u003e `\u003c\u003cInternal Container\u003e\u003e`, \u003cbr\u003e or `\u003c\u003cInternal\u003e\u003e` | `\u003c\u003cExternal Container\u003e\u003e` \u003cbr\u003e or `\u003c\u003cExternal\u003e\u003e` |\n| Containers | `rectangle` | `\u003c\u003cContainer\u003e\u003e` \u003cbr\u003eor `\u003c\u003cInternal Container\u003e\u003e` | `\u003c\u003cExternal Container\u003e\u003e` |\n| Component | `rectangle` | `\u003c\u003cComponent\u003e\u003e` \u003cbr\u003e or `\u003c\u003cInternal Component\u003e\u003e` | `\u003c\u003cExternal Component\u003e\u003e` |\n| Database | `database` | `\u003c\u003cInternal Database\u003e\u003e` \u003cbr\u003e or `\u003c\u003cInternal\u003e\u003e` | `\u003c\u003cExternal Database\u003e\u003e` \u003cbr\u003e or `\u003c\u003cExternal\u003e\u003e` |\n| Queue | `queue` | `\u003c\u003cInternal Queue\u003e\u003e` \u003cbr\u003e or `\u003c\u003cInternal\u003e\u003e` |  `\u003c\u003cExternal Queue\u003e\u003e` \u003cbr\u003e or `\u003c\u003cExternal\u003e\u003e` |\n| Expanded systems, \u003cbr\u003e containers and components | `frame`, \u003cbr\u003e `component`, \u003cbr\u003e or `rectangle` \u003cbr\u003e according to your need | `\u003cExpanded\u003e` | `\u003cExpanded\u003e` |\n\n## Examples\n---\n\nReproduced (as closely as possible from diagrams from [the official C4 model website](https://c4model.com/))\n\n1. System Context diagram\n\n    [Plantuml file for diagram below](./sample/c4-banking-system.puml)\n\n    [Edit this diagram online!](http://www.plantuml.com/plantuml/uml/jP8_Rzim4CLtVefhHgEH5az1OAGDF6G8423PcY0uKsUBCFy8l6FjeEXtxrcIvTG1sYuLj8ZwlSVtUBnXmImbUFF9HUjBGoLxQ4KwlghhZBjguwGjgyAKROf2KIgRGirRJnYbJONhs_dbWyTuS7dSkbW7PA5ShuhpJPsAT4LgEw-wmov6d7Y2hnYLt02_AHgCnKvSYl3KEWPzfJqXZpq2jCVGgL9mIn7MEOKffPs7r93lSvbCLZ1kbAI0ph_o8B--NkurL4G_6YuMyCs0FhFPyl90ZbbcCzClFsa45mV5lRCvSLeBBFUsLNVg4NglCo_QBMr8esVuqVz7Aod3nGDbJcepDNgEjuKb1SeNckikZha6JdCXWns18Skfa-jXajVLu3NfF_OQkjsDWhFZr9OJzCNxj3jjoI09lZlQJO2BwvG3zXF2LIe2Mj9bE6JuF55eRIfH630s47HAqE5R85tfaPVpAW7LDsEWKnUTqP-wt1yL_wlCltVvQSnn2wYQj8lLukDihg0miJbVdmJJ2VnTaTsc5PMylzDACyLcl8Ry70ihQynlJAMYOz8p0KWoD_fTWly5)\n\n    ![System Context Diagram](./sample/c4-banking-system.png)\n\n2. Container diagram\n\n    [Plantuml file for diagram below](./sample/c4-banking-container.puml)\n\n    [Edit this diagram online](http://www.plantuml.com/plantuml/uml/bPDHQzim4CVVzIcq3n3xfK-bcD9sq9Lr2qq6WoQKYtsDHQMJa4waO-oxx-mQrtDeMKiVWlZzzB__HJbF396pi-gJeThc1dEqkcKEwRGi8noAlU4sxtB2M7jY92vgxyhqP168MvzJUNcoM5gWxfRLaw7IGMACvIuRsvG-SyXSrYT5w58K6xQeBu24tElqIr2dQWXiFEbrQvAMVsvVaKj91KCODJw32o8pF27fn-ZTE6Xzudo3jXzDAQZPHrtdnDw9TtRsXHWZWTLBZCbJLIbrXpK3xUKw1uOU8pXyU9b6-C_F0x_gJuH_nL5u-nwguiYQFXU97tP3cqu8G0qsLQL_Aor_CdFm7QGFk7k04AofeL_7PF1n2rKrarBukEFypbZy7wyN6s3OGSBnmvI-6iwEGY2OjsxzezIyw-A-DKs3j8rct_AYclLIARoF7rTwEwBn1rfKOnkbngTI59MUQwVwHy8DtLypXxJzbqtX64rJP3hO75FTXeg-W73pPpXG4lppzklcUhrUhhOlXiL74SRn1Rn3Q5B_YzWGKACFqJ0cpLxicwkBo-sGbODuqmSixWf5wCysb9EXlJYhs_LogwRWu8xDffwQVpb5js2X9VErnStg-xTog37kv0FEkUHbP_y2)\n\n    ![Container diagram](./sample/c4-banking-container.png)\n\n3. Component diagram\n\n    ## _**!!!TODO!!!**_\n\n## Brief description\n---\n\nThis project will help you use the awesome Plantuml tooling to create C4 diagrams for documenting architecture.\n\nC4 defines a set of diagrams (core and supplementary) that are designed to document architecture in a way that is easy to understand and communicate.\n\nPlantuml is a uniquely pleasant-to-use tool to create diagrams from text. The fact that this is a text-driven tool opens up a lot of previously impossible scenarios:\n\n1. It is a *pleasure* to edit\n1. You don't need special tooling\n1. You can keep your domain models side-by-side with your code\n1. You can embed models in your markdown documents in almost all major editors\n1. Did I mention that it is an absolute pleasure to work with Plantuml?\n\nThe only real disadvantage is that positioning can sometimes be [a bit tricky](https://stackoverflow.com/a/48735216).\n\nThis skin allows you to use stereotypes to skin your diagram to be close to what is standard with C4. You can use the `!includeurl` to skin the following diagrams:\n\n1. System Context diagram\n1. Container diagram\n1. Component diagram\n1. System Landscape diagram\n1. Dynamic diagram\n\n## Instructions\n---\n\nAll that is needed to start is to add the following line:\n```plantumlcode\n!includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml\n```\n\n\u003e **NOTE**: The skin sets your diagram type as a Plantuml _deployment diagram_. If you want to add some incompatible artifacts in your diagram, you'll need to add the following statement after the `!includeurl`\n\u003e ```plantumlcode\n\u003e allowmixing\n\u003e ```\n\n1. ### Stereotypes and Legend\n\n    As mentioned above, the way the artifacts get C4 styling is through the use of Plantuml `\u003c\u003cstereotypes\u003e\u003e`. Currently stereotype names are not emitted; instead, a legend is emited at the bottom right. To turn it off, add `!define NO_LEGEND` before the import, like in [this example](https://www.planttext.com/?text=TP91JyCm38Nl-HNU2JXqkUo4gWc93JG9ZOaT4K9fuhNHKcTA70R_dcwexQQMtEBt_DbFoKDa5JZLJamCxYmXh5y_NvRFo_L2Y8abxPB151nKp8TuBsLGnsbfkKf5YXYq9qRYgVQrZ7k7YhZoASh7MRPnpQK1R_UMPAqYOv15iiv8d_YGMEhPz70QB09gLbGwX5L32wJSMrV9yxO6sv-6KS_d5_xbzz3Vrdg_s0LLz_2dyotFE_rFRljQUOHZJuITqZrhrLKkUBsjPLpQHhZ3s905MrQSpM6OKLm7EP-X_IoAuPuZrauKuWOsFbgsdYoLK3L98jmQVoJGYg10K4KHyCigHWFiOG78-cuaGFPUMMEGFaxDpR2hdKSI_EVlTxj-dx6UOPu79DDyiLy0).\n2. ### Represent C4 Person --\u003e with Plantuml Actors\n\n    There is support for two types of actors: Internal and external. The supported stereotypes are:\n    - `\u003c\u003cInternal\u003e\u003e`\n    - `\u003c\u003cExternal\u003e\u003e`\n    \n    The following code:\n\n    ```plantumlcode\n    @startuml\n    !define NO_LEGEND\n    !includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml\n\n    actor Internal          \u003c\u003cInternal\u003e\u003e\n    actor External          \u003c\u003cExternal\u003e\u003e\n    actor InternalPerson    \u003c\u003cInternal Person\u003e\u003e\n    actor ExternalPerson    \u003c\u003cExternal Person\u003e\u003e\n\n    External       -down-\u003e  Internal\n    Internal       -right-\u003e InternalPerson\n    InternalPerson -up-\u003e    ExternalPerson\n\n    @enduml\n    ```\n\n    Produces this outcome:\n\n    ![Actors](./docs/diagrams/actors.png)\n\n3. #### Represent C4 Systems --\u003e with Plantuml Rectangles and Frames\n\n    C4 Systems can be represented using Plantuml `rectangle`s and `frame`s. In both cases the stereotypes that could be used are:\n\n    \u003e **NOTE**: the simplicity of rectangles makes them really useful if you want to avoid the connotations implied by UML artifacts, so they are used to represent other C4 artifacts too\n\n    - `\u003c\u003cInternal System\u003e\u003e`\n    - `\u003c\u003cSystem\u003e\u003e` (an alias to `\u003c\u003cInternal System\u003e\u003e`)\n    - `\u003c\u003cExternal System\u003e\u003e`\n\n    The following code:\n\n    ```plantumlcode\n    @startuml\n    !define NO_LEGEND\n\n    !includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml\n\n    rectangle InternalRectangle \u003c\u003cInternal System\u003e\u003e\n    rectangle ExternalRectangle \u003c\u003cExternal System\u003e\u003e\n\n    frame InternalFrame \u003c\u003cSystem\u003e\u003e\n    frame ExternalFrame \u003c\u003cExternal System\u003e\u003e\n\n    interface InternalInterface \u003c\u003cSystem\u003e\u003e\n    interface ExternalInterface \u003c\u003cExternal System\u003e\u003e\n\n    InternalRectangle  -right-\u003e  ExternalRectangle\n    InternalFrame      -right-\u003e  ExternalFrame\n    InternalInterface  -right-\u003e  ExternalInterface\n\n    ' Positioning hints (down can be abbreviated to D etc)\n    InternalRectangle -[hidden]down-\u003e InternalFrame\n    InternalFrame     -[hidden]down-\u003e InternalInterface\n    ExternalFrame     -[hidden]down-\u003e ExternalInterface\n    @enduml\n    ```\n\n    Produces the outcome:\n\n    ![Systems](./docs/diagrams/systems.png)\n\n4. #### Represent C4 Containers --\u003e with PlantUml Rectangle and Components\n\n    C4 containers can be represented by using plantuml rectangles (and not C4 components which is a bit confusing), which are useful to be shown normally on `System Context`, `Container` and `System Landscape` diagrams. The supported stereotypes are:\n    \n    - `\u003c\u003cInternal Container\u003e\u003e`\n    - `\u003c\u003cContainer\u003e\u003e` (an alias to `Internal Container`)\n    - `\u003c\u003cExternal Container\u003e\u003e`\n\n    The following code:\n\n    ```plantumlcode\n    @startuml\n    !define NO_LEGEND\n\n    !includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml\n\n    component InternalComponent \u003c\u003cInternal Container\u003e\u003e\n    component ExternalComponent \u003c\u003cExternal Container\u003e\u003e\n\n    rectangle InternalRectangle \u003c\u003cInternal Container\u003e\u003e\n    rectangle ExternalRectangle \u003c\u003cExternal Container\u003e\u003e\n\n    interface InternalInterface \u003c\u003cInternal Container\u003e\u003e\n    interface ExternalInterface \u003c\u003cExternal Container\u003e\u003e\n\n    InternalComponent  -right-\u003e ExternalComponent\n    InternalRectangle  -right-\u003e ExternalRectangle\n    InternalInterface --right-\u003e ExternalInterface\n\n    ' Position hints (down can be abbreviated to D etc)\n    InternalComponent -[hidden]down-\u003e InternalRectangle\n    InternalRectangle -[hidden]down-\u003e InternalInterface\n    ExternalRectangle -[hidden]down-\u003e ExternalInterface\n    @enduml\n    ```\n\n    Produces this outcome:\n\n    ![Containers](./docs/diagrams/containers.png)\n\n5. #### Represent C4 components --\u003e with Plantuml rectangles\n\n    C4 components can currently only be represented by Plantuml rectangles. The are only really useful in Component C4 diagrams, but obviously really important. The stereotypes used are:\n\n    - `\u003c\u003cInternal Component\u003e\u003e`\n    - `\u003c\u003cComponent\u003e\u003e` (an alias to `\u003c\u003cInternal Component\u003e\u003e`)\n    - `\u003c\u003cExternal Component\u003e\u003e`\n\n    The following code:\n\n    ```plantumlcode\n    @startuml\n    !define NO_LEGEND\n\n    !includeurl https://raw.githubusercontent.com/skleanthous/C4-PlantumlSkin/master/build/output/c4.puml\n\n    rectangle Internal \u003c\u003cInternal Component\u003e\u003e\n    rectangle External \u003c\u003cExternal Component\u003e\u003e\n    interface Internal \u003c\u003cInternal Component\u003e\u003e as IInternal\n    interface External \u003c\u003cExternal Component\u003e\u003e as IExternal\n\n    Internal          -right-\u003e External\n    IInternal         -right-\u003e IExternal\n\n    'Positioning hints\n    Internal   -[hidden]down-\u003e IInternal\n    External   -[hidden]down-\u003e IExternal\n\n    @enduml\n    ```\n\n    Produces this outcome:\n\n    ![Components](./docs/diagrams/components.png)\n\n6. #### More details\n\n    The above should be enough to get you started. For more info please see:\n\n    - [Items definitions](./src/items)\n    - [PlantUml files for the sample diagrams](./sample/)\n    - [List of all supported artifacts](./docs/diagrams/)\n    - [Canonical SO answer re layout black magic](https://stackoverflow.com/a/48735216)\n\n## work outstanding\n\n1. Complete examples\n1. Add skinning for C4 Code diagrams \n\n## Updates\n\n- [2019-04-12] : Added skinning for sequence diagrams. Add `!define SKIN_SEQUENCE_DIAGRAM` before the include statement. See [a short sample](./sample/sequence.puml)\n- [2019-03-29] : Added skinning to cloud. Either define \"SKIN_CLOUD\" or use `\u003c\u003cExternal\u003e\u003e` stereotype\n- [2019-03-28] : Added support to skin interfaces in systems, containers and components.\n- [2019-03-28] : Fixed bug in legend titles\n- [Initial release] : Skinning support for internal and external, systems, container, components and users. Includes skinning for databases and queues. Also, provides support for expanded items (see [container diagram](#container-diagram) for an expanded system)\n\n## Inspiration / Acknowledgements\n---\n\nOne major acknowledgment is [C4-PlantUML](https://github.com/RicardoNiepel/C4-PlantUML) from [Ricardo Niepel](https://github.com/RicardoNiepel). This is a very good library to work with C4, but I wanted something much more native to Plantuml. Specifically I wanted to be able to work with Plantuml native primitives (`rectangle`, `queue`, `component`, etc.) instead of the \"method\"-like means that this library exposes.\n\nObviously a huge thank you to the awesome teams at [PlantUML](https://plantuml.com).\n\nFinally, to [Simon Brown](https://github.com/simonbrowndotje) for originating the [C4 model](https://c4model.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskleanthous%2FC4-PlantumlSkin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskleanthous%2FC4-PlantumlSkin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskleanthous%2FC4-PlantumlSkin/lists"}