@xbg.solutions/create-backend 1.0.0 → 1.0.2

package/src/project-template/.claude/skills/bpbe/setup/skill.md

@@ -0,0 +1,301 @@
+---
+description: "Setup, configuration, and development workflow for the XBG boilerplate backend: creating projects with the CLI, .env variables, npm scripts, Firebase config, validation, and local dev server."
+---
+
+# XBG Boilerplate Backend — Setup & Configuration
+
+---
+
+## Quick Start — New Project
+
+```bash
+# Scaffold a new project with the CLI
+npx @xbg.solutions/create-backend init
+
+# The CLI will:
+#   - Ask about your project (name, Firebase project, features)
+#   - Let you select which utilities to include
+#   - Generate project structure with selected @xbg.solutions/* packages
+#   - Install dependencies
+
+# Once scaffolded:
+cd my-project/functions
+
+# Interactive setup wizard (generates .env, configures Firebase)
+npm run setup
+
+# Validate configuration + run tests
+npm run validate
+
+# Start local dev server
+npm start
+# Visit: http://localhost:5001/health
+```
+
+### What a Generated Project Looks Like
+
+```
+my-project/
+├── functions/
+│   ├── src/
+│   │   ├── index.ts              # Firebase Functions entry point
+│   │   └── generated/            # Code generator output
+│   ├── package.json              # Depends on @xbg.solutions/* packages
+│   ├── tsconfig.json
+│   └── .env
+├── __scripts__/                  # Setup, generate, deploy, validate
+├── __examples__/                 # Example data models
+├── firebase.json
+└── .firebaserc
+```
+
+### Updating an Existing Project
+
+```bash
+# Check for and apply boilerplate updates
+npx @xbg.solutions/create-backend sync
+
+# Update packages to latest versions
+cd functions && npm update
+
+# Add a new utility
+npx @xbg.solutions/create-backend add-util
+```
+
+---
+
+## Environment Variables
+
+Copy `.env.example` to `.env` in the `functions/` directory. All config is env-driven — never hardcode values.
+
+### Core Variables
+
+```bash
+# Application
+APP_NAME=my-backend-api
+APP_VERSION=1.0.0
+NODE_ENV=development         # development | staging | production
+PORT=5001
+
+# Firebase
+FIREBASE_PROJECT_ID=your-project-id
+
+# API
+API_BASE_PATH=/api/v1
+CORS_ORIGINS=http://localhost:3000,http://localhost:5173
+REQUEST_SIZE_LIMIT=10mb
+```
+
+### Feature Flags
+
+```bash
+FEATURE_AUTHENTICATION=true     # JWT auth middleware
+FEATURE_MULTI_TENANT=false      # Multi-tenant mode
+FEATURE_FILE_UPLOADS=true
+FEATURE_NOTIFICATIONS=true
+FEATURE_ANALYTICS=false
+FEATURE_REALTIME=true
+```
+
+Feature flags gate entire subsystems. Check them in code:
+
+```typescript
+import { isFeatureEnabled } from '@xbg.solutions/backend-core';
+
+if (isFeatureEnabled('notifications')) {
+  await pushNotificationsConnector.send({ ... });
+}
+```
+
+### Auth / Token Variables
+
+```bash
+JWT_ISSUER=my-backend-api
+JWT_AUDIENCE=my-backend-api
+JWT_EXPIRES_IN=1h
+JWT_REFRESH_EXPIRES_IN=7d
+TOKEN_BLACKLIST_ENABLED=true
+TOKEN_BLACKLIST_CLEANUP_INTERVAL=3600000
+TOKEN_BLACKLIST_RETENTION_DAYS=30
+```
+
+### Database
+
+```bash
+MAIN_DATABASE_ID=(default)       # Primary Firestore database ID
+ANALYTICS_DATABASE_ID=analytics  # Secondary database (optional)
+DB_RETRY_ATTEMPTS=3
+DB_RETRY_DELAY=1000
+DB_TIMEOUT=10000
+DB_ENABLE_CACHE=true
+```
+
+### PII Encryption
+
+```bash
+# Generate: openssl rand -hex 32
+PII_ENCRYPTION_KEY=your-64-hex-char-key
+```
+
+Required for the hashing utility (`@xbg.solutions/utils-hashing`). Without it, `hashValue()` will throw at runtime.
+
+### Caching
+
+```bash
+CACHE_ENABLED=false              # Global cache switch
+CACHE_DEFAULT_PROVIDER=memory    # memory | firestore | redis
+CACHE_DEFAULT_TTL=300            # seconds
+CACHE_NAMESPACE=myapp
+# Redis (optional):
+CACHE_REDIS_HOST=localhost
+CACHE_REDIS_PORT=6379
+```
+
+### Rate Limiting
+
+```bash
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_WINDOW_MS=900000      # 15 minutes
+RATE_LIMIT_MAX=100               # requests per window
+```
+
+---
+
+## Configuration in Code
+
+All config is centralized via `@xbg.solutions/backend-core`. In a generated project, configuration is driven entirely by environment variables.
+
+Reading config in your code:
+
+```typescript
+// ✅ Correct — import from @xbg.solutions/backend-core
+import { APP_CONFIG, isFeatureEnabled } from '@xbg.solutions/backend-core';
+const basePath = APP_CONFIG.api.basePath;
+const env = APP_CONFIG.app.environment;
+
+// ❌ Wrong — don't access process.env scattered through your code
+const basePath = process.env.API_BASE_PATH; // don't do this
+```
+
+---
+
+## npm Scripts
+
+Run from `functions/` in a generated project:
+
+```bash
+# Development
+npm start              # Local server (http://localhost:5001)
+npm run serve          # Firebase emulators
+npm run build          # TypeScript compile
+npm run build:watch    # Watch mode
+
+# Testing
+npm test               # All tests
+npm run test:coverage  # Coverage report
+npm run test:watch     # Watch mode
+
+# Code Quality
+npm run lint           # ESLint
+npm run lint:fix       # Auto-fix lint issues
+
+# Setup & Validation
+npm run setup          # Interactive setup wizard
+npm run validate       # Full: build + lint + tests
+npm run validate:quick # Quick: build + lint only
+
+# Code Generation
+npm run generate <model-file>   # Generate from DataModelSpecification
+# Example:
+npm run generate ../__examples__/blog-platform.model.ts
+
+# Deployment
+npm run deploy         # Deploy to Firebase
+npm run logs           # View Firebase logs
+```
+
+---
+
+## Firebase Configuration
+
+### `firebase.json` (project root)
+
+Defines functions source directory and references `firestore.rules`. Generally don't modify this.
+
+### `firestore.rules` (project root)
+
+Deny-all rules for client SDK access. This backend uses the Admin SDK (which bypasses rules). These rules act as defense-in-depth against accidental client-side database exposure.
+
+### `.firebaserc` (project root)
+
+Maps aliases to Firebase project IDs:
+
+```json
+{
+  "projects": {
+    "default": "your-firebase-project-id",
+    "staging": "your-staging-project-id",
+    "production": "your-production-project-id"
+  }
+}
+```
+
+Switch projects: `firebase use staging`
+
+### Local Development with Emulators
+
+```bash
+# Start Firestore emulator
+firebase emulators:start --only firestore
+
+# In .env, add:
+FIRESTORE_EMULATOR_HOST=localhost:8080
+```
+
+---
+
+## Validation
+
+Run `npm run validate` before deploying. It checks:
+
+- Node.js version (22+)
+- Firebase CLI installed
+- TypeScript compiles cleanly
+- All tests pass
+- `.env` has required variables
+- No placeholder values left in config
+
+Common validation failures and fixes:
+
+```bash
+# "TypeScript compilation failed"
+npm run build        # See full TS errors
+
+# "Tests failing"
+npm test             # See which tests
+
+# "PII_ENCRYPTION_KEY not set"
+openssl rand -hex 32   # Generate a key, add to .env
+```
+
+---
+
+## Anti-Examples
+
+```typescript
+// ❌ Don't hardcode env values
+export const config = {
+  apiKey: 'abc123'  // Never do this
+};
+
+// ❌ Don't scatter process.env calls
+const limit = parseInt(process.env.RATE_LIMIT_MAX);  // Use APP_CONFIG
+
+// ❌ Don't ignore feature flags
+await emailConnector.send({ ... });  // Check isFeatureEnabled('notifications') first
+
+// ✅ Correct pattern
+if (isFeatureEnabled('notifications')) {
+  await emailConnector.send({ ... });
+}
+```

