🚀 Node.js Modular Monolith Starter

A robust Node.js backend starter for building scalable, maintainable APIs using a modular monolith architecture. Designed for rapid development, clear separation of concerns, and easy extensibility—ideal for teams and solo developers alike.

🏗️ What is a Modular Monolith?

A modular monolith organizes your codebase into distinct, self-contained modules (features), all running within a single application. This approach combines the simplicity of a monolith with the flexibility of microservices—making it easier to scale, refactor, and onboard new contributors.

Key Benefits:

• Clear boundaries between features (auth, users, articles, etc.)
• Easier testing and maintenance
• Seamless refactoring and future migration to microservices
• Shared infrastructure and code reuse

✨ Starter Features

• TypeScript-first: Type safety and modern tooling
• Role-based access control: Admin, Editor, Writer, Reader
• RESTful APIs: Modular endpoints for users, articles, comments
• Real-time support: Socket.IO for live features
• OpenAPI docs: Auto-generated Swagger documentation
• Docker-ready: Effortless local and production setup
• Data validation: Joi for robust input checks
• Extensible modules: Add new features with minimal friction

⚡ Getting Started

Prerequisites

• Node.js v18+
• pnpm (recommended)
• Docker & Docker Compose (optional)

Local Development

git clone [email protected]:omarl68/modular-monolith-starter.git
cd modular-monolith-starter
pnpm install
cp .env.example .env
# Edit .env for your MongoDB URI and other settings
pnpm run start:dev

Server runs at: http://localhost:3001

Docker Development

make dev         # Start dev environment
make dev-build   # Build and start dev
make dev-down    # Stop dev environment

Production

pnpm run build
pnpm run start:prod
# Or with Docker:
make prod-build
make prod

🗂️ Project Structure

/project-root/
├── src/
│   ├── modules/      # Feature modules (auth, users, articles, comments)
│   ├── core/         # Shared logic (auth, base services)
│   ├── routes/       # Route definitions
│   ├── types/        # TypeScript types
│   ├── utils/        # Helpers
│   └── app.ts        # Express config
├── scripts/          # Seeders, CLI tools
├── public/           # Static files
├── Makefile          # Docker/project commands
├── .env.example      # Sample env file
└── ...

🛠️ How to Add a New Module

1. Create a folder in src/modules/ (e.g., src/modules/notifications)
2. Define routes, controllers, services, and types inside your module
3. Register your module in the main app (src/app.ts)
4. Add tests and update documentation

📑 API Documentation

• Swagger UI: http://localhost:3001/api-docs
• Docs location: src/docs/
• Tags: Auth, User, Article, Comment, Role

🧪 Testing

pnpm test         # Run tests
pnpm test:watch   # Watch mode
make test         # Run tests in Docker

🔐 Roles & Permissions

Role	Permissions
Admin	Manage users, all articles
Editor	View/edit/write articles
Writer	Write/edit own articles
Reader	View articles

📝 Contributing

• Fork & branch for features
• Follow TypeScript and ESLint guidelines
• Write tests for new modules
• Update docs for changes

🐛 Troubleshooting

• MongoDB issues: Check connection string and server status
• Port conflicts: Change PORT in .env
• Docker problems: Use make clean and rebuild

📜 License

MIT License. See LICENSE.

---

Build modular, scale confidently, and ship faster!