🚀 Production Backend Kit

A comprehensive knowledge base + CLI + adapters for AI-powered backend development

⚡ 60s Quickstart • 🔧 CLI Reference • 🔌 Adapters • 📋 Patterns • 🤝 Contributing

⚡ 60 Seconds Quickstart

# 1. Install
npm install -g production-backend-kit

# 2. Check your environment
bek doctor

# 3. Initialize your project with a preset
bek init --preset node-express

That's it! You now have production-grade patterns and checklists in your project.

📦 Installation

Prerequisites

• Node.js 18 or higher
• npm, yarn, or pnpm

Installation

Option 1: Install from npm (recommended)

npm install -g production-backend-kit

# Verify installation
bek --version

# Check environment
bek doctor

Option 2: Install from GitHub Release

# Download and install the latest release
npm install -g https://github.com/ThanhNguyxn/backend-engineering-kit/releases/latest/download/production-backend-kit.tgz

Option 3: Install from source (for development)

git clone https://github.com/ThanhNguyxn/backend-engineering-kit.git
cd backend-engineering-kit/cli
npm install && npm run build
npm link

Expected output from bek doctor:

🩺 Environment Check

  ✔ Operating System: win32 10.0.22631 (x64)
  ✔ Node.js: v20.10.0 (>= 18 required)
  ✔ Package Manager: [email protected]
  ✔ Git: 2.43.0
  ✔ Disk Access: Writable
  ⚠ Config File: Not found (using defaults)
  ✔ Project: package.json found

⚠ Some checks have warnings. Consider addressing them.

Quick Start in Your Project

# Navigate to your project
cd your-project

# Initialize with standard template
bek init --template standard -y

# Search for patterns
bek search "error handling"

# Run quality gate
bek gate --checklist checklist-api-review

🔧 CLI Reference

Global Options

All commands support these global options:

| Option | Description | |--------|-------------| | --debug | Show debug output and full stack traces | | --silent | Suppress all output except errors | | --verbose | Show detailed verbose output | | --json | Output machine-readable JSON (where supported) |

Commands

bek doctor

Check your environment and dependencies.

bek doctor           # Human-readable output
bek doctor --json    # JSON output for CI/CD

Exit codes:

• 0 - All checks passed
• 1 - Some warnings
• 2 - Critical errors

bek init

Initialize a new Backend Kit project.

# Interactive mode
bek init

# Non-interactive with template
bek init --template standard -y

# Use a preset (copies real patterns/checklists from source)
bek init --preset node-express
bek init --preset node-fastify
bek init --preset node-minimal

# Dry run (preview without creating files)
bek init --preset node-express --dry-run

# Initialize with specific AI adapter
bek init --ai claude --target ./my-project

Options: | Option | Description | |--------|-------------| | -t, --template <name> | Template: minimal, standard, advanced | | -p, --preset <name> | Preset: node-express, node-fastify, node-minimal | | --target <path> | Target directory (default: current) | | --out <path> | Alias for --target | | --ai <tools> | AI adapters: claude,cursor,copilot,codex,all | | --force | Overwrite existing files | | --dry-run | Preview changes without creating files | | -y, --yes | Skip prompts, use defaults |

Templates vs Presets:

• Templates create sample files for you to customize
• Presets copy real patterns and checklists from the kit's knowledge base

Presets: | Preset | Patterns | Checklists | |--------|----------|------------| | node-express | error-model, validation, logging, correlation-id, rate-limiting | api-review, prod-readiness | | node-fastify | error-model, validation, logging, timeouts, rate-limiting | api-review, reliability-review | | node-minimal | error-model, logging | api-review |

Output structure (preset):

.backend-kit/
├── patterns/
│   ├── api.error-model.md
│   ├── api.request-validation.md
│   └── ...
├── checklists/
│   ├── checklist.api-review.md
│   └── checklist.prod-readiness.md
└── bek.config.json

bek lint

Lint content files for issues.

bek lint             # Human-readable output
bek lint --json      # JSON output for CI/CD

Example output:

🔍 Linting content...

ℹ Checked 30 files

.shared/production-backend-kit/patterns/api.error-model.md
  ⚠ Missing recommended field: scope [frontmatter-recommended]
  ⚠ Missing recommended field: maturity [frontmatter-recommended]

Found 0 errors and 90 warnings

bek search <query>

Search patterns and checklists.

# Basic search
bek search "pagination"

# With filters
bek search "authentication" --scope security
bek search "database" --level intermediate
bek search "error" --limit 5

Options: | Option | Description | |--------|-------------| | -t, --tag <tag> | Filter by tag | | -s, --stack <stack> | Filter by stack (postgresql, nodejs, etc.) | | -l, --level <level> | Filter by level: beginner, intermediate, advanced | | --scope <scope> | Filter by scope: api, database, security, reliability, observability | | -n, --limit <n> | Limit results (default: 10) |

bek list

List all available patterns and checklists.

