BackGen

# BackGen [](https://github.com/IbrahimKhaled19/BackGen/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@ibrahimkhaled19/backgen) [](https://opensource.org/licenses/MIT) [](https://www.npmjs.com/package/@ibrahimkhaled19/backgen) [](https://github.com/IbrahimKhaled19/BackGen) ## 🤖 AI-Ready [](https://glama.ai/mcp/servers/IbrahimKhaled19/BackGen) [](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. ```json { "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. ```bash 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 ```bash # 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. ```bash 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. ```bash 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. ```bash 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. ```bash 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. ```bash # 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. ```bash 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. ```bash 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). ```bash 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. ```bash backgen sync ``` --- ### `backgen health` Show system health information. ```bash backgen health ``` **Displays:** - Node.js version - Platform and architecture - BackGen version --- ### `backgen doctor` Check project health with ownership integrity diagnostics. ```bash 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. ```bash 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. ```bash 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: ```ts 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: ```json { "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 ```bash # 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](docs/ROADMAP.md) for details. --- ## License MIT