Designing the Architecture for an E-commerce Microservice Project

Architecture is the backbone of any successful project — but let’s be honest, it’s often the most ignored part too. Sometimes it’s because the engineering team is new to this, sometimes it’s lack of clarity from the product side, and other times it’s just us developers getting excited and diving in without a clear plan (we’ve all done it). And while these reasons are valid, they don’t excuse skipping a proper architecture document — or at least a basic diagram — before building anything. Let’s paint a picture: Company A gets a new client and agrees to deliver a shiny new system in three months — without any technical consultation to check if that’s even doable. So, they call on the office superstar dev (you know the one) to either take it on solo (yikes!) or lead a small team. The dev jumps in, follows the prototype or functional document, assigns tickets, reviews code, and the rest of the team breathes easy because “they’ve got this.” Everyone just sticks to their task, checks if the PR looks okay, merges it, and calls it a day. All smooth on the surface. But here’s the problem: every project has an architecture, whether you write it down or not. The issue? In this case, the architecture lives inside the head of that one engineer. No shared doc, no diagram, just vibes. So what happens when that superstar moves on? Maybe their contract ends, maybe they switch jobs. For a while, things still run fine. Then it starts getting harder to make changes. Product wants updates, and now the devs are stuck untangling code they didn’t design. Leadership starts asking questions. Another “super” dev joins, brings their own style, and the codebase becomes a patchwork of different ideas. Devs come and go, and maintaining the project becomes a nightmare. All this could’ve been avoided with just one shared document at the start. A project’s culture is set in the beginning. If the person kicking it off is in too much of a hurry to document the structure, that pressure usually trickles down. But as engineers, we should get into the habit of documenting our architecture, even if it’s not perfect from day one. Trust me, future-you (or the next dev) will thank you. So, about our e-commerce project... We’re going to build it using microservices — mainly for the sake of learning. In most cases, I’d recommend starting with a monolith and then splitting it up later once things get more complex. Microservices can get messy fast and there is usually a lot of technical debt to be paid in the long run. We’ll pretend our product team gave us a functional spec and a Figma prototype. With that, here’s how we’ll break things down before designing our architecture: Questions to answer before designing: What services do we need, and what should each do? What pieces of code will be shared? How will services find each other? How will services talk to each other? What does our infrastructure look like? Once we’ve thought this through, we’ll draw up an architecture diagram and write a supporting doc in our next article.

May 12, 2025 - 18:43

Designing the Architecture for an E-commerce Microservice Project

Architecture is the backbone of any successful project — but let’s be honest, it’s often the most ignored part too. Sometimes it’s because the engineering team is new to this, sometimes it’s lack of clarity from the product side, and other times it’s just us developers getting excited and diving in without a clear plan (we’ve all done it).

And while these reasons are valid, they don’t excuse skipping a proper architecture document — or at least a basic diagram — before building anything.

Let’s paint a picture:

Company A gets a new client and agrees to deliver a shiny new system in three months — without any technical consultation to check if that’s even doable. So, they call on the office superstar dev (you know the one) to either take it on solo (yikes!) or lead a small team.

The dev jumps in, follows the prototype or functional document, assigns tickets, reviews code, and the rest of the team breathes easy because “they’ve got this.” Everyone just sticks to their task, checks if the PR looks okay, merges it, and calls it a day. All smooth on the surface.

But here’s the problem: every project has an architecture, whether you write it down or not. The issue? In this case, the architecture lives inside the head of that one engineer. No shared doc, no diagram, just vibes.

So what happens when that superstar moves on? Maybe their contract ends, maybe they switch jobs. For a while, things still run fine. Then it starts getting harder to make changes. Product wants updates, and now the devs are stuck untangling code they didn’t design. Leadership starts asking questions. Another “super” dev joins, brings their own style, and the codebase becomes a patchwork of different ideas. Devs come and go, and maintaining the project becomes a nightmare.

All this could’ve been avoided with just one shared document at the start.

A project’s culture is set in the beginning. If the person kicking it off is in too much of a hurry to document the structure, that pressure usually trickles down.

But as engineers, we should get into the habit of documenting our architecture, even if it’s not perfect from day one. Trust me, future-you (or the next dev) will thank you.

So, about our e-commerce project...

We’re going to build it using microservices — mainly for the sake of learning.

In most cases, I’d recommend starting with a monolith and then splitting it up later once things get more complex. Microservices can get messy fast and there is usually a lot of technical debt to be paid in the long run.

We’ll pretend our product team gave us a functional spec and a Figma prototype. With that, here’s how we’ll break things down before designing our architecture:

Questions to answer before designing:

What services do we need, and what should each do?
What pieces of code will be shared?
How will services find each other?
How will services talk to each other?
What does our infrastructure look like?

Once we’ve thought this through, we’ll draw up an architecture diagram and write a supporting doc in our next article.