diff --git a/.github/workflows/run-percy-tests.yml b/.github/workflows/run-percy-tests.yml index 8433ed4..7aed58d 100644 --- a/.github/workflows/run-percy-tests.yml +++ b/.github/workflows/run-percy-tests.yml @@ -19,7 +19,7 @@ jobs: - name: Process diagrams uses: Timmy/plantuml-action@v1 with: - args: '-v percy -o _parsed' + args: '-v percy -o _parsed -DRELATIVE_INCLUDE="."' - name: Upload run: npx percy upload percy/_parsed env: diff --git a/C4_Component.puml b/C4_Component.puml index 3ed4560..3a681cd 100644 --- a/C4_Component.puml +++ b/C4_Component.puml @@ -1,6 +1,9 @@ -!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml -' uncomment the following line and comment the first to use locally -' !include C4_Container.puml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include %get_variable_value("RELATIVE_INCLUDE")/C4_Container.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml +!endif ' Scope: A single container. ' Primary elements: Components within the container in scope. diff --git a/C4_Container.puml b/C4_Container.puml index ca4ed4f..cfddef9 100644 --- a/C4_Container.puml +++ b/C4_Container.puml @@ -1,6 +1,9 @@ -!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml -' uncomment the following line and comment the first to use locally -' !include C4_Context.puml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include %get_variable_value("RELATIVE_INCLUDE")/C4_Context.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml +!endif ' Scope: A single software system. ' Primary elements: Containers within the software system in scope. diff --git a/C4_Context.puml b/C4_Context.puml index 9e315ec..853a5d6 100644 --- a/C4_Context.puml +++ b/C4_Context.puml @@ -1,6 +1,9 @@ -!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4.puml -' uncomment the following line and comment the first to use locally -' !include C4.puml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include %get_variable_value("RELATIVE_INCLUDE")/C4.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4.puml +!endif ' Scope: A single software system. ' Primary elements: The software system in scope. diff --git a/C4_Deployment.puml b/C4_Deployment.puml index 6c1cb82..ed1638c 100644 --- a/C4_Deployment.puml +++ b/C4_Deployment.puml @@ -1,6 +1,9 @@ -!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml -' uncomment the following line and comment the first to use locally -' !include C4_Container.puml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include %get_variable_value("RELATIVE_INCLUDE")/C4_Container.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml +!endif ' Colors ' ################################## diff --git a/C4_Dynamic.puml b/C4_Dynamic.puml index b41eb63..ff4d007 100644 --- a/C4_Dynamic.puml +++ b/C4_Dynamic.puml @@ -1,6 +1,9 @@ -!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml -' uncomment the following line and comment the first to use locally -' !include C4_Component.puml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include %get_variable_value("RELATIVE_INCLUDE")/C4_Component.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml +!endif ' Scope: Interactions in an enterprise, software system or container. ' Primary and supporting elements: Depends on the diagram scope - diff --git a/README.md b/README.md index fb8b3ae..12950b0 100644 --- a/README.md +++ b/README.md @@ -18,17 +18,12 @@ C4-PlantUML includes macros, stereotypes, and other goodies (like VSCode Snippet At the top of your C4 PlantUML `.puml` file, you need to include the `C4_Context.puml`, `C4_Container.puml` or `C4_Component.puml` file found in the `root` of this repo. -To be independent of any internet connectivity, you can also download the files found in the `root` and reference it locally with +To be independent of any internet connectivity, you can also download the files found in the `root` and activate the local conversion with additional command line argument `-DRELATIVE_INCLUDE="."` (that the local files are included) ```c# -!include path/to/C4.puml -!include path/to/C4_Context.puml -!include path/to/C4_Container.puml -!include path/to/C4_Component.puml +java -jar plantuml.jar -DRELATIVE_INCLUDE="." ... ``` -Just remember to change the `!include` statements at the top of the files. - If you want to use the always up-to-date version in this repo, use the following: ```c# diff --git a/percy/C4_Component Diagram Sample - bigbankplc.puml b/percy/C4_Component Diagram Sample - bigbankplc.puml index bf74c32..93762ff 100644 --- a/percy/C4_Component Diagram Sample - bigbankplc.puml +++ b/percy/C4_Component Diagram Sample - bigbankplc.puml @@ -1,8 +1,10 @@ @startuml -!include ./../C4_Component.puml -!include ./../C4_Container.puml -!include ./../C4_Context.puml -!include ./../C4.puml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include ./../C4_Component.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml +!endif LAYOUT_WITH_LEGEND() diff --git a/percy/C4_Container Diagram Sample - bigbankplc.puml b/percy/C4_Container Diagram Sample - bigbankplc.puml index 799f99f..241c3a5 100644 --- a/percy/C4_Container Diagram Sample - bigbankplc.puml +++ b/percy/C4_Container Diagram Sample - bigbankplc.puml @@ -1,7 +1,10 @@ @startuml -!include ./../C4_Container.puml -!include ./../C4_Context.puml -!include ./../C4.puml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include ./../C4_Container.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml +!endif LAYOUT_TOP_DOWN() 'LAYOUT_AS_SKETCH() diff --git a/percy/C4_Container Diagram Sample - message bus.puml b/percy/C4_Container Diagram Sample - message bus.puml index d57d3d6..89824d0 100644 --- a/percy/C4_Container Diagram Sample - message bus.puml +++ b/percy/C4_Container Diagram Sample - message bus.puml @@ -1,7 +1,10 @@ -@startuml "bigbankplc" -!include ./../C4_Container.puml -!include ./../C4_Context.puml -!include ./../C4.puml +@startuml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include ./../C4_Container.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml +!endif skinparam wrapWidth 200 skinparam maxMessageSize 200 @@ -10,7 +13,6 @@ LAYOUT_TOP_DOWN() 'LAYOUT_AS_SKETCH() LAYOUT_WITH_LEGEND() - Person(customer, Customer, "A customer") System_Boundary(c1, "Customer Information") { diff --git a/percy/C4_Container Diagram Sample - techtribesjs.puml b/percy/C4_Container Diagram Sample - techtribesjs.puml index d78a459..898844e 100644 --- a/percy/C4_Container Diagram Sample - techtribesjs.puml +++ b/percy/C4_Container Diagram Sample - techtribesjs.puml @@ -1,13 +1,15 @@ -@startuml "techtribesjs" -!include ./../C4_Container.puml -!include ./../C4_Context.puml -!include ./../C4.puml +@startuml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include ./../C4_Container.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml +!endif LAYOUT_TOP_DOWN() 'LAYOUT_AS_SKETCH() LAYOUT_WITH_LEGEND() - Person_Ext(anonymous_user, "Anonymous User") Person(aggregated_user, "Aggregated User") Person(administration_user, "Administration User") diff --git a/percy/C4_Context Diagram Sample - bigbankplc-landscape.puml b/percy/C4_Context Diagram Sample - bigbankplc-landscape.puml index 73915dc..b7ca084 100644 --- a/percy/C4_Context Diagram Sample - bigbankplc-landscape.puml +++ b/percy/C4_Context Diagram Sample - bigbankplc-landscape.puml @@ -1,6 +1,10 @@ @startuml -!include ./../C4_Context.puml -!include ./../C4.puml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include ./../C4_Context.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml +!endif 'LAYOUT_TOP_DOWN() 'LAYOUT_AS_SKETCH() diff --git a/percy/C4_Context Diagram Sample - bigbankplc.puml b/percy/C4_Context Diagram Sample - bigbankplc.puml index 98f35cd..a540da0 100644 --- a/percy/C4_Context Diagram Sample - bigbankplc.puml +++ b/percy/C4_Context Diagram Sample - bigbankplc.puml @@ -1,6 +1,10 @@ @startuml -!include ./../C4_Context.puml -!include ./../C4.puml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include ./../C4_Context.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml +!endif LAYOUT_WITH_LEGEND() diff --git a/percy/C4_Context Diagram Sample - enterprise.puml b/percy/C4_Context Diagram Sample - enterprise.puml index dc8d084..b407c2f 100644 --- a/percy/C4_Context Diagram Sample - enterprise.puml +++ b/percy/C4_Context Diagram Sample - enterprise.puml @@ -1,6 +1,10 @@ -@startuml "enterprise" -!include ./../C4_Context.puml -!include ./../C4.puml +@startuml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include ./../C4_Context.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml +!endif LAYOUT_TOP_DOWN() 'LAYOUT_AS_SKETCH() diff --git a/percy/C4_Deployment Diagram Sample - bigbankplc.puml b/percy/C4_Deployment Diagram Sample - bigbankplc.puml new file mode 100644 index 0000000..db9839d --- /dev/null +++ b/percy/C4_Deployment Diagram Sample - bigbankplc.puml @@ -0,0 +1,57 @@ +@startuml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include ./../C4_Deployment.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Deployment.puml +!endif + +AddTagSupport("fallback", $bgColor="#c0c0c0") + +' dynamic legend is used (activated in last line) +' LAYOUT_WITH_LEGEND() + +title Deployment Diagram for Internet Banking System - Live + +Deployment_Node(plc, "Big Bank plc", "Big Bank plc data center"){ + Deployment_Node(dn, "bigbank-api***\tx8", "Ubuntu 16.04 LTS"){ + Deployment_Node(apache, "Apache Tomcat", "Apache Tomcat 8.x"){ + Container(api, "API Application", "Java and Spring MVC", "Provides Internet Banking functionality via a JSON/HTTPS API.") + } + } + Deployment_Node(bigbankdb01, "bigbank-db01", "Ubuntu 16.04 LTS"){ + Deployment_Node(oracle, "Oracle - Primary", "Oracle 12c"){ + ContainerDb(db, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.") + } + } + Deployment_Node(bigbankdb02, "bigbank-db02", "Ubuntu 16.04 LTS", $tags="fallback") { + Deployment_Node(oracle2, "Oracle - Secondary", "Oracle 12c", $tags="fallback") { + ContainerDb(db2, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.", $tags="fallback") + } + } + Deployment_Node(bb2, "bigbank-web***\tx4", "Ubuntu 16.04 LTS"){ + Deployment_Node(apache2, "Apache Tomcat", "Apache Tomcat 8.x"){ + Container(web, "Web Application", "Java and Spring MVC", "Delivers the static content and the Internet Banking single page application.") + } + } +} + +Deployment_Node(mob, "Customer's mobile device", "Apple IOS or Android"){ + Container(mobile, "Mobile App", "Xamarin", "Provides a limited subset of the Internet Banking functionality to customers via their mobile device.") +} + +Deployment_Node(comp, "Customer's computer", "Mircosoft Windows of Apple macOS"){ + Deployment_Node(browser, "Web Browser", "Google Chrome, Mozilla Firefox, Apple Safari or Microsoft Edge"){ + Container(spa, "Single Page Application", "JavaScript and Angular", "Provides all of the Internet Banking functionality to customers via their web browser.") + } +} + +Rel(mobile, api, "Makes API calls to", "json/HTTPS") +Rel(spa, api, "Makes API calls to", "json/HTTPS") +Rel_U(web, spa, "Delivers to the customer's web browser") +Rel(api, db, "Reads from and writes to", "JDBC") +Rel(api, db2, "Reads from and writes to", "JDBC") +Rel_R(db, db2, "Replicates data to") + +SHOW_DYNAMIC_LEGEND() +@enduml \ No newline at end of file diff --git a/percy/C4_Dynamic Diagram Sample - bigbankplc.puml b/percy/C4_Dynamic Diagram Sample - bigbankplc.puml new file mode 100644 index 0000000..207e4ec --- /dev/null +++ b/percy/C4_Dynamic Diagram Sample - bigbankplc.puml @@ -0,0 +1,20 @@ +@startuml +' convert it with additional command line argument -DRELATIVE_INCLUDE="." to use locally +!if %variable_exists("RELATIVE_INCLUDE") + !include ./../C4_Dynamic.puml +!else + !include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Dynamic.puml +!endif + +LAYOUT_WITH_LEGEND() + +ContainerDb(c4, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.") +Container(c1, "Single-Page Application", "JavaScript and Angular", "Provides all of the Internet banking functionality to customers via their web browser.") +Container_Boundary(b, "API Application") { + Component(c3, "Security Component", "Spring Bean", "Provides functionality Related to signing in, changing passwords, etc.") + Component(c2, "Sign In Controller", "Spring MVC Rest Controller", "Allows users to sign in to the Internet Banking System.") +} +Rel_R(c1, c2, "Submits credentials to", "JSON/HTTPS") +Rel(c2, c3, "Calls isAuthenticated() on") +Rel_R(c3, c4, "select * from users where username = ?", "JDBC") +@enduml \ No newline at end of file