Building an Angular E-commerce App: A Step-by-Step Guide to Understanding and Refining Requirements
Published: 2024-07-08 19:28:56

## Introduction

Imagine you're tasked with building a web application. The project manager hands you a list of requirements, but some of them are a bit... fuzzy. What do you do? Panic? Start coding blindly? Or maybe, you take a step back and start asking questions. In this series of articles, we'll follow the journey of an Angular developer as they tackle the challenge of turning vague requirements into a real, working product. We'll explore the thought processes, the questions they ask, the decisions they make, and ultimately, how they create a successful e-commerce experience for their users.

### The Approach

I'll take a pragmatic, hands-on approach, starting with a Minimum Viable Product (MVP) and gradually adding complexity and features. Along the way, I'll tackle real-world challenges, explore different architectural patterns, and share practical tips for building robust and scalable Angular applications.

### What you'll learn

By the end of this series, you'll gain a deeper understanding of:
- How to analyze and refine e-commerce requirements.
- The importance of user stories and acceptance criteria.
- The role of collaboration between developers and stakeholders.
- Architectural decisions for data flow, state management, and UI design.
- How to prioritize features and deliver value early and often.

So, buckle up and join me on this journey as we unravel the complexities of building a real-world Angular application, one architectural decision at a time.

## Describing the application

Let’s imagine I’m tasked with building an Angular e-commerce application from scratch. The product owner (PO) provides the following requirements for the Minimum Viable Product (MVP):
- **Display a list of products with their images, names, and prices**.
- **Allow users to view product details (description, images, specifications) on a separate page**.
- **Enable users to find or filter products easily**.
- **Users should be able to add products to their cart from both the product listing and product details pages**.
- **Allow users to proceed to checkout from the cart**.

This is the initial set of requirements, and more are expected to follow. The primary goal is to deliver a functional application as soon as possible.

#### Understanding the MVP

In simple terms, an MVP is the most basic version of a product that can be released to users to gather feedback and validate the concept. It focuses on core features and functionality, allowing for rapid development and iterative improvement. You can learn more about MVPs here: https://www.productplan.com/glossary/minimum-viable-product/.

#### My plan of action

With these initial MVP requirements in hand, my next steps are as follows:
1. **Thorough analysis** - Carefully review each requirement to grasp the application's core purpose and intended functionality.
2. **Clarify and refine** - Identify any unclear, conflicting, or missing details in the requirements. If needed, I'll initiate discussions with stakeholders to resolve these ambiguities and ensure a shared understanding of the project scope.
3. **Task breakdown** - Analyze the requirements to identify the data involved, the data retrieval mechanisms, and the necessary user interactions. This will help me break down the work into actionable tasks.
4. **Effort estimation** - Estimate the time and effort required for each task and communicate this with stakeholders. This allows for prioritization and potential adjustments to the scope if necessary.
5. **Implementation** - Once the requirements are clearly understood and the tasks are defined, I'll begin the actual development process.

In this article, I'll focus on the first two steps: **thorough analysis** and **clarification of the requirements**.

## Understanding and clarifying the requirements

The purpose of the app is straightforward: to build a simple e-commerce website. 

I'll start by analyzing the first requirement: _"Display a list of products with their images, names, and prices."_

This statement represents a **functional requirement**. In essence, it defines a specific action or capability the system must perform to meet user needs and business objectives. It focuses on **_what_** the system does, **_not how_** it does it.

_**Note**: For a deeper dive into functional requirements, you can refer to this guide: https://qat.com/guide-functional-requirements/._

In our case, the requirement clearly states the expected outcome: _displaying a product list_. However, it leaves out crucial details about how the list should be presented and where the data will come from. To fully understand this requirement, I’ll need to clarify a few points with the PO.

### Clarification and decisions points

