@quiltr/seed

Seed data toolkit for the Quiltr platform. Bootstraps users, registers entity metadata, and populates tenant data from hand-crafted vertical JSON or Faker generators.

Quick Start

# First time — full setup (bootstrap + global metadata + tenant data)
npm run seed:all

# Re-seed tenant data only (bootstrap is idempotent, skipped if already done)
npm run seed

# Clean and re-seed with a different vertical
npm run seed -- --clean --vertical charity

Three-Phase Architecture

The seed process runs in three phases, each operating at a different auth layer:

Phase 1: Bootstrap (--bootstrap)

Creates the foundational users and tenant records on a fresh database.

1. Registers a globaladmin user (public endpoint)
2. Promotes globaladmin to admin role
3. Creates global and tenant records
4. Creates tenant users: <slug> (general), <slug>-manager, <slug>-associate

Idempotent — if globaladmin already exists with admin role, this phase is skipped entirely.

Phase 2: Global Seeds (--global-only)

Registers entity metadata and scripts using the admin token.

• Dynamic entity definitions (from data/global/dynamic-entities.json)
• Scripts (from data/global/scripts.json)

Existing metadata is updated (PATCH on 409), scripts are skipped if they already exist.

Phase 3: Tenant Seeds (default)

Seeds tenant-scoped data using the tenant user token. Data sources:

• Vertical JSON — hand-crafted datasets for 7 industry verticals
• Faker generators — dynamic data generation when no vertical is specified

Entities are seeded in dependency order:

fascias -> locations -> users -> tasks
products + customers -> baskets
products + fascias + locations -> price-entries

Configuration

Copy .env.example to .env and adjust:

SEED_API_URL=http://localhost:4000
SEED_TENANT_SLUG=tenant-123
SEED_ADMIN_USERNAME=globaladmin
SEED_ADMIN_PASSWORD=Admin123!
SEED_TENANT_PASSWORD=Flipflop123!
SEED_VERTICAL=specialty
SEED_COUNT=20
SEED_FAKER_SEED=

Priority: CLI flags > environment variables > .env file > hardcoded fallbacks.

CLI Reference

quiltr-seed [options]

Options:
  --url <url>          API base URL (default: from .env or http://localhost:4000)
  --tenant <slug>      Tenant slug (default: from .env or tenant-123)
  --vertical <name>    Use static vertical data
  --count <n>          Generate N records per entity via Faker
  --clean              Delete existing tenant data before seeding
  --all                Full run: bootstrap + global + tenant
  --bootstrap          Bootstrap only
  --global-only        Global seeds only (metadata + scripts)
  --seed <n>           Faker seed for reproducible data
  -h, --help           Show help

Available Verticals

| Vertical | Description | | -------------- | ------------------------ | | charity | Charity retail | | convenience | Convenience stores | | department | Department stores | | discount | Discount retailers | | service | Service-based businesses | | specialty | Specialty retail | | supermarket | Supermarket / grocery |

npm Scripts (from project root)

npm run seed:all      # bootstrap + global + tenant
npm run seed          # tenant data only (default vertical)
npm run seed:global   # global metadata + scripts only
npm run seed:clean    # delete all tenant data

Pass extra flags after --:

npm run seed -- --vertical charity --clean
npm run seed -- --count 50

Programmatic Usage

import { seedAll, seedTenant, bootstrap, resolveConfig } from '@quiltr/seed';

const config = resolveConfig({
  apiBaseUrl: 'http://localhost:4000',
  tenantSlug: 'my-store',
  vertical: 'specialty',
});

// Full run
await seedAll(config);

// Or individual phases
await bootstrap(config);
await seedTenant(config);

Rate Limiting

The HTTP client automatically:

• Throttles requests to stay under the API rate limit (60 req/min)
• Retries on 429 responses with exponential backoff (up to 3 retries)

No configuration needed.

Adding a New Vertical

1. Create a directory under src/data/tenant/verticals/<name>/
2. Add JSON files matching the entity names: fascias.json, locations.json, products.json, customers.json, users.json, tasks.json, baskets.json, gift-cards.json
3. Use the vertical with --vertical <name>

Each JSON file should export an array of records matching the entity schema.