create-modular-repository-backend 1.0.3

package/bin/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+const path = require("path");
+const fs = require("fs");
+const { execSync } = require("child_process");
+
+const projectName = process.argv[2] || "repository-backend";
+const targetDir = path.join(process.cwd(), projectName);
+
+if (fs.existsSync(targetDir)) {
+  console.error("❌ Folder already exists");
+  process.exit(1);
+};
+
+console.log("🚀 Creating Moduler Repository Backend:", projectName);
+
+// copy template
+fs.cpSync(
+  path.join(__dirname, "../template"),
+  targetDir,
+  { recursive: true }
+);
+
+// install deps
+console.log("📦 Installing dependencies...");
+execSync("npm install", { cwd: targetDir, stdio: "inherit" });
+
+//initiate git
+execSync("git init", { cwd: targetDir, stdio: "inherit" } );
+
+console.log("✅ Done!");
+console.log(`👉 cd ${projectName} && npm run dev`);

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "create-modular-repository-backend",
+  "version": "1.0.3",
+  "description": "Scaffold backend with repository pattern",
+  "bin": {
+    "create-modular-repository-backend": "./bin/index.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "keywords": [
+    "backend",
+    "repository-pattern",
+    "express",
+    "typescript"
+  ],
+  "license": "MIT"
+}

package/template/app.ts

@@ -0,0 +1,19 @@
+import express from 'express';
+import cors from 'cors';
+import config from './config/serverConfig';
+import {errorMiddleware} from './infrastructure/runtime-framework/express/error.handler'
+
+const app = express();
+
+app.use(cors(config.cors));
+
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+
+// Register routes here (example)
+// app.use('/users', userRoutes);
+
+// Register global error handler last
+app.use(errorMiddleware);
+
+export default app;

package/template/config/serverConfig.ts

@@ -0,0 +1,14 @@
+import { ServerConfig } from '../shared/types/general';
+
+const serverConfig: ServerConfig = {
+    port: 4001,
+    nodeEnv:'development',
+    cors: {
+        origin: [''],
+        credentials: true,
+        method: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']
+    },
+
+};
+
+export default serverConfig;

package/template/infrastructure/db/index.ts

@@ -0,0 +1 @@
+export * from "./mongo";

package/template/infrastructure/db/mongo.ts

@@ -0,0 +1,13 @@
+import mongoose from "mongoose";
+
+export const connectDB = async () => {
+  if (!process.env.MONGO_URI) throw new Error("MONGO_URI not defined");
+
+  try {
+    await mongoose.connect(process.env.MONGO_URI);
+    console.log("✅ MongoDB connected");
+  } catch (err) {
+    console.error("❌ MongoDB connection failed", err);
+    process.exit(1);
+  }
+};

package/template/infrastructure/runtime-framework/express/async.handler.ts

@@ -0,0 +1,11 @@
+//Express does not catch async errors automatically.
+export const asyncHandler =
+  (fn: any) =>
+  (req:any, res: any, next: any) =>
+    Promise.resolve(fn(req, res, next)).catch(next);
+  
+//use it like this
+// router.get(
+//   "/profile",
+//   asyncHandler(getProfile)
+// );

package/template/infrastructure/runtime-framework/express/error.handler.ts

@@ -0,0 +1,7 @@
+import { Request, Response, NextFunction } from "express";
+import { normalizeError } from "../../../shared/utils/normalizeError"
+
+export const errorMiddleware = (err: unknown, req: Request, res: Response, next: NextFunction) => {
+  const { statusCode, message } = normalizeError(err);
+  res.status(statusCode).json({ message });
+};

package/template/modules/_module/errors/userExists.ts

@@ -0,0 +1,10 @@
+import { AppError } from "../../../shared/base/errors";
+
+export class UserAlreadyExistsError extends AppError {
+  statusCode = 409;
+  isOperational = true;
+
+  constructor() {
+    super("User already exists");
+  }
+}

package/template/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "repository-backend",
+  "private": true,
+  "scripts": {
+    "dev": "ts-node-dev src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "jsonwebtoken": "^9.0.3",
+    "bcryptjs": "^3.0.3",
+    "cors": "^2.8.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "ts-node-dev": "^2.0.0",
+    "@types/express": "^4.17.21",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/cors": "^2.8.19"
+  }
+}

package/template/readme.md

