BackGen

![CI](https://github.com/IbrahimKhaled19/BackGen/actions/workflows/ci.yml) ![npm version](https://www.npmjs.com/package/@ibrahimkhaled19/backgen) ![License: MIT](https://opensource.org/licenses/MIT)

![npm downloads](https://www.npmjs.com/package/@ibrahimkhaled19/backgen) ![GitHub stars](https://github.com/IbrahimKhaled19/BackGen)

🤖 AI-Ready

![BackGen MCP server](https://glama.ai/mcp/servers/IbrahimKhaled19/BackGen) ![BackGen MCP server](https://glama.ai/mcp/servers/IbrahimKhaled19/BackGen)

BackGen ships a built-in MCP (Model Context Protocol) server that AI assistants (Claude, Cursor, GitHub Copilot, VS Code) can use to scaffold projects on your behalf.

{
  "mcpServers": {
    "backgen": {
      "command": "npx",
      "args": ["-y", "@ibrahimkhaled19/backgen", "backgen-mcp"]
    }
  }
}

Available MCP tools:

| Tool | Description | |------|-------------| | init_project | Scaffold a new production-ready backend project with chosen ORM, preset, and plugins | | add_plugin | Install a plugin (jwt, clerk, stripe, s3, ratelimit, ci-github, dependabot, codeql, docker-registry, release) | | remove_plugin | Remove a previously installed plugin | | generate_resource | Generate a CRUD resource with fields, relations, validation, and Swagger | | generate_seed | Generate a database seed file for a resource | | generate_factory | Generate a test factory for a resource | | doctor | Validate an existing BackGen project for configuration issues | | list_plugins | List all available plugins with descriptions | | list_presets | List all available domain presets | | project_info | Show project metadata from the manifest |

Then just ask: "Scaffold a SaaS backend with Prisma, JWT auth, and Stripe payments"

---

<img width="1600" height="900" alt="BackGen CLI generating Express.js backend with Prisma, Drizzle, and Mongoose — Swagger docs, Docker, auth, and multi-tenant SaaS preset" src="https://github.com/user-attachments/assets/cd3888d3-fa9d-4e4e-a595-4f10ae039871" /> > Generate production-ready backend foundations so developers can focus on business logic, not boilerplate.

BackGen is a CLI tool that generates complete Express.js backend projects on Prisma, Drizzle, or Mongoose — with authentication, multi-tenant infrastructure, production hardening, Docker, and testing — all working out of the box.

npx @ibrahimkhaled19/backgen init my-api --orm drizzle
cd my-api
npm run dev

Swagger docs at http://localhost:3000/docs in under 60 seconds. Pick your ORM, keep everything else.

---

Features

Express + TypeScript — strict mode, ESLint 9 (flat config), Vitest
Multi-ORM — Prisma, Drizzle, or Mongoose. Pick at init time, switch later via the manifest
SaaS-ready — saas-core preset ships Organizations, Memberships, Invitations, RBAC, tenant-scoped queries
Hardened by default — helmet, strict CORS, request ID, request timeout, xss + mongo-sanitize, graceful shutdown, /health + /ready, error envelope
Plugin System — JWT, Clerk, Stripe, S3, ratelimit via backgen add
Resource Generator — CRUD modules with relations, validation, Swagger
Domain Presets — saas-core, healthcare, SaaS, ecommerce, CRM, LMS — full domain in one command
Seed & Factory Generators — development data and test factories
Docker — multi-stage Dockerfile + docker-compose
Swagger/OpenAPI — auto-generated API documentation
Manifest — .backgenrc.json tracks ORM, plugins, versions, and ownership for upgrade/rollback

---

Quick Start

# Install globally
npm install -g @ibrahimkhaled19/backgen

# Create a project (pick your ORM)
backgen init my-api --orm prisma
backgen init my-api --orm drizzle
backgen init my-api --orm mongoose

# Create a full multi-tenant domain
backgen init my-saas --preset saas-core --defaults

# Add authentication
backgen add jwt
backgen add clerk

# Add production hardening
backgen add ratelimit

# Generate a resource
backgen generate resource Product name:string price:number stock:number

# Start developing
cd my-api
npm run dev

---

Commands

`backgen init [name]`

Generate a new backend project.

backgen init my-api                              # interactive ORM picker
backgen init my-api --orm prisma                 # explicit ORM
backgen init my-api --orm drizzle --defaults     # Drizzle, non-interactive
backgen init my-api --orm mongoose --skip-install
backgen init my-api --preset saas-core --defaults   # full multi-tenant domain
backgen init my-api --preset healthcare            # healthcare domain

Output:

Express app with TypeScript strict mode
ORM-specific data layer (Prisma / Drizzle / Mongoose)
Environment validation (Zod)
Swagger/OpenAPI documentation
Docker + docker-compose
Hardened by default: helmet, CORS, request ID, timeout, xss + mongo-sanitize, graceful shutdown, health checks
ESLint 9 + Vitest
.backgenrc.json manifest (records project.orm + plugins)

No auth by default — choose your auth provider with backgen add.

---

`backgen add [plugin]`

Install a plugin. Interactive multi-select if no argument.

backgen add                 # interactive multi-select
backgen add jwt             # JWT authentication
backgen add clerk           # Clerk auth-as-a-service
backgen add stripe          # Stripe payments
backgen add s3              # AWS S3 storage
backgen add ratelimit       # Per-IP / per-user rate limiting
backgen add devops          # Install all devops plugins at once

Available Plugins:

| Plugin | Category | Description | |--------|----------|-------------| | jwt | auth | JWT authentication with refresh tokens | | clerk | auth | Clerk auth-as-a-service (conflicts with jwt) | | stripe | payment | Stripe checkout, webhooks, customers | | s3 | storage | AWS S3 upload, download, presigned URLs | | ratelimit | production | Per-IP rate limiting with Redis-ready store | | ci-github | devops | GitHub Actions CI pipeline (lint, typecheck, test, build, optional deploy) | | dependabot | devops | Automated dependency updates via Dependabot | | codeql | devops | CodeQL security analysis on push and schedule | | docker-registry | devops | Docker image build and publish to GHCR | | release | devops | Semantic release with npm publish and GitHub releases |

Conflict detection: jwt and clerk cannot be installed together.

---

Domain Presets

Generate a complete domain in one command. Each preset creates multiple resources with relations, auto-installs JWT auth, and wires everything together.

backgen init my-api --preset healthcare
backgen init my-api --preset saas --defaults

healthcare

Patient, Doctor, Appointment, Prescription, MedicalRecord — appointments between patients and doctors, prescriptions linked to patients, medical records per patient.

saas

Organization, Team, Membership, Subscription, Invoice — organizations with teams and memberships, subscriptions with invoices.

ecommerce

Category, Product, Cart, Order, OrderItem, Payment — products in categories, carts with items, orders with line items and payments.

crm

Contact, Company, Deal, Activity — companies with contacts, deals tracked through pipeline, activity logging.

lms

Course, Lesson, Enrollment, Progress, Certificate — courses with lessons, student enrollments, progress tracking, certificates.

---

`backgen remove [plugin]`

Remove a plugin. Interactive multi-select if no argument. Supports devops shorthand to remove all devops plugins.

backgen remove              # interactive multi-select
backgen remove stripe       # remove specific plugin
backgen remove devops       # remove all devops plugins

---

`backgen generate resource <name> [fields...]`

Generate a CRUD resource module.

# Interactive
backgen generate resource Product

# Non-interactive
backgen generate resource Product name:string price:number stock:number

# With relations
backgen generate resource Appointment date:datetime status:string \
  --relations "doctor:Doctor,patient:Patient"

# With --fields flag
backgen generate resource Product --fields "name:string,price:number"

Generated files: `` src/modules/product/ product.controller.ts # CRUD endpoints product.service.ts # business logic product.repository.ts # database operations product.validation.ts # Zod schemas product.types.ts # TypeScript interfaces product.routes.ts # route definitions + Swagger product.test.ts # test placeholder ``

Field types: string, number, boolean, date, datetime

Relations: doctor:Doctor (belongsTo), patients:Patient (hasMany)

---

`backgen generate seed <resource>`

Generate seed data for development.

backgen generate seed Product --count 10

Output: prisma/seeds/product.ts (Prisma), db/seeds/product.ts (Drizzle), or seeds/product.ts (Mongoose)

---

`backgen generate factory <resource>`

Generate a test factory.

backgen generate factory Product

Output: src/factories/product.factory.ts

Usage: ``ts import { createProduct } from "./factories/product.factory.js"; const product = await createProduct({ name: "Widget" }); ``

---

`backgen generate migration [name]`

Generate a database migration (ORM-aware).

backgen generate migration add-product-table   # runs prisma migrate dev / drizzle-kit generate / no-op for Mongoose

---

`backgen sync`

Reconcile .backgenrc.json with the project. Regenerates missing plugin files.

backgen sync

---

`backgen health`

Show system health information.

backgen health

Displays:

Node.js version
Platform and architecture
BackGen version

---

`backgen doctor`

Check project health with ownership integrity diagnostics.

backgen doctor              # health check + ownership audit
backgen doctor --fix        # auto-fix missing manifest entries

Checks:

Node.js version (>= 18)
npm availability
.env file
DATABASE_URL
Prisma schema / Drizzle config / Mongoose connection
Dependencies
Package manager version
File integrity — all manifest-tracked files exist on disk
Ownership integrity — framework vs user file classification

---

`backgen upgrade`

Upgrade a generated project to the latest template version. Creates a backup, then applies pending migrations sequentially.

backgen upgrade              # show pending migrations, prompt before applying
backgen upgrade --yes        # skip confirmation, apply all pending

What happens:

Reads current generatedVersion from .backgenrc.json
Loads pending core + plugin migrations
Creates backup in .backgen/backups/pre-<version>/
Applies migrations in order (semver-sorted)
Updates ownership register + generatedVersion in manifest

---

`backgen rollback`

Restore a project to its pre-upgrade state from the most recent backup.

backgen rollback              # show latest backup, prompt before restoring
backgen rollback --yes        # skip confirmation

What happens:

Lists available backups in .backgen/backups/
Restores the most recent backup (all tracked files + manifest)
Project returns to exact pre-upgrade state

---

Plugin System

Every plugin implements the BackGenPlugin interface:

interface BackGenPlugin {
  name: string;
  category: string;
  description: string;
  version: string;

  dependencies?: string[];
  devDependencies?: string[];
  requires?: string[];
  conflicts?: string[];

  env?: Record<string, string>;
  templates: string[];
  migrations?: PluginMigration[];   // versioned plugin migration scripts

  install(ctx: InstallContext): Promise<void>;
  uninstall?(ctx: InstallContext): Promise<void>;
}

Plugins can:

Install npm dependencies
Inject environment variables
Register routes in app.ts
Replace existing middleware
Add database models (Prisma / Drizzle / Mongoose)
Carry versioned migrations for own upgrades

---

Project Manifest

.backgenrc.json tracks plugins, versions, generated version, and file ownership:

{
  "version": "1.0.0",
  "generatedVersion": "1.9.0",
  "project": {
    "name": "my-api",
    "framework": "express",
    "database": "postgresql",
    "orm": "prisma",
    "preset": "saas-core"
  },
  "plugins": {
    "jwt": {
      "version": "1.0.0",
      "installedAt": "2026-06-01",
      "source": "core"
    }
  },
  "files": {
    "src/app.ts": { "owner": "shared", "version": "1.9.0" },
    "src/server.ts": { "owner": "framework", "version": "1.9.0" },
    "src/config/env.ts": { "owner": "framework-editable", "version": "1.9.0" },
    "prisma/schema.prisma": { "owner": "user" },
    "src/modules/user/user.service.ts": { "owner": "user" },
    "docker-compose.yml": { "owner": "shared", "version": "1.9.0" }
  }
}

Ownership levels: | Level | Description | Upgrade behavior | |-------|-------------|-----------------| | framework | BackGen owns fully | Safe to overwrite | | framework-editable | Generated but user may customize | Smart merge via migration | | shared | Generated skeleton, user extends (e.g. docker-compose) | Migration-aware update | | user | User owns entirely | Never touched |

---

Generated Project Structure

my-api/
├── prisma/                       # Prisma ORM only
│   ├── schema.prisma
│   └── seeds/
├── src/db/                       # Drizzle ORM only
│   ├── schema/
│   │   └── index.ts
│   └── seeds/
├── src/models/                   # Mongoose ORM only
│   └── seeds/
├── src/
│   ├── app.ts                    # Express app setup
│   ├── server.ts                 # Server entry point
│   ├── config/
│   │   ├── env.ts                # Zod env validation
│   │   ├── database.ts           # Prisma client / Drizzle db / Mongoose connection
│   │   └── swagger.ts            # Swagger config
│   ├── middleware/
│   │   ├── auth.ts               # JWT/Clerk auth
│   │   ├── validate.ts           # Zod validation
│   │   ├── error.ts              # Global error handler
│   │   └── logger.ts             # Request logging
│   ├── modules/
│   │   ├── auth/                 # Auth module (if jwt installed)
│   │   ├── stripe/               # Stripe module (if installed)
│   │   └── <resource>/           # Generated resources
│   ├── services/
│   │   └── logger.service.ts     # Winston logger
│   ├── utils/
│   │   ├── api-error.ts          # Error class
│   │   ├── async-handler.ts      # Async wrapper
│   │   └── response.ts           # Response formatters
│   └── factories/                # Test factories
├── .env.example
├── .backgenrc.json               # Manifest
├── Dockerfile
├── docker-compose.yml
├── package.json
└── tsconfig.json

---

Development

# Clone
git clone https://github.com/your-username/backgen.git
cd backgen

# Install
npm install

# Build
npm run build

# Test
npm run test

# Lint
npm run lint

Test Suite

277+ tests covering:

CLI help and version
Init: project structure, configs, manifest (all 3 ORMs)
Init with domain presets: preset-specific resources and relations
Init with saas-core preset: multi-tenant organizations, memberships, RBAC
Add plugin: files, routes, env vars, manifest (V4.6 plugin suite)
Generate resource: module files, ORM model, routes, validation
Generate with relations: foreign keys, ORM includes
Seed and factory generators (all 3 ORMs)
Drizzle: schema generation, client setup, codegen
Mongoose: model generation, schema definition, connection
Remove plugin: file + dependency + manifest cleanup
Sync: file restoration
Doctor: health checks, ownership integrity
Upgrade: migration engine, pending detection, backup creation
Rollback: backup listing, file restoration, manifest recovery
Error handling: unknown plugin, non-empty directory

---

Tech Stack

| Layer | Technology | |-------|------------| | CLI | Commander.js | | Prompts | Inquirer.js | | Templates | Handlebars | | Spinner | Ora | | Colors | Chalk | | Testing | Vitest | | Linting | ESLint 9 (flat config) | | Language | TypeScript (strict) |

Generated Projects

| Layer | Technology | |-------|------------| | Framework | Express.js | | Language | TypeScript (strict) | | Database | PostgreSQL | | ORM | Prisma / Drizzle / Mongoose | | Validation | Zod | | Auth | JWT or Clerk | | Payments | Stripe | | Storage | AWS S3 | | Docs | Swagger/OpenAPI | | Logging | Winston + Morgan | | Testing | Vitest | | Deployment | Docker |

---

BackGen vs Alternatives

| Tool | ORM Choice | Auth | Plugin System | Presets | Upgrade Engine | Docs Site | |------|-----------|------|---------------|---------|----------------|-----------| | BackGen | Prisma, Drizzle, Mongoose | JWT, Clerk | ◈ 7+ plugins | 5 domains | ◈ Backup + rollback | — | | NestJS CLI | No (fixed NestJS) | Built-in | ◈ Modules | — | — | ◈ | | Express Generator | No (fixed plain JS) | — | — | — | — | — | | T3 Stack | Prisma | NextAuth | — | — | — | ◈ | | AdonisJS | Lucid ORM | Built-in | ◈ Ace | — | — | ◈ | | LoopBack | Built-in | Built-in | ◈ | — | — | ◈ |

Key differentiators:

◈ ORM-switchable — change Prisma ↔ Drizzle ↔ Mongoose via manifest, not rewrite
◈ Domain presets — healthcare, SaaS, ecommerce, CRM, LMS in one command
◈ Upgrade engine — versioned migrations + backup + rollback for generated projects
◈ Multi-ORM from day one — not locked into one data layer

---

Roadmap

| Version | Focus | Status | |---------|-------|--------| | V1 | Foundation | Done | | V2 | Plugin System | Done | | V3 | Resource Generator | Done | | V4 | Domain Presets | Done | | V4.5 | SaaS Essentials | Done | | V4.6 | Production Hardening | Done | | V4.6.1 | Base Hardening Default-On | Done | | V5 | Multi-ORM (Prisma, Drizzle, Mongoose) | Done | | V6 | DevOps & Infrastructure | Done | | V6.1 | Ownership Tracking & Doctor --fix | Done | | V6.2 | Upgrade Engine & Migration Runner | Done | | V6.3 | Backups & Rollback | Done | | V6.4 | Plugin Migrations | Done | | V7 | Upgrade Polish & Diffing | In Progress | | V8 | Schema-First Development | Planned | | V9 | Enterprise Features | Planned | | V10 | Plugin Authoring SDK | Planned | | V11 | Marketplace | Planned | | V12 | AI Context Layer | Planned |

See docs/ROADMAP.md for details.

---

License

MIT

backgen-mcp