Folder Structure

NeatNode provides different folder structures for JavaScript and TypeScript templates, each optimized for clarity and scalability.

JavaScript Templates - Structure Options

Used by Basic (JS), REST API (JS), and Socket.IO (JS) templates.

For the REST API (JS) template, you have the choice between two architectures:

MVC (Layer-based): Separates files globally by type (controllers, models, routes).
Modular (Feature-based): Groups files by domain/feature inside a modules/ folder (e.g., modules/user/).

1. MVC / Layer-based Structure


<project-root>/
├── .env
├── .env.example
├── eslint.config.js
├── package.json
├── server.js
└── src/
    ├── app.js
    ├── config/
    ├── controllers/
    ├── middleware/
    ├── models/
    ├── routes/
    ├── schemas/
    ├── services/
    └── utils/

This structure follows a layer-based architecture, separating concerns globally.

2. Modular Structure


<project-root>/
├── .env
├── .env.example
├── eslint.config.js
├── package.json
├── server.js
└── src/
    ├── app.js
    ├── config/
    ├── core/
    │   ├── middleware/
    │   └── utils/
    ├── modules/
    │   └── user/
    │       ├── user.controller.js
    │       ├── user.model.js
    │       ├── user.route.js
    │       ├── user.service.js
    │       └── user.validation.js
    └── routes/
        └── index.route.js

This structure keeps related feature logic bundled together, with shared utilities in core/.

JavaScript Template Folders `/src`

MVC Architecture

controllers/

Request handlers mapped to routes.

routes/

Defines API endpoints.

services/

Business logic and database interactions.

models/

Mongoose schemas or DB models.

schemas/

Validation schemas (e.g., Joi).

middleware/

Auth, validation, and error handling.

utils/

Shared helpers like ApiError, ApiResponse, CatchAsync.

Modular Architecture

modules/<feature>/

Groups related logic by feature. Contains its own controller, route, service, model, and validation.

routes/

Contains index.route.js which collects and registers all module routes.

core/middleware/

Global middlemare for auth, generic error handling, and rate limiting.

core/utils/

Shared global helpers like ApiError, ApiResponse, CatchAsync.

TypeScript Templates - Modular Architecture

NeatNode TypeScript templates follow a feature-based modular architecture with a clear separation between application infrastructure, shared utilities, and business modules.


<project-root>/
├── package.json
├── tsconfig.json
└── src/
    ├── app.ts
    ├── server.ts
    ├── core/
    │   ├── config/
    │   └── middlewares/
    ├── shared/
    │   ├── types/
    │   └── utils/
    ├── modules/
    │   └── auth/
    │       ├── auth.controller.ts
    │       ├── auth.route.ts
    │       ├── auth.service.ts
    │       ├── auth.validation.ts
    │       └── user.model.ts
    └── routes/
        └── index.route.ts

This structure separates framework-level concerns from business logic, making projects easier to scale and maintain.

TypeScript Template Folders `/src`

`core/`

Contains application-wide infrastructure and framework-related code.


core/
├── config/
└── middlewares/

config/

Application configuration such as:

Database connection
Environment configuration
Logger setup
Third-party service configuration

middlewares/

Reusable middleware shared across the application:

Authentication
Authorization
Request validation
Error handling
Rate limiting

`shared/`

Contains reusable code shared across modules.


shared/
├── types/
└── utils/

types/

Global TypeScript types and interfaces.

Examples:

Express request extensions
JWT payload types
Shared DTOs

utils/

Reusable helpers and utility classes.

Examples:

ApiError
CatchAsync
sendResponse
Token helpers
Pagination utilities

`modules/`

Contains feature-based business modules.

Each module owns its controller, service, route, validation, and model files.

Example:


modules/auth/
├── auth.controller.ts
├── auth.route.ts
├── auth.service.ts
├── auth.validation.ts
└── user.model.ts

Benefits:

Better scalability
Easier navigation
Clear ownership of business logic
Reduced coupling between features

`routes/`

Contains route registration and aggregation.

Example:


routes/
└── index.route.ts

Responsible for mounting all module routes into the Express application.

Request Flow


Route
  ↓
Controller
  ↓
Service
  ↓
Model
  ↓
Response

Infrastructure concerns such as authentication, validation, and error handling are managed through the core/ layer, while reusable helpers live inside shared/.

Why This Structure?

The TypeScript template separates concerns into three clear areas:


core/
    ↓
Application Infrastructure

shared/
    ↓
Reusable Utilities & Types

modules/
    ↓
Business Features

✅ Summary

JS templates → layer-based structure
TS templates → layer-based (Basic) and module-based (REST API)
Same concepts, different organization
Easy to scale, easy to understand

[!TIP] Once you understand one template, switching between JS and TS is straightforward.