DEV Community: Radu Constantin

A software development journal — Architecture (Part 3)

Radu Constantin — Tue, 31 Oct 2023 05:32:08 +0000

Architecture

In the previous articles I've presented the main idea for our team's project and the requirements for our MVP. Now that we had a list of features that we all agreed on, we could start thinking about the general architecture of the project.
Keep in mind that this was the first time we've embarked on building a more complex web app, and we weren't really sure what kind of architecture or tech stack to use. In the enormous world of web development, it seemed like there were hundreds of frameworks and tools that we could use to get the job done. Feeling a bit lost among the huge list of available options, we decided to ask for help.
While I was studying at LaunchSchool, Eamon, one of the core curriculum graduates, and his team launched a very impressive web application for language learning called Alexandria (here is a link to the app if you're curious https://tryalexandria.com and here is a link to the case study that they wrote https://alexandria-reader.github.io). All of us knew Eamon and the impressive app that he built with his team, so we decided to ask him for some guidance in creating our own portfolio project.
Antonina set up a meeting with him and we started his 'interrogation' on the ins and out's of how he and his team built Alexandria.
Getting the chance to talk with an experienced developer is an invaluable experience. We talked at length about the different tools they used for their project, how they structured their work and the challenges they had to overcome. I was very curious on how they designed Alexandria's architecture and I got the answer I was looking for: Service Oriented Architecture.
In the context of our app, using an adapted form of this type of architecture made sense. We would split the application into three layers:

Controller Layer This is the first layer. It receives HTTP requests and calls the appropriate service.
Services Layer The second layer. Holds the logic and data processing required.
Data Access Layer The third layer. Accesses and edits data on the database as needed. As an example on how this type of architecture would work, let's say that a user wants to create a new 'Neighborhood'. They would make a POST request with the data required to an established route, '/neighborhoods':

The request is received at the controller layer and the appropriate logic is called from the services layer.
The services layer then calls the Data Access Layer in order to execute the required actions on the database.

In this case the Data Access Layer is handled by an ORM (Prisma) which I will talk about a bit later, but the whole process is extremely simple!
What I loved most about this way of structuring the app was its simplicity and the well defined separation of concerns. It also makes the codebase easier to work with since each layer handles a very specific part of the application.
One more piece of the puzzle was now in place! We had a list of features and a general idea for the MVP and now we also had somewhat of a plan for the architecture. What we needed to do next was to establish the tools that we would work with. We had a few criteria required for selecting them:
1. It had to be genuinely useful for building our app;
2. It had to be in-demand in the current market;
3. Was in some way related to what we already knew. (For example, all of us had a deep understanding of JavaScript, so learning TypeScript wouldn't take too much effort).

Armed with this set of requirements we started a team debate and after going back and forth analyzing the advantages and drawbacks of each tool and we decided on the following (this is a glimpse of the reasoning behind our choices, in reality it took us longer to decide and we had to do quite a bit of research):

The Database

The main decision that we had to make in this case was if we should use a relational based database system like PSQL or one of the document based systems such as MongoDB.
During LaunchSchool, we all learned PSQL, so that was a big plus and since most of the advantages of a document based database where not really critical for our app (https://www.mongodb.com/nosql-explained/nosql-vs-sql) we decided to stick with PSQL.
Alongside PSQL we've decided to also implement something that none of us had previous experience with, but I thought that will save us a lot of time in the long run: an ORM, Prisma to be more specific. I won't get into too much details here, but an ORM is a system that translates between data representations used by databases to those used in object oriented programming.

The Backend

As I mentioned earlier, all of us already knew JavaScript, but we've decided that this would be a good opportunity to try out TypeScript and static typing. We considered that it will be helpful in catching errors earlier. Seeing that it was also a in-demand skill made it an even more attractive choice.
Express.js was the framework of choice for our API. Everybody on the team knew it and we considered that it will be a good option for the demands of our application.

The Frontend

I had worked on a few small projects with React and was enthusiastic to use it. I have to admit that in taking this decision we didn't take into account other libraries, it was either React or pure JavaScript and to be honest I don't ever want to work with pure JavaScript in making an interactive UI. I prefer Rect's component based system.
For future projects I would be interesting in trying out other libraries or frameworks, but in this case we just sticked with React and TypeScript.

Structuring our work

Now that we had all the pieces together we could finally start working, or so I thought. The fact remained that we should work as a team even though we were separated geographically and were on different time zones.
I knew we needed to work with Git & Github, but I wasn't sure exactly how to do it. After some time spent Googling and researching we established some basic rules regarding our project on Github.
1. We will never work directly on the main branch;
2. We will use branches for every feature we want to implement;
3. Every PR will need at least 2 reviews from other team members in order to be merged.
Git & Github are both complex topics that are easy to overlook. During the development of this project I dramatically increased my knowledge, but at the same time I realize that I still have a lot to learn regarding version management. I would advise any new developer to spend more time studying these tools as they are mandatory for working within a team.

First Mistake

Now I want to talk about what I consider to be our first mistake. Early on we established that it would be best to first start with the backend and the database and only then work on the frontend.
We wrote the requirements for our API and created diagrams for the Database and the API routes, but later I realized that even though we tried our best to plan everything, when we eventually started working on the frontend we realized that we've left plenty of gaps in the API.
That led to a lot of backtracking trying to fix or add modules to the backend.
What we should of done instead is to apply the philosophy of Iterative and incremental development. Decide on a small feature, and implement it on both the backend and frontend. Looking back, I think the development process would of went much smoother if we applied this concept. It would of allowed us to make sure a feature works on both the backend and frontend before advancing further. I've learned my lesson and in future projects I will do things differently.

I plan to stop here, since this article is getting a bit too long. I hope you've learned something interesting and stay tuned for the next article in the series where I will talking about our database and how we used Docker containers!

Helpful Links

I'm not affiliated with any of the links below. These are just resources that I genuinely consider useful.
Git & Github Collaboration - https://www.freecodecamp.org/news/how-to-use-git-and-github-in-a-team-like-a-pro/ (The best article I could find on the topic)
Iterative and Incremental Development - https://en.wikipedia.org/wiki/Iterative_and_incremental_development
ORM (Prisma) - https://www.prisma.io/dataguide/types/relational/what-is-an-orm#:~:text=An%20ORM%2C%20or%20Object%20Relational,used%20in%20object%2Doriented%20programming

A software development journal - The MVP (Part 2)

Radu Constantin — Mon, 23 Oct 2023 17:50:25 +0000

In the last part of this series I mentioned that our team had decided to build a small community focused app that allows users to issue requests for services or help out other people in their local community.

At this point, during our meetings, we kept going back and forth with different ideas and features that we wanted to implement. We were thinking about adding user rankings, neighborhood rankings, searching Neighborhoods based on user location, etc.

At the same time, a lot of questions arose. We knew that the core of our app consists of users being able to issue requests and respond to requests within a specific neighborhood. Here is an example of users interacting with the app:

User A is a member of Palm Springs Residential.

User B is also a member of Palm Springs Residential.

User A writes a request on the Palm Springs Residential main dashboard, saying that he needs help setting up his new washing machine.

User B sees User A’s request on the main dashboard and writes a response, saying that he is will to help out.

User A accepts User B’s help offer on the app and a communication channel is opened between them.

That is the core loop of the app. A user creates a request and a user issues a response. Sounds very simple right? And in essence it is, but as usual in software development, an apparently simple problem can hide quite a lot of complexity behind it. Currently we have 4 entities involved in this: Neighborhood, Request, Response and User. Now, here is a sample of questions that came up:

Should Users that haven’t joined a Neighborhood be able to see the requests within that Neighborhood?
When a User accepts a Response, does that automatically close the Request?
Should a User manually close a Request after it was finished?
Should we differentiate between a Request that was closed because it was solved or because it was not needed anymore?
How will User A and User B talk to each other after help was offered?
What happens to a Request or a Response if the user who created them leaves the neighborhood?

This is just a small part of all the questions we came up with. It’s not exhaustive, but I wanted to showcase the amount of depth even a small, apparently simple feature can present.

We also had to think about how a user joins a neighborhood? Who is the gatekeeper? Should we have a form of identity check?

After a few rounds of discussions, we amassed an impressive list of the potential features. Actually we had so many features that in my opinion it would of taken us too much time to implement all of them. We needed to establish an MVP (Minimum Viable Product) in order work efficiently and have a product ready for market as soon as possible.

Coming up with ideas is easy once you get into a flow state, but having to select only the essentials is though. We had to do it though, so we started cutting mercilessly left and right until we were left with the core features. I will not post all of the MVP’s requirements here since that will take up too much space in this article, but I can say that we’ve removed all of the superfluous features and instead decided to stick to the essentials, and that is to allow users to join/leave ‘neighborhoods’ and allow them to create requests and respond to requests within the same neighborhood.

One of the features that I had a hard time parting with, was linking ‘neighborhoods’ to real-world locations. I still consider this feature to be essential for the app, but for the MVP we decided that it would be best to make sure that the whole ‘Join/Leave Neighborhood | Create Request | Respond to Request’ loop is solid, before adding location based services.

After we had a list of MVP features we would like to add, we then further split it into categories based on the entities we’ve identified. Here’s a part of the features for the MVP:

MVP Features for Users and Neighborhoods

We were getting very excited. We had a product and a list of features for the MVP, but we didn’t write any code yet and I still didn’t know how we would organize ourselves and work as a team.

I forgot to mention that me and Antonina are based in Europe and are on the same timezone, while Bob and Shwetank are in the US, and are on a completely different timezone. This made collaboration a bit more difficult, but we saw that as just another challenge that needs to be overcome. As a consequence, we knew we needed to cover a lot of ground in our weekly meetings, so as to not waste the precious time that we had (I forgot to mention that we were all working on this project in our own free time, outside of our jobs or other obligations). This is how we organized our meetings for maximum efficiency:

During the week before the meeting I would share a document in which we would all write the topics or questions we wanted to discuss during our next meeting.
Since everyone had access to that document, we could all see what the others were asking or thinking about and we could research the problem before the meeting.
During the meeting, we recorded in writing the answers to all of the topics of interest.
After the meeting was over, one member of the team would take the list and transform it into an actionable plan or task list.

This very simple structures that was added to our meetings saved us a lot of time and allowed us to be focused on our priorities.

I know that I still haven’t talked about code yet, and I promise I will dive more into the technical aspects in the next article, but I want to emphasis that working on a project isn’t all about coding; a lot of time is dedicated to simply exchanging ideas, researching and discussing features and implementation.

In the next article I will breakdown and explain the architecture that we went for, the programming language that we chose to work with and the tools involved. I will also dive into the way we structured a workflow for working with Git and Github as a team.

A software development journal — Introduction (Part 1)

Radu Constantin — Sun, 22 Oct 2023 14:30:17 +0000

This series of articles is being written with the objective of documenting the process involved in building a full stack web application from the ground up. I intend to publish an article every week in which I will present every part of the journey from the initial idea stage to a finished product. I am still learning the intricacies of software development (I hope I will never stop learning) so what I write here might oftentimes seem not optimal at the best or plain stupid at the worst. If at anytime anyone has a suggestion or correction to make please write me a message or comment. I’d really appreciate it!

Having the opportunity to work alongside a team of developers has taught me a lot of things beside simple coding skills. Writing these first sentences of this article series makes me think about all of the lessons in communication, organization, planning and general human relationships that I’ve learned as part of this process. I hope that by reading this series of articles, readers will be able to learn from my journey and my many mistakes.
Now that I’ve made a short intro let’s start with……

The Beginning

I was at my desk fiddling with a pen. Thoughts were rushing through my head and I had no idea how to proceed further. I had recently graduated from LaunchSchool’s Core Curriculum and had transitioned from the rigors of a strict and well defined learning path to the vast open sea of options that the world of web development offers. In spite of the long time I took to learn software development I had nothing to show except a few small projects I’ve done during my time at LaunchSchool.
I was very confident in my abilities as a software developer, but I needed a way to actually be able to put my knowledge to good use and what better way to do that than to tackle a complex project?
I didn’t know what I wanted to build at this point. All I knew was that I wanted to create an impressive portfolio project that would be able to showcase the skills and proficiency that I’ve gained since I’ve first started the journey of learning web development.
I needed a team of like minded people to do that!

Assembling the dream-team

Being familiar with the level of discipline and study necessary to graduate from LaunchShool, I decided that that would be the best place to look for teammates. I hastily crafted a message explaining that I would like to build what will possibly be the best-ever portfolio project that humanity has ever seen and I sent it to the LaunchSchool Slack channel.
And I waited…..5 minutes……no reply……1 hour no reply. No worries, I told myself, I shouldn’t be so impatient, Rome wasn’t built in a day after all. The next day still no reply. A few days later, no reply. At this point I was starting to get worried that no one might be interested in working with me on what was possibly the greatest rival to Facebook and Google combined.
A week passed and I still did not get a reply. The whole situation was very bleak, I was facing the prospect of having to work on what was possibly the next Spotify alone. ‘It’s allright’, I told myself, I will just spend the time (as I was already used to by now) studying more web development topics.
I think almost two weeks passed before I got my first reply from my fellow colleague Shwetank, shortly afterwards I got a reply from Antonina, and finally from Bob. I was thrilled that I possibly had the teammates that I was looking for. We decided to setup a video call so we can all get the chance to know each other, our goals and what we want to get out of this experience.
During the call, we got to know our objectives each other’s strengths and knowledge of different tools and programming languages. The fact that we all graduated from LaunchSchool meant that we all had a good mastery of the fundamentals and already shared common ground regarding the programming languages that we knew. The only missing piece was the fact that we didn’t know what project to work on. We decided that all of us will write down possible project ideas and meet the next week.

The project

During the following week I struggled to come up with ideas for a portfolio project. The most important objective that I wanted to achieve with this project was to showcase our team’s ability to to build a full stack application from the ground up, using a modern tech stack. If the app could also solve a real world problem, that would be even better, but if not, I would of been satisfied to build a fully functional e-commerce store (thankfully that was not the case).
The next week I half-heartedly presented my awful ideas to the team, while hoping that somebody came up with something better than I did. Fortunately, Antonina came up with a brilliant idea!
She presented to us an app for local communities called ‘Neighborhood’ that would allow users in a particular location to issue requests for services and other ‘neighbors’ could respond. For example, I just bough a piece of furniture and I would really need some help setting it up; just issue a request on ‘Neighborhood’ and someone could respond and help out. Simple and brilliant!
The main purpose of the app is to encourage people in local communities to help each other and build long lasting relations based on mutual help.
Everybody on the team agreed that ‘Neighborhood’ was what we should start working on. Awesome! We now had an idea, but what were we supposed to do next and how exactly would we do it? Questions were racing through my mind again: What to start with, who should do what? What kind of database to use? What is Docker and why is everybody talking about it? Should we use React for the frontend? Do we design the UI first? Did I forget to feed the cat again?
Anyways, those questions will be answered in the next article in this series (only some of them actually).

Notes

During this time I have to add that I benefited a lot from the guidance and mentorship provided by my friend and fellow LaunchSchool alumni, Iuliu Pop, who was very generous in sharing his knowledge and giving me a helping hand whenever I needed it.

Resources

I’m not affiliated with any of these websites or the services/products that they provide. I’m just sharing resources that I’ve personally used and found to be very useful on my learning path.
https://launchschool.com — This is where I’ve achieved my mastery over the fundamentals of software development and I would gladly recommend any aspiring developer to follow their curriculum.
https://fullstackopen.com/ — This is a free course offered by the University of Helsinki that bridges the gap between the fundamentals learned at LaunchSchool and the tools used in modern web development.