Project and technology overview
In this series of tutorials, I want to explain some techniques to develop a production-ready full-stack application. We are going to build a fully functional Mailing List Application using PHP, JavaScript, Docker, and Amazon Web Services(we will discuss these topics later).
I intend to cover the different stages aff a web application development from the design to the deployment, paying particular attention to the decisions and strategies to follow to obtain a successful project execution.
The project infrastructure will not be completely free using the AWS free tier. Although, I will put all my efforts kept it at low costs because the interest of this series is to learn how to use and become familiar with specific technologies, not to spend a lot of money. I will make a small costs overview in each chapter.
I recommend having a notebook nearby to take notes and to make some sketches and diagrams quickly. I use a little checkbook for this purpose. You could use the one that is most comfortable for you.
1. Project Planning:
1.1. Project Requirement definition:
As we say, we go to build a Mailing List Application. In this stage, we will define the minimum use cases required to make a functional mailing list.
First of all, we need to ask a question, what is a Mailing List?
A mailing list is a tool where the users can sign up with their email addresses to receive newsletters about a topic. Also, the user can revoke these permissions to unsubscribe from the list.
What we need to implement these two use cases is to describe them in a more structured way:
Use Cases:
I will describe the minimum use case to make the application work. I will use a user story pseudo-Gerkin sentences for that.
I will remark on some verbs and subjects that we can use later for modeling the program behavior. Also, I will add some sketches enhancing the use case descriptions.
By the user point of view:
As a *user*, I want to give *permissions* to receive an *email newsletter*:* I have to add my *email address* in a form input
* I have to receive an email with the subscription *confirmation link*.
* I have to receive an *email newsletter* periodically```
As a *user*, I want to *revoke permissions* to not receive the *email newsletter* anymore:* I have to add my *email address* in a form input
* I have to receive an email with *revocation confirmation link*.
From the platform’s point of view:
As a platform, I have to *verify* given *email address* to confirm the subscription:* I have to *generate* a unique *confirmation token*
* I have to *send an email* containing the token
* I have to *confirm subscription* after receiving *confirmation token*.As a platform, I have to *remove* given *email address* to left sending email to it:* I have to *generate* a unique *revocation token*
* I have to put the link with the *revocation token* on each *sent email*
* I have to *delete* given *email address* from the list after receiving the *revocation token*
And from the admin’s point of view:
As an *admin*, I want to create emails with the *newsletter content*:* I have to write some *text* and interesting *links*
* I have to save these *email* templatesAs an *admin*, I want to send *newsletter email* to subscribed *users*:* I have to *schedule* newsletter email sending
For the moment we keep the project development here, now we have to start thinking about how we go to orchestrate all this stuff.
1.2. Project Architecture definition:
Based on the use cases described above, we know that we need at least two different user types, one for public usage and another to private usage.
We need some storage layers to save subscriptions and newsletters. Also, we need some email sending service.
To keep the thing simple, but covering everything that I want to cover, I will split into at least two different applications, the Frontend, and the Backend apps(the backend side maybe can be divided into more small pieces).
The Frontend app will be responsible for drawing the public side views, like subscription form, the revocation, and the confirmation views.
I’m going to implement it using the Nuxt Framework, to get the benefit of the server-side rendering and to take profit of the simplicity in component development from Vue JS. We will deploy it as AWS Lambda to profit the Amazon’s free tier.
In the Backend side, we go to implement all the application logic. We will need an HTTP API endpoint to communicate the public side with the backend API. Also, we will need some queue implementation to send emails. To solve this issue, we can use SQS besides with a Lambda function.
On the backend development, we are going to use Antidot Framework to demonstrate the agility that it gives us to develop small but scalable web applications.
Also, we need an admin area too. We are going to do it using the same backend API to maintain service distribution without to mutch complexity. Then we implement all persistence layers by the AWS RDS Mysql database.
The following picture describes that I mean:
Backend API:
POST /api/v1/users
An endpoint to subscribe the user to the newsletter using a POST request. It should require a valid email address to add the user to the subscription list. Then it should enqueue a confirmation mail.
POST /api/v1/users/{user_id}/subscriptions
Is responsible for confirming the user newsletter subscription. I should enable the user to receive the newsletter.
DELETE /api/v1/users/{user_id}/subscriptions
As the confirmation endpoint, It should identify the user too, and it should show the newsletter unsubscription form
Public Web Site:
GET /
The public accessible home page is our presentation card. It should have a subscription form. Also, it should be clear and easy to use.
GET /confirm/{confirmation_token}
It should identify the user, and show the newsletter confirmation form.
GET /unsubscribe/{revocation_token}
As the confirmation endpoint, It should identify the user too, and it should show the newsletter unsubscription form.
Admin Area:
GET /admin/login
The login form to give access to authorized users.
POST /admin/login
It should process and validate the data given by the login form. It should redirect the user to a restricted area with valid credentials, or load the login page again if error.
GET /admin
The admin area, it should have an overview of the users subscribed to the newsletter, and it should have the form to schedule the next mailing sent to the fully subscribed users. It should have a link to the newsletter email generation form.
GET /admin/newsletter
It should have a list of existing newsletter emails with its sending status and date.
GET /admin/newsletter/create
The newsletter email form.
POST /admin/newsletter/create
It should process and validate the newsletter content and save it in the storage layer.
GET /admin/newsletter/schedule
The list of the sent newsletter emails.
POST /admin/newsletter/schedule
It should add to a queue a message with the user email address and the newsletter email content.
Email Sender CLI Tool:
It should be a console command with the only responsibility of sending the given email content to the gave user email.
Conclusion:
In the first post, we saw how to define from scratch a simple usage application using user stories and sketches to start becoming the idea in a tangible product.
Then we define the project architecture selecting the different technologies we want to use, this decision will change in the time for many reasons, but we need something to start thinking of something.
At last, we define the application endpoints and commands, and we separate them in different usage contexts.
In the next post, I will create the development environment using docker, and I will set up the first version of the continuous integration pipeline for the different services to later deploy with confidence.
Thanks for reading, and Happy coding.;-D
