structuring large-scale Node.js applications?

[ghost]

Hi everyone,

I’m working on a growing Node.js project and starting to feel the pain of scaling the codebase.

I’d like to understand:

→ What folder structure patterns are recommended for large Node.js apps?
→ Is feature-based architecture better than layer-based (controllers/services/routes)?
→ How do you manage shared utilities and middleware cleanly?
→ Any production-grade examples or best practices?

Would appreciate advice from people managing real-world Node.js apps.

Thanks!

[Om-singh-ui]

A scalable Node.js structure should be feature-based rather than purely layer-based.
Instead of:

/controllers  
/services  
/routes  

Prefer grouping by feature:

/modules  
  /auth  
    auth.controller.js  
    auth.service.js  
    auth.routes.js  
  /users  
    user.controller.js  
    user.service.js  
    user.routes.js  

Why?

1. Better scalability – each feature is self-contained.
2. Easier onboarding – developers work inside one domain folder.
3. Reduced cross-dependency mess.

For production apps:

• Use a central error middleware.
• Keep business logic in services.
• Keep controllers thin.
• Avoid placing logic in routes.

This keeps your app maintainable as it grows.

[Harmeet10000]

I agree with @Om-singh-ui that it should be a featured based approach. I want to improve it further

├── .agents/skills/          # Agent skill definitions
├── docker/                  # Docker configurations
├── docs/                    # Documentation
│   └── websockets/
│   └── api/
│   └── workers/
├── .husky/                  # Git hooks
├── .github/                  
│   └── ISSUE_TEMPLATE/
│   └── PULL_REQUEST_TEMPLATE/
│   └── skills/
│   └── workflows/
│   └── copilot-instrcutions.md
├── infra/                   # Infrastructure (AWS, k8s)
│   └── aws/
│   └── azure/
│   └── gcp/
├── nginx/                   # Nginx config
├── scripts/                 # Build/deploy scripts
├── src/                     # Source code
│   ├── app/                 # Main application
│   │   ├── api/             # API routes
│   │   ├── config/          # Configuration
│   │   ├── connections/     # External connections
│   │   ├── examples/        # Example code
│   │   ├── features/        # Feature modules
│   │   |     ├── auth/     
│   │   |     ├── health/     
│   │   |     ├── storage/ 
│   │   |     ├── search/     
│   │   ├── helpers/         # Helper functions
│   │   ├── middlewares/     # Express middlewares
│   │   └── utils/           # Utilities
│   ├── db/                  # Database
│   │   ├── migrations/      # Drizzle migrations
│   │   ├── schema/          # Database schema
│   │   └── seeders/         # Seed data
│   └── workers/             # Background workers
├── tests/                   # Test suites
│   ├── e2e/
│   ├── integration/
│   ├── performance/
│   └── unit/
├── docker-compose.yml
├── package.json 

This structure supports scalability in several key ways:

1. Separation of Concerns

• src/app/ - Application logic (routes, features, helpers)
• src/db/ - Data layer (schema, migrations, seeders) isolated from business logic
• src/workers/ - Background jobs separate from HTTP handling
• tests/ - Tests organized by type (unit, integration, e2e, performance)

2. Modular Feature Architecture

• src/app/features/ - Each feature can be a self-contained module, making it easy to add/remove features without affecting others

3. Scalability-Ready Patterns

• Database: Drizzle ORM with migrations support schema evolution
• Workers: Background processing layer ready for async tasks (emails, webhooks, etc.)
• Infrastructure: AWS/k8s configs for horizontal scaling

4. Developer Experience

• scripts/ - Automation for common tasks
• .husky/ - Enforced code quality via git hooks
• Organized tests enable fast feedback loops

5. Production-Ready

• Docker + Nginx + Docker Compose for deployment
• Environment-specific configs (.env.development)
• CI/CD in .github/
  The structure follows domain-driven design principles with clear boundaries, making it easy to onboard new developers and scale the team