In the first post of the “Overly Complicated App” series I exposed my intention of developing an app with so many decisions about architecture and design and optimization and more, just for the sake of learning. In this post I expand on the the idea by adding the initial requirements for such an app.
I decided to go with a simple approach to requirement gathering, mostly because excessive documentation would only get lost in the void.
For this project I chose to use a block diagram to delineate the overall architecture, written use cases to describe the application’s requirements, and screen mockups to support the use cases and to given an idea of how the end product may look like.
A block diagram represents the outer components of a system and how each of them connects with the others. I used it in this project to get a feeling of how everything will fit together, considering that I separated the development into at least six stages.
The diagram above depicts a microservice architecture. There will be two microservices, each of which inside its own docker container:
- The Users Microservice will be implemented in Python and will use a PostgreSQL database.
- The Tasks Microservice will be implemented in Java, with a MongoDB NoSQL database.
The frontend applications (browser, mobile and desktop) will only send/receive data to/from the API Gateway, and will know nothing of the inner workings of the microservices.
At the time of writing, it’s still unknown whether the microservices will communicate amongst themselves.
A use case describes the steps necessary for an actor to achieve an end goal in a system. A simple example would be an actor user executing the steps of filling the login form to achieve the goal of logging in into the system XYZ application.
When writing the use cases, I first started by listing the expected types of actors/users for the application. Then, I listed the requirements in a very simple, non-use case, manner:
- A non-registered user should be able to sign up.
- A registered user should be able to login.
- A registered user should be able to logout.
- A non-registered user should be able to reset his/her forgotten password.
- A registered and logged user should be able to create/read/update/delete a task at any time.
- A registered and logged user should be able to mark a task as completed/done (not active).
- A registered and logged user should be able to mark a completed task as incomplete (active).
- A registered and logged user should be able to update his/her own account.
- A registered and logged user should be able to delete his/her own account.
- A user should be able to change the app’s language.
Yes, the items above are not proper use cases, because they lack the thorough description and steps needed to complete the goal. The real use cases, with proper documentation, can be found here.
Still, by simply listing the goals/functionalities your system’s suppose to provide, you can get an insight of how you actually want the system to be.
And this brings us to Mockups, which are simply images of how the end product may look like.
When doing them, I realized that just writing use cases is not enough to list your system’s requirements. And neither would be just drawing mockups. But when you put both of them together, that’s when they add the most value to your project.
It happened that I was drawing one or another screen of my system, and I’d realize that the functionality the screen was describing hadn’t been contemplated in the use cases. So I’d go and write the proper use case for said functionality. And by doing so, I would gain further insight of how the mockup should be.