While the requirement states the desired outcome, it raises several questions I need to address:
- **visual presentation** - How should the list be displayed? Should it be a grid, a simple list, or something else?
- **data source** - Where will I get the product data from? Is there an existing API, or do I need to use mock data for now?
- **performance** - How many products are we dealing with? If it's a large dataset, should I implement features like pagination or infinite scrolling to optimize performance?
- **responsiveness** - How should the list adapt to different screen sizes (desktop, mobile, etc.)?

Let's delve into each of these questions and how we might approach them.

#### Visual Presentation

Since the requirement doesn't specify the layout, I'll consult with the PO. There are two likely scenarios.

**Scenario 1: The PO has design guidelines**. Ideally, the PO might have already collaborated with a designer or have a clear vision for the product list's appearance. In this scenario, they would provide detailed specifications on the layout, styling, and any specific interactions. This makes my job easier as I can directly translate these guidelines into code.

**Scenario 2: The PO needs guidance**. More often, especially in early MVP stages, the PO may need guidance. My approach would be:
1. Propose options: I'll suggest common layouts like grid and list, potentially with simple mockups to visualize them.
2. User Experience (UX) Focus: We'll discuss the pros and cons of each layout regarding UX. For instance, grids are visually appealing but might be less space-efficient on mobile devices.
3. Guided Decision: By presenting options and their implications, I'll help the PO make an informed decision.

In this case, let's say the PO decides on a grid layout with a maximum of 4 items per row. We'll also leverage the Angular Material UI library for its pre-built components and consistent styling.

#### Data source

Next, I need to figure out where the product data is coming from. The requirement doesn't mention where the product data comes from. Do we have a backend API ready, or should I use mock data for now? Also, what specific data fields (e.g., descriptions, categories) should be included? 

I'll inquire about the availability of a backend API.

**API exists**: If there's a ready-to-use API, I'll need to understand the endpoint, response format, and any authentication requirements.

**No API Yet**: If the backend is still under development, I'll propose using mock data for the initial implementation. This allows us to move forward with the frontend while the backend is being built.

Since there's no backend API yet, we've decided to hardcode the products on the frontend.

#### Performance considerations

The number of products can significantly impact how we display the list. I'll ask the PO about the expected product volume.

**Scenario 1: Small List**. If we're dealing with a limited number of products (e.g., 10-20), a simple list or grid should suffice.

**Scenario 2: Large List**. If we anticipate hundreds or thousands of products, I'll need to consider performance optimization techniques like pagination, infinite scrolling, or virtual scrolling. Given that this is an MVP, I'll likely recommend starting with the simplest approach (no pagination/scrolling) to prioritize a quick launch. We can revisit this as the product catalog grows.

To keep things simple for the MVP, we’ve decided to have no pagination or scrolling mechanisms for the product list at this stage.

#### Responsiveness

Most e-commerce sites need to look good on various devices. I'll check if the PO has any specific requirements for mobile or tablet views.

**Scenario 1: Responsiveness Required**. If so, I'll need to ensure the chosen layout (grid or list) is responsive and adapts gracefully to different screen sizes.

**Scenario 2: Desktop-First**. If the focus is on desktop for the MVP, I'll still design with responsiveness in mind, but we might postpone full mobile optimization for later iterations.

The PO confirms they want a visually appealing product list on both mobile and desktop devices. Therefore, our chosen grid layout will be made responsive to adapt to various screen sizes.

### The importance of thorough requirement analysis

The process I've just walked through highlights several crucial aspects of effective requirement analysis:

- **Proactive communication**: Engaging in open and direct communication with the PO or stakeholders is key. By asking questions and seeking clarification, we avoid making assumptions and ensure the feature is built to meet the intended goals. This proactive communication not only clarifies the "**what**" of the requirement but also uncovers the underlying "**why**", allowing us to tailor solutions that truly address user needs.
- **Balancing user needs and technical constraints**: Building software is a delicate balancing act between what users desire and what is technically feasible within given constraints (time, budget, resources). By carefully considering both perspectives, we can make informed decisions that prioritize delivering value to users while also ensuring a sustainable and maintainable implementation.
- **Iterative development and the MVP mindset**: Recognizing that we are building an MVP (Minimum Viable Product) allows us to prioritize the most essential features and functionality. By starting with a simplified solution and iterating based on user feedback, we can quickly validate our assumptions, learn what works best, and make informed refinements to the product over time. This agile approach not only speeds up development but also ensures that the final product is more aligned with user expectations.


