Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 2

From User Flows to Technical Specifications

Recommended resources

In our last lesson, we focused on the initial planning phase, learning how to deconstruct a broad idea into user roles, user stories, and the user flows that visualize their journey. This process helps us understand what the application needs to do from a human perspective.

Now, we will build on that foundation by translating those user-centric plans into a preliminary technical blueprint. This lesson is about converting user flows into the three core components of a MERN application: the pages a user sees, the database entities that hold the information, and the API endpoints that connect the two. Mastering this translation is the crucial step that moves you from following tutorials to architecting your own applications, a key part of your goal to "think like a developer."

1. From User Flows to Frontend Pages

The most direct translation from your planning work is from user flows to the pages or views of your application. Each significant step, screen, or decision point in a user flow diagram often corresponds to a "page" in a traditional web app, or a major component view in a single-page application (SPA) like one built with React.

Consider the user flow for a stock recommendation app shown below.

This flowchart shows the navigation structure of a stock application. Each node, like "Recommendation Page" or "Portfolio Details Page," represents a distinct view the user interacts with.

You can see a clear mapping:

  • The "Recommendation page" circle translates to a React component that shows stock recommendations, likely at a URL like /recommendations.
  • The path from "Portfolio Page" to "Portfolio Details Page" to "Stock Details" implies a nested routing structure in React Router, perhaps /portfolio, /portfolio/:portfolioId, and /portfolio/:portfolioId/stocks/:stockId.

For the inventory system we discussed, a user flow like "Admin logs in, navigates to the product list, and clicks to add a new product" immediately suggests the need for:

  1. A Login Page
  2. A Product List Page (an admin dashboard view)
  3. An Add Product Page (likely a form)

Thinking this way gives you an initial sitemap and a to-do list for your React development before you've written any code.

2. Identifying the "Nouns": Database Entities

Once you know what pages you need, the next question is: what information do these pages display and manage? The answer to this question reveals your database entities. Entities are the fundamental "nouns" of your system—the core objects about which you need to store information.

You can often identify these directly from your user stories.

  • "As a user, I want to see my past orders..." -> implies User and Order entities.
  • "As an admin, I want to add a new product to a category..." -> implies Product and Category entities.

A robust inventory management system will have several core entities. The following guide provides an excellent breakdown.

Design Inventory Management System: (Step-by-Step Guide)

This guide from System Design Handbook offers a professional look at architecting a large-scale system. We'll focus on its data modeling section, which provides a clear and practical example of identifying the core entities for an inventory system.

Please read the section titled Database design and data modeling. Pay close attention to the list of core entities (Product, Warehouse, Inventory, Transaction) and the attributes they contain. The ERD diagram in this section is a preview of what we'll be building in the next lesson.

As the article explains, we can identify entities like:

  • Product: Stores catalog information (name, SKU, price).
  • User: For authentication and roles (customer, admin).
  • Order: Represents a customer's purchase, containing multiple products.
  • Inventory: Links a product to a warehouse and tracks its quantity.
  • Transaction: An audit log of all stock movements (sale, restock, return).

Listing these entities and their essential fields (e.g., a Product needs a name and price) is the first step in designing your database schema.

3. Defining the "Verbs": API Endpoints

Your React pages (frontend) can't talk directly to your MongoDB database (backend). They communicate through a contract known as an API (Application Programming Interface). The user's actions on a page—clicking a button, submitting a form—trigger calls to specific API endpoints, which are the "verbs" that operate on your database "nouns."

For example, when a user clicks "Add to Cart" on a Product page:

  1. The React frontend sends a request to an API endpoint.
  2. The Node.js/Express backend receives this request.
  3. The backend logic updates the Cart entity in the database.
  4. The backend sends a response back to the frontend confirming the action.

The process of designing these endpoints can be systematic. The following article outlines a professional, user-centric approach to API modeling.

Before designing an API, model your API: guide - Tyk API Gateway

This article from the Tyk blog provides a structured, five-step process for translating user needs into a concrete API model. This directly addresses your goal of learning how to design API endpoints from scratch.

Please read the article from the section Why API modelling before you design? through the end of "Step 5: Validate your API model." Focus on how it connects user "outcomes" and "steps" (which we've called user stories and user flows) to candidate API resources and actions.

The key takeaway is that you don't just invent endpoints randomly. You derive them from the actions required to fulfill a user flow.

Let's combine this with a more detailed look at the structure of these endpoints. The most common convention for web APIs is REST (Representational State Transfer), which uses standard HTTP methods (GET, POST, PUT, DELETE) to represent actions. This video gives an excellent introduction.

API Design and Architecture - Backend Engineering Intro (1 Hour)

Caleb Curry's video on API Design provides a fantastic, practical walkthrough of how to structure RESTful endpoints.

Please watch the following segments to understand how to structure your API: HTTP Methods: First, watch the explanation of core methods from this section. This covers how GET, POST, and other verbs map to actions. URL Structure: Next, watch how URLs are structured for resources, including versioning and IDs, from this segment. Nesting vs. Filtering: Understand the two main ways to relate resources, discussed from this part. This is a critical design decision. Passing Data: Finally, learn the three ways to send data to an API (path, query, body) and when to use each, from this section.

4. Tying It All Together: An Example Translation

Let's translate a complete user flow for an inventory system into all three components.

User Flow: "An administrator wants to view all products and update the stock level of one of them."

  1. Pages/Views:

    • /admin/products: A Product List Page that shows a table of all products with their current stock.
    • /admin/products/:id: A Product Edit Page with a form to update product details, including the stock quantity.

  2. Database Entities:

    • Product: To store name, sku, description, etc.
    • Inventory: To store productId, quantity, warehouseId.

  3. API Endpoints (following REST conventions):

    • GET /api/v1/products:
      • Action: Fetches a list of all products.
      • Used by: The Product List Page to populate its table.
      • Response: An array of product objects.
    • GET /api/v1/products/:id:
      • Action: Fetches a single product by its ID.
      • Used by: The Product Edit Page to pre-fill the form with the current product data.
      • Response: A single product object.
    • PUT /api/v1/products/:id:
      • Action: Updates an existing product.
      • Used by: The Product Edit Page when the admin submits the form.
      • Request Body: A JSON object with the fields to update, e.g., { "inventory": { "quantity": 150 } }.
      • Response: The updated product object.

This clear, traceable line from user action to frontend page to API endpoint to database entity is the essence of good application architecture.

Conclusion

In this lesson, we bridged the gap between user-focused planning and technical design. By systematically translating user flows, you can create a clear and logical initial architecture for your application.

Key Takeaways:

  • Flows to Pages: User flow diagrams provide a natural starting point for identifying the pages and component views your frontend will need.
  • Needs to Nouns: The information required by these pages and user stories helps you define your core database entities—the "nouns" of your system.
  • Actions to Verbs: The actions users perform within these flows translate into API endpoints—the "verbs" that manipulate your entities using RESTful conventions (GET, POST, PUT, DELETE).
  • Systematic Design: This translation process (Flow -> Page -> Entity -> Endpoint) is a repeatable method for architecting applications, giving you the confidence to build from scratch.

In our next lesson, we will formalize our database design. You will learn to sketch an entity-relationship diagram (ERD) for an inventory management system, creating a visual blueprint of our data model and the connections between entities.