uml – solution architecture

1 Introduction

1.1 Mission statement

I need a simple web-based UML editor that renders diagrams based on text. This is the most efficient way of making sequence diagrams, which are very cumbersome to draw in conventional drawing applications.

PlantUML is a great solution, but the free web-based editor PlantText shows ads, which I find annoying.

uml is a simple web application that does the same as PlantText, but without ads.

1.2 Glossary

TermDescription
umlThe web application, the solution architecture of whish is documented here.

1.3 References

TopicDescriptionLink
UMLUnified Modeling Language.UML
PlantUMLDiagram rendering engine that uses simple clear text as input.PlantUML
PlantTextOnline editor based on PlantUML (with ads).PlantText

1.4 Releases

VersionRelease dateDescription
1.91October, 2020Latest maintenance release.

2 Solution overview

Users run the web application in their favorite web browser. A cloud-hosted virtual web server loads and runs the service-side .NET Core application, and creates a session to service HTTP requests from the user’s browser. The web application calls the remote PlantUML service to render the user’s UML source text.

@startuml
skinparam monochrome true

actor User
actor Admin

node "User's computer" as PC {
	[Broswer] as browser
}

node "Web server" as WS {
	[HTTP Server] as http
}

node "PlantUML server" as PS {
	[PlantUML service] as service
}

User -> PC
browser -> http
http -> service
Admin -> WS

@enduml

The administrator can shut down the web application on the on the web server, which is necessary to upload new releases.

3 Functionality

The functionality supports the user’s UML diagramming and the administrator’s maintenance activities:

@startuml
skinparam monochrome true

actor User
actor Admin

usecase (View manual) as UC1
usecase (Edit text) as UC2
usecase (Render image) as UC3
usecase (Copy text) as UC4
usecase (Save image) as UC5
usecase (Learn more) as UC6

User -down- UC1
User -down- UC2
User -down- UC3
User -down- UC4
User -down- UC5
User -down- UC6

usecase (Shut down) as UC7

Admin -down- UC7

@enduml

Use caseDescriptionConsequences
View manualOpens the official PlantUML manual in a separate browser tab.The page includes a help button.
Edit textEnables the user to enter and edit text that can be rendered into an UML diagram.The page includes a text area wrapped in the CodeMirror editor.
Render imageRenders the current text into an UML diagram.The page includes a refresh (or render) button that renders the current text and displays the result in a viewing area next to the text area.

A movable divider splits the text and viewing areas.

Since both the text and image areas may be too small to fit their content, they both use scrollbars if necessary to allow the user to manage the content.
Copy textCopy the current text into the computer’s clipboard.The page includes a copy button that copies the current test into the computer’s clipboard.
Save imageSave the currently rendered image to any available storage location.Browsers allow the user to right-click on the currently rendered image to save it to any location.
Learn moreLearn more about the architecture of the uml web application.The page includes a button that opens the web application’s architecture documentation in a separate browser tab.
Shut downStop the running web application threads, and prevent new sessions to start until a new release has been uploaded.The web application checks that the web.config file exists whenever the page is loaded.

The web server runs a cron job that opens the page every 5 minutes.

This means that if and when the administrator wants to shut down the application, he logs into the web server dashboard page, and removes the web.config file. This shuts down the application within 5 minutes.

Removing the web.config files makes the normal page unreachable. It its place, a static index.html page in the root folder redirects the user to a maintenance page.
The screen is laid out as follows:

4 Information

The web application saves the text area content in the browser’s session storage, and reinstates the text area content in case the page is reloaded in the browser.

5 Design constraints

5.1 Life span

As long as the PlantUML rendering service remains in operation.

5.2 Policies

PolicyRationaleConsequences
Minimize costsSince all my development activities are long-running hobby work, costs need to be kept at a minimum, particularly reoccurring subscription costs.uml is developed using the same tools as for developing factors, and is deployed to the same cloud-based hosting service.
Further factors developmentfactors requires an advanced user interface and other technically challenging features. The work with uml needs to further that development by taking on as many of these features on a small scale.uml is developed using the same tools and components as factors.

5.3 Standards

StandardRationaleConsequences
HTTPSTo minimize risk of having the web application blocked by corporate firewalls it uses the HTTPS protocol.A free Let’s Encrypt SSL certificate is applied to the URL in the cloud-based hosting service provider’s administration dashboard.

5.4 Technologies

TechnologyRationaleConsequences
Web applicationWeb applications are accessible to everyone everywhere on all platforms.uml is built as a .NET Core web application.
.NET CoreCross-platform framework that makes it easy to build web applications using C#.

Supported on many affordable hosting platforms.
uml is built using JavaScript and C#.
C#Modern feature-rich object-oriented programming language.uml is developed using a C# development tool.
RiderSubscription-based C# development tool with the same refactoring and coding aids as JetBrains ReSharper for VisualStudio.Imposes a monthly subscription cost, but is deemed worthwhile compared to the free VisualStudio, which requires a ReSharper subscription instead.
DevExtremeFeature-rich user interface component suite that supports Material.