This requirement analysis process demonstrates that:
- Effective communication is vital for successful project outcomes.
- Collaboration between developers and stakeholders is key to building the right thing.
- Prioritization and iteration are fundamental principles of agile development, allowing us to deliver value quickly and adapt to changing needs.

By embracing these principles, we can create a solid foundation for our e-commerce application, ensuring that it not only meets the initial requirements but also evolves to satisfy the evolving needs of our users and business goals.

### Introducing user stories and acceptance criteria

The clarifications I've gathered are a solid foundation for development, but they primarily focus on the technical **_what_** – what the system needs to do. However, behind every technical requirement, there's a crucial **_why_** – the user's motivations and goals.

#### Personal reflection: the importance of "_why_"

In my own experience, I've found that simply following instructions without understanding the underlying purpose can be demotivating and unproductive. Whether it was homework in school, theoretical problems in university, or tasks at previous jobs, knowing the "why" behind my work always made a significant difference. It gave my efforts meaning and helped me see the bigger picture.

That's why, when working on personal projects, my biggest challenge was always to clearly define the problem I wanted to solve. Understanding the "why" gave my work direction and ensured I was building something truly valuable.

As developers, it's easy to get caught up in the technical details and forget the bigger picture. We may have been trained to focus on completing tasks and implementing features without always understanding the underlying reasons behind them. This "just do it" mindset can be demotivating and lead to solutions that miss the mark.

In real-world projects, it's essential to grasp the "why" behind our work. What problems are we solving for the users? How will our implementation bring value to them and the business? By answering these questions, we can build features that are not only technically sound but also meaningful and impactful.

#### The pitfalls of a purely technical focus

In the context of our e-commerce application, focusing solely on the technical what can lead to several pitfalls:
- **Misaligned solutions**: If we don't understand the user's underlying motivations, we might build a technically impressive feature that doesn't actually solve their problem or address their needs. This leads to wasted effort and resources.
- **Missed opportunities**: You might miss opportunities to enhance the user experience if you don't explicitly consider the user's goals and motivations.
- **Misaligned priorities**: Without a clear understanding of the user's needs, it's harder to prioritize features effectively. You might end up spending time on technical details that don't significantly impact the user experience.
- **Communication barriers**: Technical jargon can create communication barriers between stakeholders and developers, leading to misunderstandings and delays.
- **Disengaged developers**: When developers don't understand the "why" behind their work, they can become disengaged and less invested in the project's success. This can negatively impact their motivation and productivity.

#### Shifting to a user-centric perspective with user stories

**User stories** help us bridge this gap. They shift the focus from the technical implementation to the user's perspective. Let's see how we can transform our first requirement into a user story:

> _As a potential customer, I want to see a list of products with their images, names, and prices so that I can quickly browse and compare products before making a purchase decision._

This user story clearly articulates the user's goal (browsing and comparing products) and the reason behind it (making an informed purchase decision). By understanding this "why," we can make better design and implementation choices that truly cater to the user's needs.

_**Note**: You can find more information about user stories at https://www.visual-paradigm.com/guide/agile-software-development/what-is-user-story/ or https://www.atlassian.com/agile/project-management/user-stories._

### Adding clarity with Acceptance Criteria

In addition to this part, we have to define a set of conditions that must be met for the user story to be considered complete and accepted by the product owner or stakeholders. This is what is called **Acceptance Criteria**.

Here is how they can be composed:

> - The product listing page displays a grid of products.
> - Each product card shows the product image, name, and price.
> - The product list has a maximum of 4 items per row.
> - The list does not have pagination or infinite scrolling functionality (for the MVP).

