In my experience as a backend developer, I have observed that companies of all sizes face the same issues. They often struggle to anticipate changes or develop products with agility.
We are plagued by buzzwords like scalability, adaptability, reliability, and robustness. As developers, we sometimes try emerging technologies without seeing the consequences, which can lead to problems. This technical debt often surfaces as common project frustrations that anyone involved in a tech project can recognize:
- Feature releases are delayed.
- Why didn’t you mention it to me before?.
- We need to perform a code cleanup.
- We need to refactor X module.
- A supposedly simple change provokes 25 file changes in a pull request. Isn’t it supposed to be simple?
- Dozens of pull requests stagnate in the repositories.
- Many conflicts arise between pull requests, even when the feature tasks are different.
- One change can break a feature in production, so teams are prioritizing bugs over feature development.
- An impossible coexistence between classical programming and AI engineering.
These are some issues I will help you avoid by sharing my experience and the actionable steps I have applied (and applying) in my career.
As we move through this series, we will dive deep into software engineering principles. But we’ll do it differently. Forget the ambiguous, philosophical theories you might hear from the latest backend guru. While I agree with the core concepts, social media often treats them as a panacea, which confuses Developers & Tech enthusiasts. A common example is Design Patterns. We will revisit them, but with working examples in a GitHub repository.
We will create a typical note-taking backend application that, even when small, can become complicated if we don’t take care of our code.
Assumptions
- This series assumes you have a basic understanding of the following:
- Programming basics: Good practices and modern software engineering can be taught and applied in our early stages. This series aims to provide a clear and structured explanation.
- Version control systems like Git
- Operating systems: The basics
- Network Communication
- A desire to learn.
The Project: AdaptNotes
When a new project arrives, it is often written in business language, plain English, and vague descriptions. Here is our example:
Project Name
AdaptNotes
Description
AdaptNotes is a dynamic note-taking application that offer flexible features for both registered and anonymous users. Registered users have full control over their notes, allowing them to store, organize, and manage their content efficiently. Additionally, users can perform actions such as sending notes via email or executing custom actions that may be requested later by the client.
For anonymous users, AdaptNotes provides a unique feature allowing them to contribute notes without the ability to manage them. These anonymous submissions are treated as quotes and published on the home page, serving as motivational content for all visitors. To maintain the quality and appropriateness of the quotes, the platform features a moderator moderation system, where authorized users can review and manage the displayed content. Future iterations of the app may incorporate automated moderation to streamline this process based on client needs.
AdaptNotes combines personalized note management with an open platform for inspirational sharing, fostering creativity and community engagement. Initially, the app could be completely deployed as a web application.
Analysis
Because this is a backend series, we will skip the frontend or client apps, but we will refer to them at a high level. Our main component will be the backend app. We’ll start with RESTful APIs, and in future articles, I will demonstrate how to make protocol switching easy.
Let’s separate the backend app into entities, showing their relationships and potential attributes.
Now, it is necessary to visualize the relationships and collaborations using CRC cards.
CRC Card for User
Here summarizes the user interaction with notes when role is not moderator and the responsibilities as moderator according to the requirements.
| Class Name | User |
|---|---|
| Responsibilities | • Create, manage, and delete notes • Authenticate and manage access to the system • Track email-sending activities (via Email_History) |
| Collaborators | • Note (for note creation and management) • Email_History (for tracking email-sending events) |
CRC Card for Note
Describe how a note will be managed.
| Class Name | Note |
|---|---|
| Responsibilities | • Store content created by users • Track the number of times the note has been sent via email • Link to the User who created the note (if applicable) |
| Collaborators | • User (as the author of the note) • Email_History (to log email-sending events) |
CRC Card for Quotation
The particular type of note and how the Anonymous user will interact with a quotation, to create it and see in the home.
| Class Name | Quotation |
|---|---|
| Responsibilities | • Record all quotations made by anonymous users • Store quotation content and metadata |
| Collaborators | • Anonymous (no authentication required) • moderator User (to approve or reject quotations) |
CRC Card for Anonymous
Overview of the type of user with their limited capabilities, following the specifications of the client.
| Class Name | Anonymous |
|---|---|
| Responsibilities | • Send a quotation • View quotations on home page • Provide unique IP identification |
| Collaborators | • Quotation (to send and view quotations) • Home Page (read-only access to quotation list) |
CRC Card for Email_History
This is the process how a Email_History can be track all email statuses.
| Class Name | Email_History |
|---|---|
| Responsibilities | • Record the sending status (sent, failed, in-progress) of notes • Track email delivery attempts to recipients • Maintain timestamps for tracking when emails were sent |
| Collaborators | • User (to track who sent the email) • Note (to reference which note was sent) |
For experienced developers, these diagrams might be sufficient. However, to get a precise idea of the workflow and avoid ambiguity, we can use sequence diagrams. Presenting these to clients, stakeholders, and other non-technical team members in the early stages is invaluable for making adjustments and ensuring everyone is on the same page.
A picture is worth a thousand words.
User Interactions
In this diagram you can see the different interactions of a registered user
Anonymous Interactions
And the anonymous respectively
Conclusion
We’ve seen how easily backend systems can become resistant to change, leading to a cycle of project delays and developer frustration. It’s a common story, but it doesn’t have to be yours.
This series is your practical guide to breaking that cycle. We will move beyond the buzzwords and focus on the foundational principles and hands-on techniques that lead to truly adaptable, resilient, and even enjoyable backend systems. We’re not just building software, we’re building a foundation for future innovation.
In the next article, we’ll get our hands dirty. We will take our first concrete step requirements. You’ll see how this low-tech approach can clarify a system’s design and save countless hours of refactoring before we write a single line of code.
Which of the ‘pain points’ I mentioned resonates with you the most? Let me know in the comments.