Free for non-commercial use.
The free version can only supports JavaScript (not C# Razor pages).
JavaScriptRequired for using the non-commercial version of DevExtreme.uml may not work in very old outdated web browsers.
Simply.comAn affordable cloud-based platform offering virtualized Windows servers that support .NET Core.Imposes a cost of an annual subscription.

Simply.com doesn’t have .NET Core installed, so uml is deployed with the entire .NET Core runtime library.

6 Design principles

Design principleRationaleConsequences
Prevent new sessions from starting during downtime.Reduces annoying user experiences during downtime.A fallback static index.html file is deployed along with the web application and .NET Core runtime libraries, which gets picked up and returned to the user’s browser if the web application isn’t running.

The static index.html file redirects the user’s browser to a page in the corporate website explaining that uml is down for maintenance.

To trigger a controlled shutdown, the administrator removes the web.config file from the web application deployment folder.

A cron job opens the web application page every 5 minutes. The page controller detects if the web.config file has been deleted, does a controlled shutdown, and redirects the user to the corporate maintenance page.

Ongoing sessions in users’ browsers will fail to render text into UML diagrams during downtime, but will retain the current text until the web server becomes available again.
Use microservices in the designMakes the code more manageable.Each operation is handled by a dedicated service class, which inherits from the .NET Core BaseController classs.

7 Design qualities

7.1 Auditability

Not relevant.

7.2 Compliance

Not relevant.

7.3 Security

The web application doesn’t keep any data in the server, so there’s no information to protect from intruders.

There is no protection from DDoS attacks except whatever may be in place in the hosting provider’s infrastructure.

7.4 Integrity

Since no data is stored anywhere, there’s no integrity to protect.

7.5 Authentication

Not relevant.

7.6 Authorization

Not relevant.

7.7 Non-repudiation

Not relevant.

7.8 Usability

Good usability is achieved through several design choices:

  • The toolbar sticks to the top of the browser’s viewport area so it doesn’t disappear due to scrolling.
  • A draggable divider separates the text and the diagram, allowing the user decide where to split between the text and image areas.

7.9 Concurrency

The render (refresh) button in the toolbar is disabled while waiting for the results to be returned and displayed. This minimized the risk that the user accidentally generates a lot of concurrent rendering activity.

7.10 Capacity

To bypass some corporate firewalls’ limitation on HTTP GET header length, the rendering service is called using HTTP POST.

7.11 Performance

Performance is only limited by two uncontrollable elements:

  • The Simply.com hosting provider, specifically how fast the hosted IIS spins up the web server when a user loads the web application after it has been stopped due to inactivity. To prevent the server from falling to sleep, a cron job opens the web applications every 5 minutes.
  • The speed with which the cloud-based rendering service renders and returns the generated diagram image.

It may be possible to setup a local UML rendering service as part of the deployment, but it hasn’t been warranted yet.

7.12 Observability

Currently, no observability is implemented. Some overall performance metrics and user activity metrics can be viewed in the Simply.com web server administration dashboard.

However, I do plan to add metrics generation in v2.

7.13 Scalability

The hosting plan can easily be upgraed to utilize more CPU cores and memory if needed.

7.14 Availability

Not a concern.

Should the rendering service turn out to be unreliable, it might be possible to install the rendering engine on the web server for local execution.

7.15 Testability

New versions can be tested locally in the debugger before deployment to the production environment.

7.16 Operability

The Simply.com web server administration dashboard offers the necessary application control features. Specifically, folders can be viewed and files deleted. This can be used to remove the web.config file, which leads to a controlled shutdown of the application backend.

7.17 Recoverability

The JavaScript running in the user’s browser retains the current text in case the server becomes unavailable for rendering, and should reconnect seamlessly once the backend is up and running again.

8 High-level design

8.1 Interfaces

8.1.1 User interface:

ElementLocationDescription
ToolbarTopContains toolbar buttons.
Text areaLeft sideContains the text editor.
DividerMiddleSplits the two areas. Can be dragged left and right to resize the text and image areas.
Image areaRight sideContains the rendered image.
Toolbar buttonPositionDescription
HelpFirst from leftOpens the PlantUML manual in a separate browser tab.
Refresh imageSecond from leftRenders the current text.
Copy textThird from leftSelects and copies the current text into the computer’s clipboard.
AboutRight sideOpens the corporate website uml introduction page in a separate browser tab.

8.2 Structure

Significant components:

@startuml
skinparam monochrome true
hide empty attributes
hide empty methods

class "Program" as program
class "Startup" as startup

package index.html <<Rectangle>>{
}

package "Pages"
{
	class "Index" as index
	class "PageModel" as page
	page ^-- index
}

package "Services"
{
	class "ControllerBase" as controller

	class "RenderingService" as renderer
	{
		Render( text )
	}
	controller ^-- renderer

	class "MetricsService" as metrics
	{
		Write( start, stop )
	}
	controller ^-- metrics
}

program -down-> startup

package "DevExtreme" {}
index -down-> DevExtreme

package "CodeMirror" {}
index -down-> CodeMirror

package "jQuery" {}
index -down-> jQuery

@enduml

8.2.1 index.html

This static HTML file is the fallback HTTP response from the web server in case the .NET Core web application isn’t running. It contains a few lines of JavaScript that redirects the user’s browser to the maintenance page in the corporate website.

8.2.2 Program

Web application entry point, simply runs the Startup code.

8.2.3 Startup

Sets up the web server with the following configuration:

  • Session lifetime set to 30 days. A long lifetime is preferable to retain current text while waiting for the web server to restart after downtime.
  • Redirect to HTTPS. Ensures use of HTTPS even though the user tries to access the website via HTTP.

8.2.4 Index

The single application page based on the .NET Core Razor concept.

  • index.cshtml
    Contains the HTML (including JavaScript) that constitutes the single web page that is the uml web application.
  • index.cshtml.cs
    The C# code that gets run when a web page is created in a user’s browser.

8.2.5 jQuery

Small JavaScript library that implements shorthand post and get functions.

8.2.6 CodeMirror

JavaScript library (with accompanying CSS stylesheet) that implements an advanced text editor that wraps a native HTML text area element.

8.2.7 DevExtreme

Rich JavaScript library (with accompanying CSS stylesheets and icon definitions) that implements a wide variety of user interface widgets like toolbars, tool buttons etc.

8.2.8 RenderingService

A single-operation microservice based on the .NET Core controller concept. Implements a single POST operation that sends the current text from the JavaScript code in the user’s browser to the remote PlantUML rendering service, and returns the rendered image to the calling JavaScript, which in turn displays the returned image in the viewport’s image area.

8.2.9 MetricsService

Currently not used. But eventually, it will be used to pass metrics from the JavaScript code running in the user’s browser to the web server, which in turn will write the metric to a database on the web server.

8.3 Behavior

8.3.1 Accessing the single-page web application

The user enters the web application’s URL in the browser.

@startuml
skinparam monochrome true
hide footbox

participant "User's browser" as BR
activate BR

BR -> IIS : https://uml.asp.ugleberg.dk/
activate IIS

group try

	IIS -> IIS : load "web.config"
	
	IIS -> Program : Main()
	activate Program
	
	Program -> Startup : Run()
	activate Startup
	deactivate Program
	
	Startup -> Index
	activate Index
	deactivate Startup
	
	alt "web.config" exists
	
		Index -> BR : index.cshtml
		
	else
	
		Index -> ApplicationLifetime : StopApplication()
		activate ApplicationLifetime
		ApplicationLifetime -> IIS : shutdown
		deactivate ApplicationLifetime
		
		Index -> BR : https://ugleberg.dk/uml/down/
	
	end
	deactivate Index
	
else catch

	IIS -> BR : "index.html"
	BR -> BR : https://ugleberg.dk/uml/down/
	
end

destroy IIS

@enduml

8.3.2 index.cshtml.cs

The page defines a toolbar area and an area below, which is split in three: a text area, a divider line, and an image area. The JavaScript executed when the page is loaded does the following:

  • Declare global variables that serve as handles to user interface objects.
  • Create the DevExtreme toolbar object, and link it to the toolbar area in the HTML definition.
  • Add event listeners to capture events that imply dragging the divider or resizing the browser window.
  • Create the CodeMirror object, and link it to the text area defined in the HTML definition.

The JavaScript also defines some helper functions to handle button click events and resizing/dragging events.

9 Development

The source code is stored on the developer’s laptop, and edited in Rider. Documentation is written in WordPress, and published as this page.

Illustrations are developed using the uml web application described in this document. The text source for each illustration is embedded in accordions under each illustration.

10 Testing

Testing is primarily done on the development machine, running the web application locally in the debugger (with Chrome as the browser).

11 Deployment

A build configuration is set up for easy deployment to Simply.com.

To avoid file transfer errors, stop the currently deployed web application by using the Simply.com website administration dashboard to delete the uploaded web.config file.

Either open the web application in a browser, or wait until the cron job that runs every 5 minutes loads it.

When the web application is opened in the cron job or a browser, and the web.config file is missing, the IIS HTTP Server software falls back on the static index.html file, which in turn redirects the browser to the maintenance page.

Once down, deploy the new version using the deploy configuration in Rider.

12 Operation

The only operations feature is the check for the web.config file’s existence, and the immediate stopping the web server if it’s missing – paving the way for a fresh deployment without file transfer errors.