_**Note**: You can learn more about acceptance criteria at https://www.productplan.com/glossary/acceptance-criteria/ or https://www.altexsoft.com/blog/acceptance-criteria-purposes-formats-and-best-practices/._ 

#### How to compose effective Acceptance Criteria

**Focus on user outcomes**: Instead of specifying technical details, focus on what the user should be able to achieve or experience when the feature is implemented.

**Use clear and concise language**: Write in plain language that everyone, including non-technical stakeholders, can understand. Avoid vague terms like "_user-friendly_" or "_intuitive_." Be specific about what the user should see, do, or experience.

**Each criterion should be verifiable**: Write criteria that can be objectively tested to determine if they have been met. Use specific values or conditions whenever possible.

**Collaborate with stakeholders**: Work with the product owner, designers, and other stakeholders to ensure the acceptance criteria accurately reflect their expectations. Share your draft acceptance criteria with stakeholders early on to gather feedback and make necessary adjustments.

### Benefits of using User Stories and Acceptance Criteria

**User-Centric Focus**: The core principle of user stories is to shift the perspective from a purely functional description to understanding the user's needs and motivations. By framing the requirement as "As a potential customer, I want to see a list of products... so that I can quickly browse and compare products," you immediately highlight the value the feature brings to the user. This helps the team focus on delivering solutions that directly address user needs.

**Shared understanding**: User stories create a common language between stakeholders (including the PM, designers, and developers). The simple "_As a... I want... so that..._" format is easy to understand and avoids technical jargon. This ensures everyone is aligned on the purpose of the feature and what it needs to accomplish.

**Clearer priorities**: User stories are easier to prioritize than purely functional requirements. By understanding the "why" behind the feature, stakeholders can assess its importance relative to other features and prioritize development efforts accordingly.

**Flexibility and adaptability**: User stories are inherently flexible. They are not rigid specifications but rather invitations for conversation and collaboration. As the team learns more about user needs and technical constraints, the user story can be refined and adapted without requiring a complete rewrite of the requirements.

**Testable outcomes**: User stories naturally lead to the definition of acceptance criteria, which are specific, measurable conditions that must be met for the story to be considered complete. This creates a clear definition of "done" and facilitates testing and quality assurance.

### Documenting the discussions

Once I've thoroughly discussed and clarified the requirements, it's crucial to formally document them in a shared location accessible to the entire team. This documentation serves as a single source of truth, ensuring everyone is aligned and preventing misunderstandings.

Here is how I can translate the first requirement into a user story:

> _**User Story**_:
>
> _As a potential customer, I want to see a clear and visually appealing list of products with their images, names, and prices, so that I can quickly browse and compare items before making a purchase decision._
>
> _**Acceptance Criteria**:_
> - _Layout_:
>     - _The product listing page displays products in a grid layout._
>     - _Each row of the grid contains a maximum of 4 product items._
>     - _The layout is responsive and adapts to different screen sizes._
> - _Product Card Content:_
>     - _Each product card displays a clear product image._
>     - _The product name is prominently displayed below the image._
>     - _The price is displayed clearly, using the appropriate currency symbol._
> - _Functionality:_
>     - _The product list is initially loaded when the user navigates to the product listing page._
> - _MVP Considerations:_
>     - _The product list does not include pagination or infinite scrolling in this initial version._
>     - _Error handling for data fetching issues will be addressed in a later iteration._
> - _Technical Notes:_
>     - _Data Source: Product data will be initially hardcoded on the frontend._
>     - _UI Framework: The Angular Material library will be used for styling and components._

In this e-commerce example, I've translated the first functional requirement into a single user story. However, this is not always the case. A single functional requirement can often give rise to multiple user stories, each representing different perspectives and needs of various users.

In an Agile environment, the responsibility of writing user stories is often shared. While the Product Owner is ultimately accountable for the product backlog, developers can contribute by creating user stories and validating them with the PO to ensure they are clear, concise, and actionable.

### The importance of clarifying and refining requirements