bek list                    # List all
bek list --scope security   # Filter by scope
bek list --tag api          # Filter by tag

bek show <id>

Show details of a specific pattern or checklist.

bek show api-error-model
bek show checklist-api-review --json

bek gate

Run quality gate checklist.

bek gate --checklist checklist-api-review
bek gate --checklist checklist-prod-readiness --json

bek validate

Validate content and rebuild database.

bek validate           # Validate and rebuild
bek validate --fix     # Auto-fix issues first
bek validate --json    # JSON output

bek build-db

Build/rebuild the search database.

bek build-db

bek sync

Update BEK kit files in an existing project. Useful when the CLI is upgraded and you want the latest patterns/checklists.

# Interactive sync with backup
bek sync

# Preview changes without applying
bek sync --dry-run

# Force sync without confirmation
bek sync --force

# JSON output for CI/CD
bek sync --json

# Skip backup
bek sync --no-backup

Options: | Option | Description | |--------|-------------| | --target <path> | Target directory (default: current) | | --dry-run | Preview changes without applying | | --force | Apply changes without confirmation | | --backup | Create backup before syncing (default: true) | | --no-backup | Skip backup | | --json | Output as JSON |

Aliases: bek update

bek remove

Remove BEK kit files from a project. Performs a clean uninstall based on the manifest.

# Interactive removal
bek remove

# Preview what would be removed
bek remove --dry-run

# Skip confirmation prompt
bek remove -y

# JSON output
bek remove --json

Options: | Option | Description | |--------|-------------| | --target <path> | Target directory (default: current) | | -y, --yes | Skip confirmation prompt | | --dry-run | Preview without removing | | --json | Output as JSON |

Aliases: bek clean, bek uninstall

What gets removed:

• .backend-kit/ directory (patterns, checklists, manifest)
• Config files (bek.config.json, .bekrc, etc.)
• AI adapters listed in manifest

🔌 Adapters

| Adapter | Location | Description | |---------|----------|-------------| | 🟣 Claude | adapters/claude/ | Full skill definition with YAML frontmatter | | 🔵 Cursor | adapters/cursor/ | Rules and commands for Cursor IDE | | ⚫ Copilot | adapters/copilot/ | Custom instructions for GitHub Copilot | | 🟢 Codex | adapters/codex/ | Skill guide for OpenAI Codex |

Manual Setup

# Claude
cp -r adapters/claude/* your-project/.claude/skills/

# Cursor
cp adapters/cursor/*.md your-project/.cursor/rules/

# Copilot
cp adapters/copilot/*.md your-project/.github/

# Codex
cp adapters/codex/*.md your-project/.codex/

Using CLI

# Initialize all adapters
bek init --ai all

# Initialize specific adapter
bek init --ai claude --target ./my-project

📋 Patterns & Checklists

Patterns (45+)

| Category | Patterns | |----------|----------| | API | Error Model, Pagination, Versioning, Webhooks, Idempotency | | Database | Indexing, Migrations, Transactions, N+1 Avoid, Schema Constraints | | Security | Auth Boundaries, Rate Limiting, Password Storage, Secrets Management | | Reliability | Timeouts, Retries, Circuit Breaker, Outbox Pattern, DLQ | | Observability | Correlation ID, Structured Logging, RED/USE Metrics |

Checklists (6)

| ID | Description | |----|-------------| | checklist-api-review | Comprehensive API review | | checklist-db-review | Database schema and query review | | checklist-security-review | Security controls audit | | checklist-reliability-review | Resilience patterns check | | checklist-prod-readiness | Pre-deployment checklist | | checklist-multitenancy-review | Multi-tenant isolation audit |

📁 Directory Structure

production-backend-kit/
├── cli/                         # CLI source (TypeScript)
│   ├── src/
│   │   ├── commands/            # doctor, init, lint
│   │   ├── lib/                 # logger, errors, config
│   │   └── __tests__/           # Unit & integration tests
│   ├── dist/                    # Compiled JavaScript
│   └── package.json
├── adapters/                    # AI tool adapters
│   ├── claude/
│   ├── cursor/
│   ├── copilot/
│   └── codex/
├── .shared/production-backend-kit/
│   ├── patterns/                # Pattern markdown files
│   ├── checklists/              # Checklist markdown files
│   └── db/                      # Generated search index
├── docs/
│   ├── architecture.md          # CLI architecture
│   └── templates.md             # Template system
├── CONTRIBUTING.md
├── CHANGELOG.md
└── SECURITY.md

🛠️ Development

# Clone repository
git clone https://github.com/ThanhNguyxn/backend-engineering-kit.git
cd backend-engineering-kit

# Install dependencies
cd cli
npm install

# Build
npm run build

# Run tests
npm test

# Development mode (watch)
npm run dev

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

📝 License

MIT License - see LICENSE for details.

Built with ❤️ by ThanhNguyxn

⭐ Star this repo if you find it helpful!