Solution architecture

1. Introduction

1.1 Background

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 adds, which I find disturbing.

1.2 Glossary

TermDescription
UMLWidely acknowledged standard for illustrating various aspects of solution architecture.

1.3 References

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

1.4 Change log

VersionPublishedDescription
0.1January, 2020Initial release, very limited functionality.

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 editor application may log to the logger application to help the developer troubleshoot the editor application.

The editor application calls a cloud-hosted service that renders the image of the diagram defined by the text in the editor application’s text editor widget.

Once show in the browser, the user saves the picture locally, and embeds in documents etc.

3. Functionality

Using editor involves only a few actions:

The user edits the text that defines a diagram, and renders it regularly to preview the resulting diagram rendering.

Once satisfied with the diagram, the user saves both the defining text and the diagram image to use it later, and embed it it documents.

4. Information

The editor web application holds its information in the browser’s session storage, which lives as long as the browser remains running.

The session holds the text that defines the diagram, and the rendered diagram image. Also, the session holds the filename under which both the text and the image are saved on the web server’s file store, from where it can be linked to from web pages and documents.

5. Design constraints

5.1 Life span

Not defined. But will be useful to have operational as long as I work with IT, also if factors and logger are dropped before that.

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.editor 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 editor needs to further that development by taking on as many of these features on a small scale.editor is developed using the same tools and components as factors.

5.3 Standards

StandardRationaleConsequences
MaterialChoosing a widely used user interface standard is likely to make editor more approachable to new users.The user interface is built using the DevExtreme component suite.

5.4 Technologies

TechnologyRationaleConsequences
Web applicationWeb applications are accessible to everyone everywhere on all platforms.editor is built using a technology that makes it easy to develop and deploy web applications.
.NET CoreCross-platform that makes it easy to build web applications using C#.

Supported on many affordable hosting platforms.
editor is built using C#.
C#Modern feature-rich object-oriented programming language.editor 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.editor won’t run in very old out-dated web browsers.
SmarterASP.NETAn affordable cloud-based platform offering virtualized Windows 10 servers that support .NET Core.Imposes a cost of an annual subscription.

6. Design principles

Design principleRationaleConsequences
Enable logging from JavaScriptLogging from JavaScript can help finding bugs when experimenting with new features in the JavaScript part of the source code.A JavaScript method is defined in the JavaScript source. It calls a corresponding handler on the controller, which in turn send an HTTP request to write the message to the logger web application.
Measure from user’s point of viewMeasuring a user initiated action in JavaScript increases the accuracy of the measurement, and provides a better measurement of the user’s experience.In JavaScript, the Date() method is used to set the starting time of a critical function. Since the value is in milliseconds, the same technique can record the function’s stop time, and the difference can be logged in a readable text format.

7. Design goals

7.1 Accountability

Not relevant.

7.2 Compliance

Not relevant.

7.3 Confidentiality

Confidentiality can’t be expected since the text defining diagrams is sent to an external service, and the resulting diagram data returned unencrypted.

7.4 Integrity

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

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:

  • Building on DevExtreme and using the built-in Material look and feel ensures a recognizable and approachable user interface.
  • The content is restricted to the actual browser viewport area, avoid that the toolbar disappears due to scrolling.
  • A adjustable divider separates the text and the diagram, allowing the user decide which part to scroll horizontally within its area.

7.9 Concurrency

No concurrent sessions share any resources, so no concurrency issues can arise.

7.10 Capacity

Not relevant.

7.11 Performance

Performance is only limited by two uncontrollable elements:

  • The SmarterASP.NET 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.
  • The speed with which the cloud-based rendering service renders and returns the generated diagram image.

7.12 Measurability

Not relevant.

7.13 Scalability

Not relevant.

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

Not relevant.

7.16 Operability

The web server is remotely manages in SmarterASP.NET’s web-based dashboard. Also, the web application logs when it starts and stops.

7.17 Recoverability

Not relevant.

8. High-level design

8.1 Structure

These are the significant classes:

Program and Startup configures every concurrent web application session.

Log is a static class that offers a single Write method that send the message to the logger web application.

Index inherits from PageModel and has defined the Razor-based home page laying out the screen and defining the JavaScript code.

8.2 Behavior

The user clicks the render button in the toolbar, which generates a click event:

The JavaScript render function is mapped to the click event. It extracts the text from the embedded CodeMirror editor, and sends it to the remote rendering service.

Depending on the result, the render function toggles between the states error message or the rendered image.

9. Development

The source code is stored on the developer’s laptop, and edited in Rider.

10. Testing

Code changes are tested by …

11. Deployment

Zzz

12. Operation

Zzz