As you've seen, even a seemingly simple requirement like "_Display a list of products with their images, names, and prices_" can raise numerous questions. Before a single line of code is written, it's crucial to address these questions through collaborative discussions with the Product Owner and other stakeholders.

**Why not assume? The value of shared understanding**

While it might be tempting to make assumptions based on experience or best practices (e.g., assuming a grid layout for the product list), it's essential to resist that urge. Explicitly discussing design choices and technical considerations with stakeholders ensures everyone is on the same page.

For instance, while a grid layout might seem like the obvious choice, the PO might have a different vision in mind or specific design constraints to consider. By collaborating early on, we avoid misunderstandings, reduce the risk of rework, and build a product that aligns with everyone's expectations.

**Business value first: Balancing innovation and practicality**

As developers, we're often eager to implement cutting-edge features or solve complex technical challenges. However, it's crucial to remember that our primary goal is to deliver business value. This means prioritizing features that directly address user needs and contribute to the product's success.

In the context of an MVP (Minimum Viable Product), the focus should be on getting the core functionality working quickly and efficiently. We can always add more sophisticated features and optimizations in later iterations, based on user feedback and evolving business needs.

**The Agile mindset: Embracing iteration and feedback**

This approach aligns with the core principles of Agile development methodologies:
- **Incremental Delivery**: Start with a basic version of the product and gradually add features and refinements.
- **Continuous Feedback**: Regularly gather feedback from users and stakeholders to validate assumptions and guide development.
- **Adaptability**: Be prepared to adjust plans and priorities based on feedback and changing requirements.

Remember, we're not just building software; we're building a product that solves real problems for real people. By fostering open communication, clarifying assumptions, and prioritizing user needs, we set ourselves up for success, creating a product that delights users and drives business growth.

### Recap of the clarification process

As I delved into the first requirement, "Display a list of products with their images, names, and prices," several questions and decisions emerged. This seemingly simple requirement opened up a wealth of considerations:

1. Visual Presentation: We recognized the need to clarify the desired layout of the product list. By proposing options and mockups, we ensured a shared understanding of the visual presentation with stakeholders.
2. Data Source: We proactively addressed the absence of a backend API by suggesting mock data for the initial development phase. This keeps the project moving forward while the backend is being developed.
3. Performance and Scalability: We considered the potential for the product list to grow over time. While simpler solutions were prioritized for the MVP, we acknowledged the need for future optimizations like pagination or infinite scrolling if the list becomes extensive.
4. Responsiveness: We discussed the importance of responsiveness across different devices, but agreed to focus on the desktop version for the MVP, prioritizing timely delivery.
5. Documentation: We emphasized the importance of documenting these decisions and assumptions, creating a clear reference point for the team and stakeholders.

This clarification process revealed a crucial shift in perspective. Initially, we focused on the technical **_what_** - the specific steps to implement the product list. However, by engaging in discussions and exploring different options, we naturally began to consider the **_why_** - the user's needs and the value this feature would bring to them.

This shift in focus leads us to the next logical step: framing the requirement as a user story and defining clear acceptance criteria. User stories provide a powerful tool for encapsulating the user's perspective and goals, while acceptance criteria serve as a checklist to ensure we meet those expectations.

## Summarize and looking ahead

In this article, I've explored the initial steps of building an Angular e-commerce application. By carefully analyzing and clarifying even a seemingly simple requirement like "_Display a list of products_", I've demonstrated the importance of understanding the underlying user needs and business goals. I've also highlighted the value of collaborative discussions with stakeholders, documenting decisions, and prioritizing features for the MVP.

In the next article, I'll dive deeper into the **technical design** and **implementation** of the product listing page. We'll explore how to structure our Angular components, fetch data from a mock source, and leverage Angular Material to create a visually appealing and user-friendly interface. Stay tuned for the next article in the series, where I'll continue the journey towards building a successful e-commerce platform

______

What are your thoughts on the importance of user stories and acceptance criteria? Have you encountered similar challenges in your own projects? Share your experiences and insights in the comments below!