Milestone 4
The views are all documented using the following five categories.
This is the representation of the view, usually a diagram. It shows software elements and relations between them.
This contains information about every element in the view as shown in Primary Presentation section. The additional information about each element includes Elements and their Properties, Relations and their Properties, Element Interfaces, and Element Behaviour. It may also include interface specifications and behaviour diagrams like sequence diagrams.
This section contains a context diagram that shows the scope of the part of the system represented by this view. Typically, this diagram will show the scope of the view as a box surrounded by other boxes representing external entities. Lines are used to show the relations between the view's part of the system and the external entities.
This is used to describe variability mechanisms that the system is using in the portion described in the view. It will also describe how the variability mechanisms may be used, like how and when (build time, deploy time, run time).
Examples of variability include optional components (e.g., plug-ins, add-ons); configurable replication of components and connectors; selection among different implementations of an element or different vendors; parameterized values set in build flags, .properties files, .ini files, or other config files.
Finally, describe the reasoning behind all significant design decisions within the scope of the view. Additionally, describe any significant alternative decisions that were rejected. Often this reasoning will include assumptions, constraints, results of analyses or experiments, and any requirements that were architecturally significant enough to affect the view.
The diagram above shows a low-detail representation of the Login/Register microservice and how other applications can interact with it in a meaningful way. Users can interact with the login and registration system using the frontend and other microservices can interact with the validate service by authenticating with an API key.
N/A
The login/register microservice is defined as Infrastructure as Code written in the AWS CDK.
This architecture allows the login/register microservice to be changed in place without updating the frontend or other microservices.
Triage Microservice
- The main component that implements the basic symptom triaging based on user input
TriageResult
- An interface that requires a function to preform the triage and return a result
Input Validation
- Another interface that requires a function to validate form input ensuring all keys are present
UserLogin validation
- An interface that requires a function to validate the user login session. It must take a token from the user input and then validate it against the login / register Microservice's validate function
N/A
N/A
The rationale to go with this implementation was to ensure that we would easily swap out our Triaging Microservice with another version, by simply implementing our required interfaces.
Notification Microservice
- The principal component for this feature, which handles the core functionality of scheduling and sending notifications
UserLogin Validation
- The userlogin interface is implemented by the registration microservice and validates the username and session token of a request. The notification microservice uses it's API to validate requests before scheduling a notification.
Register Interface
- The register interface is implemented by the notification microservice. Other services can use it's API, along with valid credentials, to schedule a notification when an ER spot becomes available.
N/A
The register API has an optional parameter that allows a custom message to be sent with a notification. This can be used to specify the appointment details. If not included, a generic message is sent instead.
The rationale for this implementation was to allow for simple modification and upgrades to the notification service as long as the API stays the same. It also makes it easy to scale up the service during excess demand and scale down during lower usage.
The diagram above shows a medium-detail representation of the Login/Register microservice and how other applications can interact with it in a meaningful way. The Register module reads and writes to the Members table and Token table. The Login module reads from the Members table and writes to the Token table. The Validate module reads from the Token table.
N/A
The login/register/validate modules are defined using AWS CDK constructs.
This two-table setup allows for the microservice to manage two separate states: account information state and active session state.
- main.py - This is the primary script that initiates and coordinates the function calls across the system.
- triage.py - Contains the handlers responsible for managing the triage process.
- requirements.txt - Lists all the necessary dependencies required for the smooth operation of the triage microservice.
- index.html - Provides the HTML structure for the user interface of the triage microservice.
- Microsoft Azure Devops - Serves as the cloud-based execution environment, hosting and running the triage microservice instances.
N/A
Depending on the demand and load, the triage microservice could be designed for configurable replication through Microsoft Azure's in-built scaling feature. This would allow scaling up the service during peak hours or scaling down during off-peak times, ensuring efficient resource usage. It gives the option to scale between 1-3 instances of the services on the current plan.
For our technology stack, we chose to go with a culmination of Python and Flask as they offer robust, lightweight backend processing for the constraints of our system. Flask offers simplicity and flexibility, making it suitable for rapidly developing and deploying a microservice like triage. For deployment, we chose Microsoft Azure as it provides reliable cloud infrastructure with scalability options. This choice ensures that the triage service can handle varying loads effectively and offers integration possibilities with other Azure services for enhanced functionality. Additionally, using POST requests ensures that user data is sent securely and is not exposed in URL parameters. This aligns with the need for privacy and security in healthcare applications.
On the contrary, we rejected the idea of using a more complex framework instead of Flask mainly due to the increased complexity and potential overhead, which might not be necessary for the scope of the triage microservice. We also avoided hardcoding operational parameters in favor of configurable parameters to allow for greater flexibility and adaptability to different deployment environments and user requirements.
Y-statement: Flask was selected over a more complex framework for its simplicity and minimal overhead, ensuring that the development and maintenance of the triage microservice remain efficient and straightforward. This approach aligns with the need for a lightweight, agile solution that can be rapidly developed, easily updated, and smoothly integrated with other systems, without the additional complexities and potential performance trade-offs that might come with a more intricate framework.
The elements are the dockers containers which hold the flask server which connects to our mail service. The user's client device is also an element as it sends the request to the endpoint to send the notification.
N/A
N/A
The notification microservice is written in Python. It uses a Flask web server to listen for and respond to requests. We chose Python because it's easy to write, read, and maintain. Flask was chosen as the web server because it's simple, efficient, and well-supported. For scheduling notifications, we used a Redis cache. Redis is an in-memory object store that is efficient for quick lookup of small amounts of data. It was chosen because requests only need to be stored temporarily, until the notification can be sent. So, it makes sense to store the data in memory rather than writing it to storage. There are also well-known Python libraries that integrate a work queue with Redis. The entire service is hosted in Docker containers. We decided to use Docker over local hosting because it provides the most flexibility for future maintainers.
Triage Microservice
- Main microservice that deals with patient symptom triaging. It requires the validation method from the Login Microservice to validate user login information before returning a result
Notification Microservice
- Allows users to sign up for an automated email whenever a near by ER spot is open. It requires the validation method from the Login Microservice to validate user login information before sending an email. It also requires the triage results from the Triage Microservice to determine the correct diagnosis to include within the email
Login / Register Microservice
- Provides registration / login capabilities for users. It provides the validate credentials interface for our two other microservices which is used to a validate a user login token.
N/A
N/A
N/A
The diagram above shows a high-detail representation of the Login/Register microservice and how other applications can interact with it in a meaningful way. The Register Module receives calls to its API Gateway endpoint and makes read/write calls to the DynamoDB Member and Token tables.
N/A
The login/register/validate modules are defined using L2, L3, and L4 AWS CDK constructs. This allows them to be deployed automatically using the AWS CDK CLI. The configuration of the Lambda functions is controlled using environement variables defined in the CDK implementation.
The API Gateway/Lambda/DynamoDB pattern is a well-established horizontally scaleable pattern which allows for flexibly usage. When the system load is high, AWS automatically horizontally scales your application to handle the volume. When the system load is low, AWS automatically spins down any instances of your code to save resources.
- During the triage, the user begins by entering the details in the input form.
- Then the system checks if the input is valid, if not, then the system throws an error message and asks the user to re-enter the form with valid details/format.
- After the form is validated, the systems checks for the validity of the user through a validation token. If the user is valid, then the system returns the triage result and terminates the process.
- Otherwise, the system throws an invalid user error and terminates the process.
N/A
N/A
The implementation of string input validation and user authentication is driven by a commitment to privacy and security, aligning with the rigorous standards of the health industry. Ensuring accurate data entry and secure user sessions is critical in maintaining the integrity and confidentiality of the triage process. This approach not only enhances the system's reliability but is also important to generate user trust by safeguarding sensitive health information.
This diagram represents the control flow of the notification microservice. The states shown are all possible states the microservice can be in. The states are request received, user verification request sent, user not verified, user verified and notification sent. The Request received state occurs when the service just receives the request, it is only used to acknowledge the request and move to the next state. The next state is where the request to the /verify endpoint of the login/register microservice occurs. If it returns 200 the user is verified and the notification is sent otherwise the notification is dropped because the user is not verified.
N/A
The only variability occurs in the response by the /validate endpoint and whether or not the notification is sent.
The states for this diagram were decided based on the process the microservice takes to fulfill a request. More states could have been used to properly display the behaviour of the system but the current amount is adequate to be able to fully understand the microservice.
This set of questions aims to assess how useful the Architecture Package is for Maintainers and to verify if it contains sufficient information for them to fulfill their responsibilities.
The subject of the review is the architecture package for our Mister ED web app which is a concoction of three microservices: Register/login, triage, and notification. Stakeholders will be the potential future maintainers of the project.
-
Would troubleshooting steps be a worthwhile documentation piece to add in the future?
- Expected Answer: Yes
-
Do we have adequate documentation for the system?
- Expected Answer: Yes
-
Is it clear what the contents of the each view is
- Expected Answer: Yes
-
Do you find any of these diagrams or views to be redundant or excessive?
- Expected Answer: Yes
-
Suggest any additional tools or diagrams which could be included in the documentation package
- Expected Answer: A diagram describing the connection of all of the microservices and which pieces interact with each other, showing boundaries of trust and runtime. For example, it should show what runs in AWS vs what runs in Azure, etc
-
Suggest any different decisions which could have been made during the architecture design stage.
- Expected Answer: Run everything within the same virtual private cloud (like is possible in AWS) to increase service-to-service security.
-
Please list any concerns around the decision to use a monorepo to host all code as opposed to a fragmented solution where each microservice has its own git repository.
- Expected Answer: The monorepo solution is acceptable for the size and scope of the application.
-
Please list any areas of concern in the variability guide.
- Expected Answer: There are no areas of concern in the variability guide.
-
Q: Please identify the gaps, if any, between the current state of the Architecture Diagram and desired state so that the system is maintainable in its current condition. If there are no gaps, please identify areas of improvement.
- Expected Answer: There are no gaps for the system to be maintainable as-is; however, it would be great if there were better instructions for troubleshooting.
-
Please provide any miscellaneous feedback you may have for the development team.
- Expected Answer: N/A
The review will be carried out by providing the reviewers first with the set of questions we have prepared for them, allowing them to read them over completely. After they have comprehended the questions, we will provide them with a demo of the application. After they have seen a demonstration of the application, they will review the Architecture Package for completeness.
Review done by Group 13
-
Would troubleshooting steps be a worthwhile documentation piece to add in the future?
- Yes, having troubleshooting available is always useful in case a user doesn't understand how a feature works or is having trouble accomplishing something
-
Do we have adequate documentation for the system?
- Yes, the system is extensively documented including all expected diagrams
-
Is it clear what the contents of the each view is
- Yes they are all clear
-
Do you find any of these diagrams or views to be redundant or excessive?
- For simple use cases such as login, extensive diagramming is not useful and a simple textual description of implementation choices would be more than enough.
-
Suggest any additional tools or diagrams which could be included in the documentation package
- Having an overall module view would be useful to see how all components interact with each other in a broader context. As well, having larger deployment diagrams would help to see at a glance where everything is running
-
Suggest any different decisions which could have been made during the architecture design stage.
- For a simple app like this, a microservice architecture is clunky and unnecessary.
-
Please list any concerns around the decision to use a monorepo to host all code as opposed to a fragmented solution where each microservice has its own git repository.
- A monorepo is a totally fine solution for a small to medium-sized project such as this one. A fragmented solution would make sense if the intention were to integrate more with other preexisting microservices which are not controlled by your organization.
-
Please list any areas of concern in the variability guide.
- I didn't find any problems.
-
Please identify the gaps, if any, between the current state of the Architecture Diagram and desired state so that the system is maintainable in its current condition. If there are no gaps, please identify areas of improvement.
- It is good as is. (did you mean Architecture Document?)
-
Please provide any miscellaneous feedback you may have for the development team.
- Good job!
- Troubleshooting and general help documentation would be needed if development were to continue.
- Simpler parts of the system were given large diagrams and presence within the documentation when rationale of design choices is more than capable of explaining them fully.
- The general system documentation and diagramming is not enough to allow for understanding of the general inner workings of the system as well as deployment structure.
- The current amount of documentation and diagramming allows for the system to be maintainable for future maintainers.
- If this project were to be redone or if it was a real project to be released not just a prototype current architecture design choices might need reevaluation.
For the final sprint, we decided to add a new attribute to our response after the user submits a form. The new attribute is an "email body" which is used by the Notify Microservice to provide the user a more detailed email about why they need to visit the ER. When the Triage MS returns a response, the Notify Microservice is able to retrieve the email body attribute and send it to the patient's selected email whenever an ER spot is open. This email body attribute is only returned when the user is required to visit the ER, either for further triage or treatment.
For the final sprint our goal was to use results from the triage microservice to customize the email sent to the user. This ‘email_body’ element provided in the response from the triage microservice was only available on mandatory ER visits so we still needed the regular email from earlier. The ‘email_body’ element was stored as a cookie within the browser and sent to the notification microservice when an email is requested. If the ‘email_body’ element is not empty the body of the email sent to the user will be replaced with it.
For the final sprint, the login/register microservice was updated to require new accounts' username to be in email format. This allows us to have some way to contact account holders in the event of an error. If there was a next sprint, the next big feature would be to allow users to reset their password in case they have forgotten it.
Our team has also decided to use GitHub Issues to help allocate tasks and keep documentation of who is doing what. For example, each team has a sprint issue where their respective team members can comment about their progress.
| Name | V# | Contribution |
|---|---|---|
| Aman Palod | V00968304 | Documentation guide for triage microservice, question set review, review of document |
| Brennan McMicking | V00939944 | Sprint 2 implementation for Login/Register microservice, documentation, and 6-step process ideas |
| Payne Jones | V00941757 | Implementation of notif sprint 2, allocation and c&c views and documentation for notif, review results summarization and question set help |
| Andrew Hu | V00966409 | Sprint 2 implementation for Triage MS, review of document, question set review |
| Kyle Stang | V00935810 | Diagrams and documentation for notification microservice. Bug fixes and deployment of sprint 2 |