As a cloud architect, one of my primary responsibilities is designing SaaS services architecture. This responsibility has proven challenging, even tricky, especially when dealing with Serverless architectures.
I've had numerous cases where I could think of several solution candidates to a problem and needed to choose between the candidates.
Should I use SNS-> SQS pattern? or EventBridge?
Should I use DynamoDB? or Aurora RDS Serverless?
Should I use Elasticache or DynamoDB with DAX?
You see, sometimes, it's not clear what solution candidate is better.
All the solution candidates fulfill the requirements, but each candidate has its pros and cons.
In these use cases, I required clear guidelines to help me differentiate the solutions and make a decision. My manager suggested I write a design template to assist me in decision-making.
That is how this template came into manifestation.
So, in this blog post, you will find my recommended high-level design template that will help you to define and inspect your solutions and eventually choose the one that best fits your requirements.
Documentation Is Key
Yes, it's not fun to write documentation, and it can be time exhausting, BUT it has many benefits.
For starters, documenting your thought process and design choices can help you choose between solutions and offer a clear, unobstructed view of your choices.
Second, it serves as a justification to any future interested party as to the considerations and options at the time of writing.
Third, the product's requirements can change in the future and can affect your solution and architecture. It's always good to specify the requirements you had then since they affect the chosen solution.
And lastly, the cloud is ever-changing. New architectures, services, and service capabilities are released all year long. Concrete and clear documentation can help you refactor the architecture in the future as it points out limitations, hacks, or workarounds you considered and implemented.
Template Structure
Written below is my recommendation for a high-level design template structure.
Feel free to change it as you see fit.
Status
Possible values: [Draft, Under Review, Approved, Implemented, Retired]
It's essential to keep tabs on your design. It's easy to get lost in old designs that are not relevant anymore.
Make sure you start the design with a 'Draft' status.
Once done, it changes to the 'Under Review' status and, once approved, to the 'Approved' status. Once the implementation is completed, the status is changed to the 'Implemented' status.
However, the most crucial state, in my view, is the 'Retired' status.
When you create a new design that supersedes the current 'Implemented' one and makes it redundant, set the status to 'Retired' and add a link to the up-to-date design page.
Terminology
In this section, you should explain any common expressions, definitions, and stakeholder descriptions related to your service.
Imagine that your design documentation is read by developers and architects who are not familiar with your service or problem domain and wish to review it.
Context
In this section, you must describe the problem you wish to solve in a customer-oriented manner.
Assumptions
Describe all the assumptions that are considered during the design process.
The product team must accept these assumptions as they probably affect the overall user experience.
Functional Requirements
This is where it gets interesting.
In this section, you need to define what the service must do and its features and functions.
"Generally, functional requirements describe system behavior under specific conditions". - altexsoft.com
It would be helpful to link here any product team's requirements documentation for reference.
Feel free to challenge the product team and demand a straightforward and clear set of functional requirements, as they are critical for differentiating between possible solutions.
For example:
Handle X concurrent user session per second.
Support the following filter queries in your API call: filter1, filter2, filter3...
Deploy the service to specific regions: region1, region2.
The more precise the requirements are, the better your research and solution comparison is.
Non Functional Requirements
In this section, you need to describe the general properties of the architecture, also known as quality attributes.
You should take into account the following parameters:
Cost - cost estimation per month, considering architecture and concrete product requirements (user sessions per second, etc.). For AWS, use the AWS pricing calculator.
Performance tests - define a set of tests/queries/numerical values that can help estimate real-world performance/bottlenecks.
Resilience
Does it have an automatic backup mechanism? Do you need to build it yourself?
Is it AWS fully managed? Is it highly available? By how many 9's?
Does it support multi-regions?
Multi-tenancy (if applicable) - define the recommended approach to multi-tenancy in the solution (silo, pool, bridge). Read more here.
Compliance - define the minimum required, FedRamp High, SOC2, etc. Does your solution support it or require it?
Quotas - specify architecture limits and essential quotas.
Does it require a new SDK dependency?
Is it simple to integrate and use in your service code?
Ease of deployment - AWS CDK/Serverless/Terraform:
Does it have a high-level AWS CDK construct?
Does it require a VPC?
Does it take long to deploy?
Does it require more time to research best practices -DB schema research, security policies?
Options Considered
For each candidate solution, provide a brief description with links to a sub pages where you provide:
Complete Architecture/flow diagrams of the solution candidate.
Describe how it answers the functional requirements.
Describe in detail all the non-functional requirements specifications, ranging from cost and performance test results to each usage and deployment.
Include any relevant image of the AWS console.
Provide detailed performance test results. Is the solution candidate viable performance wise?
Risk analysis - are you using an alpha SDK? is the AWS service brand new? is the documentation/user experience lacking?. List any possible setback that comes to mind.
Weighted Decision Matrix
The weighted decision matrix turns guesswork and gut feeling into a scientific conclusion backed by numbers.
Since all candidate solutions must satisfy the functional requirements, the focus in this matrix should be the non-functional requirements.
Weights are the value multiplier for each criterion and represent the criteria's importance in our eyes.
Each of the non-functional requirements (one through eight) gets a weight.
For our example, let's use weights of 1-5.
It's essential to discuss this internally with your team and get everybody's approval since these weights affect the final score of the solution.
Each solution receives a mark per criteria. A mark can be between one to three.
For example, 1-3 marks signify:
One represents the bare minimum requirement satisfaction.
Two represents reasonable satisfaction.
Three represents the best in class.
Once the mark is set a criteria, you can calculate the criteria's score by multiplying the weight by the mark.
Let's examine the table below:
We wish to distinguish between two solutions: A and B.
Our non-functional requirements, in this case, are 'resilience', 'ease of use', and 'cost'.
Each requirement receives a weight:
Resilience gets a weight of 3 out of 5
Ease of use 1 (less important to the team in this case)
Cost gets 5 out of 5, which sets it as the most important requirement to the team.
Solution A received the following marks: 3 out of a maximum of 3 for resilience, 3 out of a maximum of 3 for ease of use, and 3 out of 3 for cost. What an overachiever!
Solution B, on the other hand, received 2 out of a maximum of 3 for resilience, 3 out of a maximum of 3 for ease of use, and 2 out of 3 for cost.
The highest-scoring solution is the solution you will declare as the chosen solution.
In this case, solution A is the preferred solution with 27 points.
Decision Summary
In this section, you explain why you chose the selected solution.
It should be the solution that received the most points in the weighted comparison table.
Describe briefly the pros, and cons of the solution.
That's it; the design document is completed.
Did I miss anything? If you have any suggestions or comments, please write them at the comments section below.
Thanks you Meitar Karas for suggesting I build this template and for introducing me to the concept of weighted matrix in decision making.