@@ -0,0 +1,217 @@
+What a Modular Monolith actually is -
+A single deployable app, but organized by feature, not by layer
+A module owns its data, API, services, and repositories
+
+[Highlights]
+Modules are self-contained: models, entities, services, repositories, controllers.
+Shared folder: reusable, framework-agnostic utilities, types, base classes.
+Infrastructure: Express setup, DB connection, runtime-specific wrappers, error middleware.
+Server.ts: initializes DB connection first, then starts app.
+app.ts: only configures Express (middleware, routes, error handler).
+
+[Folder Structure & Responsibilities]
+-----------------------------------
+template/
+├── config/
+│   └── serverConfig.ts       # Server configuration (port, CORS, etc.)
+├── di/                       # Dependency injection setup
+├── infrastructure/
+│   ├── db/
+│   │   ├── index.ts          # Export DB connections
+│   │   └── mongo.ts          # MongoDB connection logic
+│   └── runtime-framework/express/
+│       ├── async.handler.ts  # Wrapper for async route handlers
+│       └── error.handler.ts  # Express global error middleware
+├── modules/_module/
+│   ├── api/
+│   │   ├── controllers/      # Route controllers
+│   │   ├── enums/            # Module-specific enums
+│   │   ├── middlewares/      # Module-specific middlewares
+│   │   └── routes/           # Express routes for the module
+│   ├── domain/
+│   │   ├── entity.ts         # Module-specific business entity
+│   │   └── projection.ts     # DTOs / projections for queries
+│   ├── errors/
+│   │   └── userExists.ts     # Module-specific errors
+│   ├── mappers/              # Maps between entities, DTOs, DB models
+│   ├── persistance/
+│   │   ├── interface/        # Repository interfaces
+│   │   └── model/            # Module-specific DB models
+│   ├── repository/           # Repository implementations
+│   ├── services/             # Business logic / service layer
+│   └── index.ts              # Module export point
+├── shared/
+│   ├── base/
+│   │   ├── BaseRepository.ts # Generic base repository for CRUD
+│   │   ├── errors.ts         # AppError, NotFoundError, ValidationError, etc.
+│   │   └── IBaseRepository.ts# Interface for base repository
+│   ├── types/
+│   │   └── general.d.ts      # Global types/interfaces
+│   └── utils/
+│       └── normalizeError.ts # Normalizes errors for middleware
+├── .env                      # Environment variables
+├── .gitignore
+├── app.ts                     # Express app configuration
+├── package.json
+└── server.ts                  # Server entry point; connects DB & starts app
+
+
+[Responsibilities / Rules]
+------------------------
+1. config/
+Store configuration variables (server port, CORS, JWT secrets).
+Should not contain logic.
+
+2. di/
+Handles dependency injection if required.
+Modules should remain decoupled, use DI for services/repositories.
+
+3. infrastructure/
+Any code that interacts with the outside world:
+DB connections
+Express-specific middleware
+Async handler wrappers
+No business logic here.
+
+4. modules/
+Encapsulates domain, services, repositories, controllers for a single feature.
+Each module owns:
+Models: persistance/model → DB schema
+Entities: domain/entity.ts → business objects
+Repository interfaces: persistance/interface
+Repository implementations: repository/
+Services: business logic
+Controllers: handle HTTP requests
+Modules should not know about other modules.
+
+5. shared/
+Contains generic reusable code:
+Base repository
+Shared types
+Global errors
+Utilities (like normalizeError)
+Must be framework-agnostic — no Express-specific code here.
+
+6. app.ts
+Sets up Express app:
+Middleware
+Routes
+Global error handler
+Does not start server or connect DB.
+
+7. server.ts
+Entry point:
+Connects to DB (connectDB())
+Starts server (app.listen())
+Handles runtime concerns only.
+
+
+[Data Flow (Request → Response)]
+------------------------------
+-HTTP request → controller (modules/<module>/api/controllers)
+-Controller → service (modules/<module>/services)
+-Service → repository (modules/<module>/repository)
+-Repository → DB model (modules/<module>/persistance/model)
+-DB returns → repository → service → controller
+-Controller returns → response
+Errors:
+-Services / repositories throw AppError (or module-specific errors)
+-normalizeError (shared/utils) converts errors into {statusCode, message}
+-error.handler.ts (infra) sends JSON HTTP response
+
+[Rules / Best Practices]
+----------------------
+-Modules are independent → avoid cross-module imports.
+-Shared folder is framework-agnostic.
+-Infrastructure folder handles DB, HTTP, queues, and other external systems.
+Error handling:
+-Throw AppError or module-specific error
+-Use async handler wrapper in controllers
+-Let errorMiddleware handle HTTP response
+-DB connections happen in server.ts only; modules access DB through repositories.
+-app.ts is testable without server or DB.
+
+
+[Modular Monolith Flow]
+---------------------
+
+        ┌──────────────┐
+        │   HTTP Client│
+        └───────┬──────┘
+                │
+                ▼
+    ┌───────────────────┐
+    │   modules/*/api   │
+    │  (controllers +   │
+    │    routes)        │
+    └────────┬──────────┘
+            │ calls
+            ▼
+    ┌───────────────────┐
+    │ modules/*/services│
+    │  (business logic) │
+    └────────┬──────────┘
+            │ calls
+            ▼
+    ┌───────────────────────┐
+    │ modules/*/repository  │
+    │(implements interfaces │
+    │    for DB access)     │
+    └────────┬──────────────┘
+            │ interacts with
+            ▼
+    ┌─────────────────────┐
+    │modules/*/persistance│
+    │(DB models/schemas)  │
+    └────────┬────────────┘
+            │ connects to
+            ▼
+    ┌───────────────────┐
+    │ infrastructure/db │
+    │   (connectDB,     │
+    │     Mongo/PG)     │
+    └────────┬──────────┘
+            │ initializes
+            ▼
+        Database
+        (Mongo/Postgres)
+
+
+[Shared & Utilities Flow]
+-----------------------
+┌─────────────────────────┐
+│        shared/          │
+│ ┌─────────────────────┐ │
+│ │ base/               │ │
+│ │  - BaseRepository   │ │
+│ │  - errors.ts        │ │
+│ │  - IBaseRepository  │ │
+│ └─────────────────────┘ │
+│ ┌─────────────────────┐ │
+│ │ types/              │ │
+│ │  - general.d.ts     │ │
+│ └─────────────────────┘ │
+│ ┌─────────────────────┐ │
+│ │ utils/              │ │
+│ │  - normalizeError   │ │
+│ └─────────────────────┘ │
+└─────────────┬───────────┘
+              │ used by
+              ▼
+        modules/* and infrastructure
+
+
+[Error Handling Flow]
+-------------------
+Modules Services / Repository
+        │
+        │ throw AppError or module-specific errors
+        ▼
+normalizeError() in shared/utils
+        │
+        ▼
+errorMiddleware in infrastructure/runtime-framework/express
+        │
+        ▼
+Client HTTP Response
+(Status code + JSON message)

package/template/sever.ts

@@ -0,0 +1,17 @@
+import app from './app';
+import serverConfig from './config/serverConfig';
+import { connectDB } from './infrastructure/db';
+
+const startServer = async () => {
+  try {
+    await connectDB(); // connect to DB first
+    app.listen(serverConfig.port, () => {
+      console.log(`Server running on http://localhost:${serverConfig.port}`);
+    });
+  } catch (err) {
+    console.error('Failed to start server', err);
+    process.exit(1);
+  }
+};
+
+startServer();

package/template/shared/base/errors.ts

@@ -0,0 +1,39 @@
+// shared/base/errors.ts
+export abstract class AppError extends Error {
+  abstract statusCode: number;
+  abstract isOperational: boolean;
+
+  constructor(message: string) {
+    super(message);
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+export class NotFoundError extends AppError {
+  statusCode = 404;
+  isOperational = true;
+
+  constructor(resource = "Resource") {
+    super(`${resource} not found`);
+  }
+}
+
+export class ValidationError extends AppError {
+  statusCode = 400;
+  isOperational = true;
+}
+
+export class UnauthorizedError extends AppError {
+  statusCode = 401;
+  isOperational = true;
+}
+
+export class ForbiddenError extends AppError {
+  statusCode = 403;
+  isOperational = true;
+}
+
+export class ConflictError extends AppError {
+  statusCode = 409;
+  isOperational = true;
+}

package/template/shared/types/general.d.ts

@@ -0,0 +1,55 @@
+export { ParsedQs } from 'qs';
+
+export type ServerConfig = {
+  port: number,
+  nodeEnv: string,
+  cors: Cors
+};
+
+export type Cors = {
+  origin: string[],
+  credentials: boolean,
+  method: string[],
+};
+
+type StringKeys<T> = {
+  [K in keyof T]: T[K] extends string ? K : never
+}[keyof T];
+
+export type SearchConfig<T> = {
+  searchableFields: StringKeys<T>[];
+  sortableFields: (keyof T)[];
+  statusField?: keyof T;
+  defaultSortField: keyof T;
+  defaultSortOrder?: "asc" | "desc";
+  dateField?: keyof T;
+};
+
+export type PaginatedResponse<T> = {
+  data: T[];
+  pagination: {
+    page: number;
+    pageSize: number;
+    totalRecords: number;
+    totalPages: number;
+  };
+};
+
+
+export type SearchFilterSortParamsType = {
+  search: string,
+  startDate: string,
+  endDate: string,
+  status: boolean | undefined,
+  sortColumn: string,
+  sortDirection: string,
+  page: number,
+  pageSize: number,
+  role?: string,
+  isBlocked?: boolean,
+}
+
+export type TokenType = {
+  accessToken: string;
+  refreshToken: string
+};

package/template/shared/utils/normalizeError.ts

@@ -0,0 +1,8 @@
+import { AppError } from "../base/errors"
+
+export function normalizeError(err: unknown) {
+  if (err instanceof AppError) {
+    return { statusCode: err.statusCode, message: err.message };
+  }
+  return { statusCode: 500, message: "Internal server error" };
+};

package/template/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "target": "es6",
+    "moduleResolution": "node",
+    "sourceMap": true,
+    "outDir": "dist"
+  },
+  "lib": ["es2015"]
+}