Designing a Scalable Folder Structure for Our Node.js E-commerce API (Clean Architecture + Feature-Based)

Hey folks! 👋

In the last post, we saw how messy traditional code gets when everything (HTTP, business rules, DB) is thrown together. We fixed that with Clean Architecture layers.

But layers alone aren't enough when your app grows to 20+ features. Scrolling through giant controllers/ or services/ folders becomes a nightmare.

The fix? Organize by feature (also called vertical slices or feature-first), while keeping Clean Architecture inside each feature.

Goal Recap

• Related code stays close together
• Easy to navigate and add new features
• Scales beautifully as the e-commerce app grows

Step 1: Identify the Core Business Features

E-commerce revolves around clear business capabilities:

• Users (registration, profiles, addresses)
• Products (catalog, details, search)
• Cart (add/remove items, totals)
• Orders (create, track, cancel)
• Payments (integrate gateways like Stripe/Razorpay)
• Reviews & Authentication (login, JWT, roles)

We group code by these features instead of by type.

src/
└── features/
    ├── users/
    ├── products/
    ├── cart/
    ├── orders/
    ├── payments/
    └── reviews/

Want to work on "products"? Just open src/features/products — everything is right there. No more hunting across folders!

Step 2: Apply Clean Architecture Inside Each Feature

Inside a feature folder, we still separate concerns using Clean layers:

src/
└── features/
    └── users/
        ├── domain/          ← Core business concepts (pure JS/TS, no frameworks!)
        ├── application/     ← Use cases / business flows
        ├── infrastructure/  ← DB, external services (Mongo, email, etc.)
        └── presentation/    ← API controllers, routes, validation

Domain Layer — The Heart ❤️

Pure business rules. No Express, no MongoDB imports.

Contains:

• Entities (e.g., User with methods like changeEmail())
• Value Objects (e.g., Email, Password)
• Repository interfaces (abstract, e.g., IUserRepository)

domain/
├── entities/
│   └── User.js
└── repositories/
    └── IUserRepository.js   // ← just the contract!

Rule: This layer never depends on outer layers or tech. It stays stable forever.

Application Layer — The Brain 🧠

Use cases — what the system can actually do.

Examples: RegisterUser, LoginUser, UpdateProfile, AddAddress

application/
└── use-cases/
    ├── registerUser.js
    ├── loginUser.js
    └── updateProfile.js

These coordinate domain entities + call repositories (via interfaces).

Infrastructure Layer — The Tools 🔧

Concrete implementations of domain interfaces.

infrastructure/
├── repositories/
│   └── MongoUserRepository.js   // implements IUserRepository
└── services/
    └── JwtService.js

Switch DB from Mongo → PostgreSQL? Only change files here. Domain & application stay untouched!

Presentation Layer — The Doorway 🚪

Handles HTTP (Express routes/controllers).

presentation/
├── controllers/
│   └── userController.js
├── routes/
│   └── userRoutes.js
└── dtos/                  (optional: request/response shapes)
    └── registerUser.dto.js

It calls application use cases and returns responses.

Full Example: Users Feature Folder

src/
└── features/
    └── users/
        ├── domain/
        │   ├── entities/
        │   │   └── User.js
        │   └── repositories/
        │       └── IUserRepository.js
        ├── application/
        │   └── use-cases/
        │       ├── registerUser.js
        │       ├── loginUser.js
        │       └── updateProfile.js
        ├── infrastructure/
        │   ├── repositories/
        │   │   └── MongoUserRepository.js
        │   └── services/
        │       └── JwtService.js
        └── presentation/
            ├── controllers/
            │   └── userController.js
            ├── routes/
            │   └── userRoutes.js
            └── dtos/
                └── registerUser.dto.js

Repeat this pattern for products/, orders/, etc.

Classic Clean Architecture (onion) — dependencies point inward

Vertical slices (feature-based) vs traditional horizontal layers — features group everything vertically

Why This Combo Rocks for E-commerce

• High cohesion — All "user" code in one place → faster development
• Low coupling — Features don't touch each other unless needed
• Scalability — Add "subscriptions" or "wishlist" as new feature folders
• Maintainability — New devs onboard quickly ("show me the orders feature")
• Testability — Mock infrastructure → unit test domain & application easily
• Tech independence — Swap DB, framework, or add GraphQL? Minimal pain

This is a pragmatic blend of Clean Architecture (for inner stability) + Vertical Slice (for outer organization). Many production Node.js e-commerce APIs use exactly this.

• Setting up the project