Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(Diagrams): Added puml diagrams. PE-4847 #63

Merged
merged 6 commits into from
Dec 12, 2023
Merged

docs(Diagrams): Added puml diagrams. PE-4847 #63

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6176e4d
docs: Added puml files for gateway and API diagrams
Bobinstein Nov 20, 2023
ee3bf82
chore: Modified structure to nest source files below generated images
Bobinstein Nov 20, 2023
7766503
chore: added generated docs to gitignore
Bobinstein Nov 20, 2023
5f7edda
docs(diagrams): Updated diagrams based on feedback
Bobinstein Dec 5, 2023
ef454e0
chore: nested C4 definition files to eliminate error messages while g…
Bobinstein Dec 5, 2023
2a8af0b
docs: Updated Gateways Diagram to show different data indexes
Bobinstein Dec 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ test-results.json

# Generated docs
/docs/sqlite/bundles
/docs/diagrams/*.png

# VS Code
/.vscode
Expand Down
8 changes: 4 additions & 4 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ plantuml_version := 1.2023.12
plantuml_jar := plantuml-$(plantuml_version).jar
plantuml_jar_path := vendor/$(plantuml_jar)

dot_pngs := $(patsubst docs/diagrams/%.dot,docs/diagrams/%.png,$(wildcard docs/diagrams/*.dot))
puml_pngs := $(patsubst docs/diagrams/%.puml,docs/diagrams/%.png,$(wildcard docs/diagrams/*.puml))
dot_pngs := $(patsubst docs/diagrams/src/%.dot,docs/diagrams/%.png,$(wildcard docs/diagrams/src/*.dot))
puml_pngs := $(patsubst docs/diagrams/src/%.puml,docs/diagrams/%.png,$(wildcard docs/diagrams/src/*.puml))

all: $(plantuml_jar_path) $(dot_pngs) $(puml_pngs)

Expand All @@ -17,9 +17,9 @@ $(plantuml_jar_path):
curl -L -o $(plantuml_jar_path) https://github.com/plantuml/plantuml/releases/download/v$(plantuml_version)/$(plantuml_jar)

# Render Graphviz dot files
$(dot_pngs): docs/diagrams/%.png: docs/diagrams/%.dot
$(dot_pngs): docs/diagrams/%.png: docs/diagrams/src/%.dot
dot -Tpng -o $@ $<

# Render PlantUML files
$(puml_pngs): docs/diagrams/%.png: docs/diagrams/%.puml
$(puml_pngs): docs/diagrams/%.png: docs/diagrams/src/%.puml
java -jar $(plantuml_jar_path) -o $(CURDIR)/docs/diagrams -tpng $<
83 changes: 83 additions & 0 deletions docs/diagrams/src/C4_definitions/C4_Component.puml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
' convert it with additional command line argument -DRELATIVE_INCLUDE="relative/absolute" 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

' Scope: A single container.
' Primary elements: Components within the container in scope.
' Supporting elements: Containers (within the software system in scope) plus people and software systems directly connected to the components.
' Intended audience: Software architects and developers.

' Colors
' ##################################

!$COMPONENT_FONT_COLOR ?= "#000000"
!$COMPONENT_BG_COLOR ?= "#85BBF0"
!$COMPONENT_BORDER_COLOR ?= "#78A8D8"

!$EXTERNAL_COMPONENT_FONT_COLOR ?= $COMPONENT_FONT_COLOR
!$EXTERNAL_COMPONENT_BG_COLOR ?= "#CCCCCC"
!$EXTERNAL_COMPONENT_BORDER_COLOR ?= "#BFBFBF"

' Styling
' ##################################

UpdateElementStyle("component", $COMPONENT_BG_COLOR, $COMPONENT_FONT_COLOR, $COMPONENT_BORDER_COLOR)
UpdateElementStyle("external_component", $EXTERNAL_COMPONENT_BG_COLOR, $EXTERNAL_COMPONENT_FONT_COLOR, $EXTERNAL_COMPONENT_BORDER_COLOR)

' shortcuts with default colors
!unquoted procedure AddComponentTag($tagStereo, $bgColor="", $fontColor="", $borderColor="", $shadowing="", $shape="", $sprite="", $techn="", $legendText="", $legendSprite="", $borderStyle="", $borderThickness="")
$addElementTagInclReuse("component", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, $techn, $legendText, $legendSprite, $borderStyle, $borderThickness)
!endprocedure
!unquoted procedure AddExternalComponentTag($tagStereo, $bgColor="", $fontColor="", $borderColor="", $shadowing="", $shape="", $sprite="", $techn="", $legendText="", $legendSprite="", $borderStyle="", $borderThickness="")
$addElementTagInclReuse("external_component", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, $techn, $legendText, $legendSprite, $borderStyle, $borderThickness)
!endprocedure

' Layout
' ##################################

SetDefaultLegendEntries("person\nsystem\ncontainer\ncomponent\nexternal_person\nexternal_system\nexternal_container\nexternal_component\nenterprise_boundary\nsystem_boundary\ncontainer_boundary\nboundary")

!procedure LAYOUT_WITH_LEGEND()
hide stereotype
legend right
|<color:$LEGEND_TITLE_COLOR>**Legend**</color> |
|<$PERSON_BG_COLOR> person |
|<$SYSTEM_BG_COLOR> system |
|<$CONTAINER_BG_COLOR> container |
|<$COMPONENT_BG_COLOR> component |
|<$EXTERNAL_PERSON_BG_COLOR> external person |
|<$EXTERNAL_SYSTEM_BG_COLOR> external system |
|<$EXTERNAL_CONTAINER_BG_COLOR> external container |
|<$EXTERNAL_COMPONENT_BG_COLOR> external component |
endlegend
!endprocedure

' Elements
' ##################################

!unquoted procedure Component($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("rectangle", "component", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure

!unquoted procedure ComponentDb($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("database", "component", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure

!unquoted procedure ComponentQueue($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("queue", "component", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure

!unquoted procedure Component_Ext($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("rectangle", "external_component", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure

!unquoted procedure ComponentDb_Ext($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("database", "external_component", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure

!unquoted procedure ComponentQueue_Ext($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("queue", "external_component", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure
103 changes: 103 additions & 0 deletions docs/diagrams/src/C4_definitions/C4_Container.puml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
' convert it with additional command line argument -DRELATIVE_INCLUDE="relative/absolute" 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

' Scope: A single software system.
' Primary elements: Containers within the software system in scope.
' Supporting elements: People and software systems directly connected to the containers.
' Intended audience: Technical people inside and outside of the software development team; including software architects, developers and operations/support staff.

' Colors
' ##################################

!$CONTAINER_FONT_COLOR ?= $ELEMENT_FONT_COLOR
!$CONTAINER_BG_COLOR ?= "#438DD5"
!$CONTAINER_BORDER_COLOR ?= "#3C7FC0"

!$CONTAINER_BOUNDARY_COLOR ?= $BOUNDARY_COLOR
!$CONTAINER_BOUNDARY_BG_COLOR ?= $BOUNDARY_BG_COLOR
!$CONTAINER_BOUNDARY_BORDER_STYLE ?= $BOUNDARY_BORDER_STYLE

!$EXTERNAL_CONTAINER_FONT_COLOR ?= $ELEMENT_FONT_COLOR
!$EXTERNAL_CONTAINER_BG_COLOR ?= "#B3B3B3"
!$EXTERNAL_CONTAINER_BORDER_COLOR ?= "#A6A6A6"

' Styling
' ##################################
UpdateElementStyle("container", $CONTAINER_BG_COLOR, $CONTAINER_FONT_COLOR, $CONTAINER_BORDER_COLOR)
UpdateElementStyle("external_container", $EXTERNAL_CONTAINER_BG_COLOR, $EXTERNAL_CONTAINER_FONT_COLOR, $EXTERNAL_CONTAINER_BORDER_COLOR)

UpdateBoundaryStyle("container", $bgColor=$CONTAINER_BOUNDARY_BG_COLOR, $fontColor=$CONTAINER_BOUNDARY_COLOR, $borderColor=$CONTAINER_BOUNDARY_COLOR, $type="Container")

' shortcuts with default colors
!unquoted procedure AddContainerTag($tagStereo, $bgColor="", $fontColor="", $borderColor="", $shadowing="", $shape="", $sprite="", $techn="", $legendText="", $legendSprite="", $borderStyle="", $borderThickness="")
$addElementTagInclReuse("container", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, $techn, $legendText, $legendSprite, $borderStyle, $borderThickness)
!endprocedure
!unquoted procedure AddExternalContainerTag($tagStereo, $bgColor="", $fontColor="", $borderColor="", $shadowing="", $shape="", $sprite="", $techn="", $legendText="", $legendSprite="", $borderStyle="", $borderThickness="")
$addElementTagInclReuse("external_container", $tagStereo, $bgColor, $fontColor, $borderColor, $shadowing, $shape, $sprite, $techn, $legendText, $legendSprite, $borderStyle, $borderThickness)
!endprocedure

!unquoted procedure UpdateContainerBoundaryStyle($bgColor=$CONTAINER_BOUNDARY_BG_COLOR, $fontColor=$CONTAINER_BOUNDARY_COLOR, $borderColor=$CONTAINER_BOUNDARY_COLOR, $shadowing="", $shape="", $type="Container", $legendText="", $borderStyle="", $borderThickness="")
UpdateBoundaryStyle("container", $bgColor, $fontColor, $borderColor, $shadowing, $shape, $type, $legendText, $borderStyle, $borderThickness)
!endprocedure

' Layout
' ##################################

SetDefaultLegendEntries("person\nsystem\ncontainer\nexternal_person\nexternal_system\nexternal_container\nenterprise_boundary\nsystem_boundary\ncontainer_boundary\nboundary")

!procedure LAYOUT_WITH_LEGEND()
hide stereotype
legend right
|<color:$LEGEND_TITLE_COLOR>**Legend**</color> |
|<$PERSON_BG_COLOR> person |
|<$SYSTEM_BG_COLOR> system |
|<$CONTAINER_BG_COLOR> container |
|<$EXTERNAL_PERSON_BG_COLOR> external person |
|<$EXTERNAL_SYSTEM_BG_COLOR> external system |
|<$EXTERNAL_CONTAINER_BG_COLOR> external container |
endlegend
!endprocedure

' Elements
' ##################################

!unquoted procedure Container($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("rectangle", "container", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure

!unquoted procedure ContainerDb($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("database", "container", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure

!unquoted procedure ContainerQueue($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("queue", "container", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure

!unquoted procedure Container_Ext($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("rectangle", "external_container", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure

!unquoted procedure ContainerDb_Ext($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("database", "external_container", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure

!unquoted procedure ContainerQueue_Ext($alias, $label, $techn="", $descr="", $sprite="", $tags="", $link="")
$getElementLine("queue", "external_container", $alias, $label, $techn, $descr, $sprite, $tags, $link)
!endprocedure

' Boundaries
' ##################################

!unquoted procedure Container_Boundary($alias, $label, $tags="", $link="")
!if ($tags != "")
!$allTags = $tags + '+container'
!else
!$allTags = 'container'
!endif
' $type defined via $tag style
Boundary($alias, $label, "", $allTags, $link)
!endprocedure
Loading