In the first article of this series, I outlined my goal for these articles, how I want to approach writing back-end services and websites in Azure and how I want you, the reader, to help. In this article, I want to outline the overall architecture for the services and apps. The first part of this article will document the feature request, then the remainder will be about the architecture and the design.
Feature Request Documentation
When I learned software development, the project manager or usually I, wrote feature request documents based on user or marketing requests. This was always the first step in the process. Sure, sometimes I was given a feature request that was one sentence, but it was up to me to write up the details. Unfortunately, what I see these days, is no feature requirements at all. I saw this wave start when Agile started to get popular. I’m not blaming Agile for the lack of documentation, I blame the people that implement Agile incorrectly.
How can you architect or even write code without the complete, thought out requirements for the feature? Recently, at a company I was contracting with, if I even got a feature requirement, it was usually a Visio type document. While this is better than nothing, it wasn’t 100% useful since I still had lots of questions I needed answered first which delayed the project. This is even important for the quality assurance team. How can they test a feature if they have no documentation to tell them what the heck it’s supposed to do?
dotNetTips.com Dev Utility App Rotating Ad Feature Request
We will start off by defining the feature that is requested, in this case by me, since this is my app.
Updatable Rotating Ad Data
Currently, the dotNetTips.com Dev Utility App displays rotating ads at the bottom of the app. Instead of this data being hardcoded in the app, it will come from the cloud. Below are the requirements.
- During app startup, the rotating ad data should be downloaded from the cloud. This data should be cached locally to be displayed at the next app startup or if there isn’t an internet connection.
- Only this app should be able to download ad data from the cloud.
- Rotating ad data
- Message – text to be displayed in the app
- Image – displayed left of the message
- URL – for the user to click on for more information
- Start and end date (optional) – These ads should only be displayed to the user during these dates.
- When the user clicks on an ad, that event should be sent to the cloud for analytics. The user’s country should be recorded. No other user data will be recorded.
- Rotating ad data will be maintained by a secure website.
- Online reports are needed to analyze the number of clicks per ad, grouped by country on a monthly, quarterly and annual basis.
Other requirements are that calls to the cloud should be asynchronous, so it does not slow down the performance of the app. All the service calls and website should be secure. Ad data does not need to be secure.
The Architecture & Design
Now that we have the feature requirements, it’s time to write up the architecture design. This is very important to do before sitting down for meetings or to start coding. Let’s review the n-tier architecture (shown below) that I always start off with before I design any application.
I have been using this type of architecture my entire programming career and it has served me well. I modify this design based on application requirements, not because I’m lazy. I also make sure that my design is future proof as much as possible. What that means is that it’s easily changed base on new feature requests or to add new technology stacks. At the end of this article, I will show an updated design based on the frameworks that we will use for the rest of these articles.
Database Layer
After speaking with some Azure MVP’s, it looks like using Azure Cosmos DB will the best fit for this app. This means dropping the use of Entity Framework (sorry EF fans). I have never used Azure Cosmos DB before, so this will be a learning curve for me for sure and since it is new, it should be of interest to you, the reader. The database should be backed up daily.
Business Layer
This section will be a bit more detailed so… The number one thing that all my business layers start with are the business entities.
Business Entities
To make sure that all the assemblies in this feature can use the same business entities, they should be separated into their own DLL. This includes the classes that will be used to interact with the database.
Microservices
All microservices in this layer will be Azure Functions. The one function that has been identified at this point is one that will process user click messages from a queue. An Azure Queue will be used to capture these messages. When a message hits the queue, that should fire this function to store the message in the database. This will allow a very short response back to the client app.
Web Communication Layer
The communications layer will be created using an App Service in Azure. The two services needed are:
- Retrieve ad data – this read-only service will return current ads plus ads that will be active in the next week.
- Data maintenance – this read-write service is for the website that will be used to create and edit ads. This service could also be used for a mobile app (possibly in the future).
All calls to this layer need to be asynchronous.
User Experience Layer
ASP.NET Core will be used to all the creation and editing of the ad data and the display of reports. The pages required are:
- Default page, show top 5 ads based on user clicks. (this could be made public)
- Secured page to create, edit and disable ads.
- Secured page to report on user clicks.
The goal is to create this UI with Microsoft Blazor. Blazor is a new experimental .NET web framework using C#/Razor and HTML that runs in the browser with WebAssembly. Even though it is in the experimental stage, it looks very promising. If I run into too many issues, I will write the UI in ASP.NET Core using Razor.
Identity Layer
There are a few parts to this layer. The first is the Azure Key Vault. All secrets like database connection strings etc. should be retrieved from the vault. No secrets will be stored in the different layers or in the dotNetTips.com Dev Utility App. Managed Service Identity will be used to secure the calls to the Azure Key Vault.
Since I will be the only user of this app, for now, I’m thinking of keeping calling the services secure by keeping a username and password in Azure Key Vault. This might change when I start coding the UI layer.
Other
All layers should use Application Insights for logging and monitoring the different layers for performance issues and errors.
Final Architecture
Now that I have written up the architecture, below is the new design diagram.
Summary
Like in all projects, things change since I first started thinking about these features and they might change again once coding begins. Here are some of the things I have dropped:
- API Management
I did want to use this since it has so many great features and I wanted to compare it with API Gateway in AWS but it’s expensive for an individual. Its monthly cost is $150. Since the app that will be using this is free, I can’t justify the cost.
- Entity Framework
I’ve been using EF since before it was released and it continues to be my favorite ORM. I had to drop it since it does not support Cosmos DB.
- Event Hub
I might revisit this later, but at this point in the architecture, I don’t see the need for it.
Maybe in the future, I will get to use these frameworks. If I do, I will write separate articles on them. I would like to thank Azure MVP’s Sam Cogan and Vishwas Lele for helping me with this article.
Where Is My Team?
I have not heard anything from my team (you) about my last article. If you have comments or questions, I hope you will email me by clicking here.
Next Article
In the next article I will be coding the database layer with Cosmos DB, so check back here soon.