entities – design steps

While I always rigorously stick to my preferred template structure in my architecture documentation, the design process is not always strictly in the order of the chapters. The following steps describe the process of architecting the solution.

Step 1

Having written the enterprise architecture canvas article I realized that I could use a tool that helps me keep track of the elements of any enterprise architecture.

So, first step is to outline an information model that can represent the elements on the canvas:

It extends the enterprise architecture canvas to also cover software requirements, which helps when developing new or maintaining existing solutions.

Based on the information model, the next step is to outline a page structure for a web application:

While I often go for single-page-applications, entities will manage large quantities of items organized in a complex structure. And ideally, multiple users will work on different parts simultaneously, which makes me lean towards a more traditional multi-page web application.

Step 2

Today I need to consider concurrency aspects of a multi-user application. Multiple users may find themselves editing the same entity at the same time, either editing its properties or adding/removing some of its children.

One such conflict occurs when two different users both rename a process entity almost simultaneously, but to two different names.

When the first user starts editing the process (changing its name), a new draft version of the process entity is created. When the second user starts editing the same entity, yet another new draft version of the process entity is created.

The user who saves his or her edit first, will update the master process entity, and the draft is deleted. The second user can’t just save his or her edit, because the draft version contains outdated attribute values. So, the the second user must first refresh his or her draft with the recent updated master, and chose between the recently updated process name or the name he or she is trying to save.

Another scenario is that two users each add a child capability under a capability entity, for example one adds “Online sales” under “Sales” and another adds “Shop sales”. When the first user saves the added “Online sales”, it’s added to the master and the draft version is deleted. When the second user saves the added “Shop sales”, the master capability is silently updated with the additional child capability.

Step 3

Having pondered concurrency issues for a while, and acknowledging its enormous impact on the complexity of the design – and being realistic about the chances of ever attracting other users, I’m deciding to circumvent the issue by not allowing multiple users editing the same data altogether.

Step 4

The information model first created in step 1 has now been updated. I have added Account, Invoice and Folder to prepare the design to a future subscription-based payment model.

At this time, both Rider and NET Core components have been recently updated, and the core information model hasn’t needed adjustments (aside from the additions mentioned above) so I’m now starting the coding. Initially, my coding is experimental – I spend too little time coding to ever achieve a level of proficiency that allows me to make all the right choices from the start.

When developing a web application there are always two key choices to make. Single page application or multi page application? And which UI framework to use? In the past I have tried to use DevExtreme from DevExpress Inc, but I always find that I spend too much time relearning it every time I resume my coding between long pauses. Also, it’s a large comprehensive library (large CSS and JS files) that takes unnecessarily long time to load in the user’s browser.

So, in my first take and ended up trying W3, which is simple and leight-weight. Here’s my first take on a sign-in page:

W3 is largely about styling basic HTML, which keeps things simple. And it looks a little like Google’s Material Design, which is nice. So, I’m sticking to W3 and abandoning DevExtreme.

Another choice I made in my first take was to try the multiple page application design. The reasoning being that each specialized page is small and therefore loads fast, whereas the single page of a single-page application ends up becoming large and loads more slowly.

But my initial coding reveals too many drawbacks of the multiple page approach. For example, each time a new page is loaded the user may use the browser’s back-button the reload the previous page, which ends up creating a confusing user experience that is difficult to track by the server-side part of the web application.

The conclusion is that I have to peel back much of my initially written code and find a way to use to strucure the large single page application and possibly find a way to only send partial content to the user’s browser depending on the user’s current context.

Step 5

I’m keeping the skeleton code from step 4 but redesigning the Index.html page as the single page of the entire new application.

First off, I have been contemplating how to best handle errors when submitting data to the server. The sign in page has been enhanced with an initially hidden panel containing a sign in error message. In case of sign in error in the underlying API controller, the error panel is shown.

My first rewrite revealed that it’s difficult to build a Razor page that changes content based on the user’s actions – it’s not practical to conditionally render different parts of the complete page. So, I’m building the single page with the entire content, and use variables and logic to control which elements are visible based on the user’s actions.

To avoid coding too much of the wrong stuff I have outlined a storyboard that identifies which view I have to design and which navigation controls they need to offer a satisfactory user experience for users when they log in or register.

In this step I’m setting these views (with buttons to navigate) up in the single Index.cshtml file, which is rendered into an HTML file when the user accesses the web application URL (including if they refresh their browser).

I’ll assign unique id’s to each <div> element encapsulating a view, and keep a View value in the session that controls which view to show (hiding all others). And when the user navigates, the called Javascript function will hide the current view and show the next view, which the user navigates to.