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 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 Releases

VersionRelease dateDescription
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.

While editor can be used by anonymous visitors, signing in to an account enables storing diagrams and the renderings online.

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.

The admin can view the logs to see recent activity and performance, and can manage accounts directly in the database.

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

3. Functionality

Using editor involves only a few actions:

Use caseDescriptionConsequences
Edit textEdit the diagram definition.Use CodeMirror as text editor.

Offer text copy and show help tool buttons.

Place a splitter between the editor and the image.
Draw imageDraw the diagram image.Offer draw image tool button.

Draw PNG image to the right of the splitter. Image can be copied and saved using standard browser features.
Sign inEnter email address.

Prompt for a new password if required.

Show user features.
Offer sign-in tool button when not signed in.

Offer sign-out button when signed in.

When signing in, if account has no password, show a popup that requires the user to set a password. A checkbox can be checked to unmask the password.

Sign-in fails if no password is chosen.
Set passwordShow account, change password.Offer show account tool button.

Show account popup containing fixed email address and initially masked password (revealing only the password length).

Offer button to change the password, which shows an editable field for entering the current password, a field for the new password (initially masked) and a checkbox to unmask the new password. And a save button to complete the password change.
Sign outHide user features.Offer sign-out tool button.

Hide user features upon sign-out.
Manage filesShow files.

Rearrange files.

Select file.

Delete file.
Enable the menu (hamburger) tool button.

In the drawer template, show a tree view with saved files.

Allow drag and drop rearranging.

Allow deleting files.

File record must contain the following fields:
– FileId
– UserId
– IsFolder
– HasFiles
– FolderId
– Name
MonitorView activity log.Write significant events to logger.
ControlShut down the web app.Use SmarterASP.NET dashboard to stop and start the web app.
Manage usersCreate new user.

Force user to change password on next sign-in.

Delete user.
Edit the database table directly in the database windows in Rider.

User records must contain the following fields:
– UserId
– EmailAddress
– HashedPassword
– PasswordLength
– AccountLocked
The screen is laid out as follows:
ElementDescriptionDesign notes
Window titleContains the text “editor vX.X”
Menu buttonDisabled when not signed in. When signed in, shows the user’s files.
Help buttonOpens the PlantUML reference in a separate browser tab.
Refresh buttonDraws the current UML definition (entered in the text area).
Copy buttonCopies the UML definition into the computer’s clipboard. From there, it can be pasted into a document, and saved.
Link buttonDisabled when not signed in. Copies a link to the image file into the computer’s clipboard. From there, the link can be pasted into an image upload dialog to be embedded in a document or webpage.
FilenameBlank when not signed in. When signed in, it shows the current file’s name, and if clicked, it can be edited to edit the filename. The file is continuously saved as it’s edited.The image file (png) is saved in the files folder on the web server with the file id as it’s filename (with the .png filename extension).
Account buttonIf not signed in, it just says [Sign in].

If signed in, it shows the user’s name and dropdown menu with two commands: [Account] and [Sign out].
UGLEBERG.dk buttonOpens the UGLEBERG.dk website on the editor page.
FilesSide out from the left side when the menu button is pressed, which is only enabled when signed in.

Shows a hierarchical last of saved files. The current file is selected in the list.
Use a TreeView to implement the list.

Enable drag and drop rearranging file placements.

Enable deletion of a file.

Load selected file, and show the image.
Text areaDiagram definition is entered here.Wrap a textarea in CodeMirror.
DividerDivides the editor from the image.

Can be dragged sideways.
Use simple event listeners to redraw and resize as the divider is moved.
ImageShows the drawn diagram.
The [Sign in] button shows the sign in form, which initially expects a revisiting user to sign in, but may change to a password chooser if the user is signing in for the first time:
When the user moves focus to the password input field, the email address is looked up on the server. If unknown, the email field is marked as invalid. If recognized, the form may change into the password chooser depending on the state of the account identified by the entered (and valid) email address.

4. Information

The webapp page uses the browser’s session storage to store information about the active session’s state.

On the server, the webapp holds this and more information in a session object.

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 qualities

7.1 Auditability

Not relevant.

7.2 Compliance

Not relevant.

7.3 Security

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 Observability

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