package/src/project-template/.claude/skills/bpbe/skill.md

@@ -0,0 +1,153 @@
+---
+description: "Overview of the XBG boilerplate backend: architecture, philosophy, layered structure, and navigation guide to sub-skills for setup, data, services, utilities, and API."
+---
+
+# XBG Boilerplate Backend — Overview
+
+A production-ready Node.js/TypeScript backend distributed as **npm packages** (`@xbg.solutions/*`) and optimized for AI-assisted development. Built on Firebase Functions + Firestore + Express.js, designed so that AI can reliably generate, extend, and debug application code.
+
+**Repository:** `boilerplate_backend` (sister: `boilerplate_frontend` — SvelteKit 5)
+
+---
+
+## Core Philosophy
+
+This boilerplate provides **infrastructure**; you (or AI) provide **business logic**. The pattern is:
+
+1. Scaffold a new project with `npx @xbg.solutions/create-backend init`
+2. Define a declarative data model (`DataModelSpecification`)
+3. Run the generator to scaffold Controller/Service/Repository/Entity
+4. Register the controller in `functions/src/index.ts`
+5. Add business logic in the service layer
+
+The boilerplate never ships pre-built domain models (no User, Product, Order). That's intentional — AI generates those from your model spec.
+
+---
+
+## Architecture: Distributable npm Packages
+
+This boilerplate is structured as a **monorepo of publishable npm packages**, enabling update propagation to projects built on it.
+
+```
+boilerplate_backend/
+├── packages/
+│   ├── core/                    → @xbg.solutions/backend-core
+│   │   ├── src/
+│   │   │   ├── base/            #   BaseEntity, BaseRepository, BaseService, BaseController
+│   │   │   ├── middleware/      #   Auth, CORS, rate limiting, error handling, logging
+│   │   │   ├── config/          #   App, database, auth, cache, middleware config
+│   │   │   ├── types/           #   Custom error classes
+│   │   │   ├── generator/       #   Code generator engine
+│   │   │   ├── templates/       #   Handlebars templates for code generation
+│   │   │   └── app.ts           #   Express app factory
+│   │   └── package.json
+│   │
+│   ├── utils-logger/            → @xbg.solutions/utils-logger
+│   ├── utils-events/            → @xbg.solutions/utils-events
+│   ├── utils-errors/            → @xbg.solutions/utils-errors
+│   ├── utils-cache-connector/   → @xbg.solutions/utils-cache-connector
+│   ├── utils-firestore-connector/ → @xbg.solutions/utils-firestore-connector
+│   ├── utils-hashing/           → @xbg.solutions/utils-hashing
+│   ├── utils-token-handler/     → @xbg.solutions/utils-token-handler
+│   ├── utils-email-connector/   → @xbg.solutions/utils-email-connector
+│   ├── utils-sms-connector/     → @xbg.solutions/utils-sms-connector
+│   ├── ... (20+ utility packages)
+│   │
+│   └── create-backend/          → @xbg.solutions/create-backend (CLI scaffolding tool)
+│
+├── functions/                   ← Local development/testing workspace (not published)
+│   ├── src/                     #   Mirrors packages structure for local dev
+│   └── __tests__/               #   Test suite
+├── __examples__/                ← Sample DataModelSpecification files
+├── __scripts__/                 ← Project-level scripts (setup, generate, deploy, validate)
+└── package.json                 ← Monorepo root (npm workspaces)
+```
+
+### Two-Part Distribution Model
+
+1. **npm packages** (runtime dependencies) — Base classes, middleware, config, and utilities live in `node_modules/`. Updates propagate via `npm update`. Semver protects against breaking changes.
+
+2. **CLI scaffolding tool** (`@xbg.solutions/create-backend`) — Handles project structure, config files, scripts, and templates. Operates in init mode (new project) and sync mode (update existing).
+
+This is the same pattern as `firebase-tools` + `firebase init`.
+
+---
+
+## Architecture: Strict 3-Layer Stack
+
+```
+HTTP Request
+    ↓
+BaseController        ← Route handling, request/response shaping
+    ↓
+BaseService           ← Business logic, auth checks, event publishing
+    ↓
+BaseRepository        ← Firestore CRUD, soft-delete, caching
+    ↓
+Firestore
+```
+
+All generated code follows this exact pattern. Never put business logic in controllers, never put Firestore calls in services.
+
+---
+
+## Sub-Skills — When to Use Each
+
+| Skill | Use when you need to... |
+|---|---|
+| `bpbe/setup/skill.md` | Create a new project, configure .env, understand npm scripts, validate config |
+| `bpbe/data/skill.md` | Define entities, understand BaseEntity, use the generator, work with Firestore schemas |
+| `bpbe/services/skill.md` | Write service methods, handle events, implement auth/access control, lifecycle hooks |
+| `bpbe/utils/skill.md` | Use logger, PII hashing, cache, token handler, or any communication connector |
+| `bpbe/api/skill.md` | Add routes, register controllers, use middleware, understand API response shapes |
+
+---
+
+## Key Import Paths
+
+All imports come from npm packages — no relative paths to boilerplate internals.
+
+```typescript
+// Base classes (from @xbg.solutions/backend-core)
+import { BaseEntity, ValidationHelper, ValidationResult } from '@xbg.solutions/backend-core';
+import { BaseRepository, QueryOptions } from '@xbg.solutions/backend-core';
+import { BaseService, RequestContext, ServiceResult } from '@xbg.solutions/backend-core';
+import { BaseController, ApiResponse } from '@xbg.solutions/backend-core';
+
+// App factory and config
+import { createApp, APP_CONFIG, isFeatureEnabled } from '@xbg.solutions/backend-core';
+
+// Middleware
+import { createAuthMiddleware, requireRoles, requireAdmin } from '@xbg.solutions/backend-core';
+
+// Utilities (each is a separate package)
+import { logger } from '@xbg.solutions/utils-logger';
+import { eventBus, EventType } from '@xbg.solutions/utils-events';
+import { hashValue, hashFields, unhashValue } from '@xbg.solutions/utils-hashing';
+import { getCacheConnector } from '@xbg.solutions/utils-cache-connector';
+import { tokenHandler } from '@xbg.solutions/utils-token-handler';
+import { emailConnector } from '@xbg.solutions/utils-email-connector';
+```
+
+---
+
+## Tech Stack
+
+- **Runtime:** Node.js 22+, TypeScript (strict mode)
+- **Framework:** Express.js
+- **Deployment:** Firebase Functions (also runs on Cloud Run, AWS Lambda, Docker)
+- **Database:** Firestore (multi-database support)
+- **Auth:** Firebase Auth + custom JWT token handler with blacklisting
+- **Testing:** Jest, 796 passing tests
+- **Caching:** Memory / Firestore / Redis (progressive, per-repository opt-in)
+- **Events:** Internal EventEmitter-based event bus (not Pub/Sub)
+
+---
+
+## Non-Obvious Decisions
+
+- **Soft delete by default.** `BaseRepository.delete()` sets `deletedAt`; pass `hardDelete=true` for permanent. `findAll()` automatically excludes soft-deleted records.
+- **`deletedAt === null` in Firestore queries.** The repository filters by `where('deletedAt', '==', null)` — this requires a composite index if combined with other where clauses.
+- **Events are synchronous.** The event bus uses Node.js `EventEmitter`. It's fire-and-forget within the request lifecycle, not durable. For durable async, use Firebase Pub/Sub or queue systems.
+- **Generated code goes in `src/generated/`.** This directory is gitignored in production projects. Treat generated files as a starting point — copy and modify in your own directories.
+- **Config is all env-driven.** Never hardcode values in config. Feature flags via `FEATURE_*` env vars.