Folder Architecture at Scale: How to Organize React, Angular, and Node.js Projects with SOLID and Clean Architecture

If you have ever had to add a simple field to a form and found yourself navigating through five folders in the project root (/components, /services, /types, /hooks, /utils), you have been a victim of file-type architecture.

At the beginning of a software project, grouping files by what they are (components with components, services with services) seems clean and intuitive. However, as the application scales to hundreds of screens and business rules, this approach turns into a cognitive nightmare. Coupling skyrockets, cohesion goes out the window, and deleting an old feature without breaking the system becomes an impossible mission.

Today, many high-performance teams in React, Angular, and Node.js converge on Domain/Feature-Scoped Organization — often loosely called Vertical Slices.

In this article, we will dissect how to structure folders for modern applications across the frontend and backend, demonstrating how the principles of SOLID, DRY, and Separation of Concerns (SoC) shape this architecture in practice.

1. The Golden Principle: Colocation and Cohesion

Before looking at specific frameworks, we need to understand the fundamental rule governing modern architectures: code that changes together should live together.

This is what we call Colocation. If the screen component for a shopping cart needs a shipping-cost hook, a specific TypeScript interface, and an API call, all of these files should live inside the Cart feature folder, rather than being scattered globally across the project.

The Architectural Acid Test: If your Product Owner asked you to remove the "Wishlist" feature today, could you delete the /features/wishlist folder, remove the route that uses it, and have the project compile without errors? If the answer is no, your coupling is too high.

2. The Theoretical Foundation: SOLID and DRY in the File System

A good folder structure is the physical manifestation of software engineering principles in your repository. Here is how they apply to our organization:

SOLID in Folder Practice

• S — Single Responsibility Principle (SRP): In the legacy model, a UserController or GlobalServices file accumulated business rules, HTTP validation, and database queries. In our structure, we isolate responsibilities. In Node.js, a file in use-cases/create-order.usecase.ts has only one reason to change: the order business rule. It ignores the HTTP protocol (the controller's responsibility) and the database (the repository's responsibility).
• O — Open/Closed Principle (OCP): Your system should be open for extension but closed for modification. If you need to add a new payment method in the frontend, you do not edit an existing massive component; you create a new folder inside features/billing/components/ (e.g., /pix-checkout/) with a component that implements the payment-method contract the checkout already consumes, and register it in the list of methods. The checkout, which only knows that contract, doesn't change; the only existing line that moves is the registration.
• L — Liskov Substitution Principle (LSP): Any implementation of order.repository.interface.ts — the production prisma-order.repository.ts or an in-memory repository in tests — must be able to stand in for the interface without the use case noticing any difference in behavior.
• I — Interface Segregation Principle (ISP): We avoid the global /types folder containing a 3,000-line index.ts file. By placing the types/ or dto/ folder inside each specific module, we ensure that a component consumes only the strict contracts necessary for its functionality, without relying on type definitions from other areas of the system.
• D — Dependency Inversion Principle (DIP): Our business rules depend on abstractions (interfaces), not concrete implementations. This allows us to swap external libraries or databases by simply replacing the file in the infrastructure layer, without rewriting the domain logic.

Strategic DRY (And the Coupling Trap)

The Don't Repeat Yourself (DRY) principle is often applied blindly by developers. In our architecture, it shows up most visibly in pure infrastructure and generic UI (/shared, /components/ui, /lib). Buttons, modals, and HTTP clients are written only once.

However, in business rules, you have to tell duplicated knowledge — which is what DRY targets — apart from shapes that merely coincide. If the OrderDTO entity in the Orders module has the exact same four fields as the InvoiceDTO in the Billing module, do not try to unify them into a BaseGlobalDTO in /shared.

Accidental duplication across different domains is far cheaper than premature coupling. If the tax department requires a new field on the invoice tomorrow, the orders module should not be impacted.

3. Angular: The Standalone Era and Practical DDD

With Standalone APIs as the default (since Angular 19) and NgModules now optional, Angular shed much of its bureaucratic complexity. The modern pattern draws heavy inspiration from Nx library types (feature, ui, data-access, util) and lightweight Domain-Driven Design (DDD) concepts.

We divide the application into four macro-categories: core, shared (or ui), features, and data-access.

Recommended Structure for Angular

src/
 ├─ app/
 │   ├─ core/                     # Singleton services, interceptors, and global guards
 │   │   ├─ auth/
 │   │   │   ├─ auth.guard.ts
 │   │   │   └─ auth.service.ts
 │   │   └─ http/
 │   │       └─ error.interceptor.ts
 │   │
 │   ├─ shared/                   # "Dumb" and generic UI (Design System)
 │   │   ├─ ui/
 │   │   │   ├─ button/
 │   │   │   └─ modal/
 │   │   └─ utils/
 │   │
 │   ├─ features/                 # Business slices (Vertical Slices)
 │   │   ├─ checkout/
 │   │   │   ├─ components/       # Internal components exclusive to checkout
 │   │   │   ├─ services/         # Checkout presentation logic
 │   │   │   ├─ checkout.routes.ts # Lazy Loaded route
 │   │   │   └─ checkout.component.ts
 │   │   │
 │   │   └─ catalog/
 │   │
 │   └─ data-access/              # External API communication and Global State (Signals)
 │       ├─ products/
 │       │   ├─ products.api.ts
 │       │   ├─ products.store.ts # SignalStore / State
 │       │   └─ products.types.ts
 │       └─ user/

• Separation of Concerns (SoC): The data-access folder centralizes HTTP calls and state management (SignalStore). The features/ layer consumes this data without knowing how it was fetched or tagged in the cache. This is a deliberate exception to the colocation rule from section 1: data used by several features (products show up in both the catalog and the checkout) gets its own folder; data owned by a single feature stays inside it — in Nx, libs/<domain>/data-access.
• UI Isolation: Anything inside features/checkout/components is private. If features/catalog needs the same product card, that component must be refactored and promoted to shared/ui.

4. React: Feature-Scoped Architecture and Barrel Files

In the React ecosystem (whether Next.js with App Router or SPAs with Vite), architectural freedom often leads to traumatic refactoring. The most resilient structure adopts the Bulletproof React methodology, abandoning bloated global folders in favor of self-sufficient modules.

Recommended Structure for React

src/
 ├─ app/                          # Routing (Next.js App Router or React Router setup)
 │   ├─ (public)/
 │   └─ (authenticated)/
 │       └─ dashboard/
 │           └─ page.tsx          # The page acts purely as a Feature orchestrator!
 │
 ├─ components/                   # Global UI components (Shadcn / Tailwind)
 │   ├─ ui/
 │   │   ├─ button.tsx
 │   │   └─ dialog.tsx
 │   └─ layouts/
 │
 ├─ lib/                          # External client configurations (Axios, QueryClient)
 │   ├─ axios.ts
 │   └─ react-query.ts
 │
 ├─ features/                     # The core of the application
 │   ├─ billing/
 │   │   ├─ api/                  # TanStack Query hooks (useInvoice, usePay)
 │   │   ├─ components/           # InvoiceList, PaymentModal
 │   │   ├─ hooks/                # Local feature hooks (useTaxCalculator)
 │   │   ├─ types/                # DTO interfaces restricted to billing
 │   │   └─ index.ts              # BARREL FILE: Exports only what is public!
 │   │
 │   └─ projects/
 │
 └─ stores/                       # Global state (Zustand, when strictly necessary)
     └─ use-theme-store.ts

The Power of the Barrel File (index.ts)

Inside each React feature, we maintain an index.ts file at the root acting as the module's public API. (This is where we part ways with Bulletproof React, which now discourages barrel files because they hurt tree shaking in Vite; adopting the barrel means accepting that cost in exchange for an explicit boundary.) If the Dashboard page needs to render the invoice list, it imports:

import { InvoiceList } from '@/features/billing';

The barrel alone doesn't stop anyone from importing deep internal files (such as a private useTaxCalculator hook) by their full path; what enforces encapsulation and information hiding is a lint rule — import/no-restricted-paths or no-restricted-imports — that forbids importing past index.ts.

5. Node.js (NestJS / Express): The Modular Monolith

In the backend, the fundamental mistake is structuring the project by technical layers at the root (/controllers, /models, /repositories). This violates the Single Responsibility Principle at the module level.

Whether using NestJS (which natively guides us down this path) or a clean setup with Express/Fastify, we must design the backend as a Modular Monolith based on Clean Architecture.

Recommended Structure for Node.js

src/
 ├─ config/                       # Environment variables, DB connection, loggers
 ├─ shared/                       # Global middlewares, custom exceptions, decorators
 │   ├─ errors/
 │   └─ middlewares/
 │
 ├─ modules/                      # Business domains (Bounded Contexts)
 │   ├─ orders/
 │   │   ├─ dto/                  # Data Transfer Objects (Zod / Class-Validator)
 │   │   │   ├─ create-order.dto.ts
 │   │   │   └─ order-response.dto.ts
 │   │   │
 │   │   ├─ entities/             # Domain models (no ORM types)
 │   │   │   └─ order.entity.ts
 │   │   │
 │   │   ├─ repositories/         # Database isolation (Repository Pattern)
 │   │   │   ├─ order.repository.interface.ts
 │   │   │   └─ prisma-order.repository.ts
 │   │   │
 │   │   ├─ use-cases/            # Pure business logic (Or Services in NestJS)
 │   │   │   ├─ create-order.usecase.ts
 │   │   │   └─ calculate-discount.usecase.ts
 │   │   │
 │   │   ├─ orders.controller.ts  # HTTP Layer / Data Input & Output
 │   │   └─ orders.module.ts      # Dependency wiring (Dependency Injection)
 │   │
 │   └─ users/
 │
 └─ main.ts                       # Application entrypoint

Strategic Advantages of the Modular Monolith

• Infrastructure Independence (DIP): By isolating use-cases (business logic) from repositories (data access), if the company decides to migrate from MongoDB to PostgreSQL in the future, the code to change stays concentrated in /repositories — as long as entities/ isn't the ORM schema. The business logic remains untouched; migrating the data and handling the transaction differences between the two databases are still separate work.
• Microservices-Ready: If the orders module experiences a severe processing bottleneck and needs to scale independently, boundaries are already drawn. Extracting it into an independent microservice becomes far cheaper: the domain code moves almost intact, and the real work becomes what the network introduces — calls that turn remote, partial failures, transactions that stop being local, and splitting the data.

Conclusion

Software architecture does not exist to bureaucratize engineering work with rigid rules; its main function is cognitive load management.

When we organize React, Angular, or Node.js projects by Features and implement SOLID and DRY principles at the root of our directory structure, we enable any developer to understand, modify, and test a specific slice of the system without needing to load the entire application into their short-term memory.

The next time you start a project or refactor a legacy system, abandon grouping by syntax or file type. Start structuring your code by the business problems it solves.