Vertical Seeding Infrastructure

The vertical seeding system creates realistic, production-representative test data across all 11 Ngwenya Verticals with strict multi-tenant isolation. Each Malet is owned by a specific user or Organization, and every seeded entity is scoped to exactly one Malet.

Architecture

Two-Plane Approach

The seed system mirrors the platform's own architectural split:

This split is necessary because the experiences subgraph exposes read-only queries for most entities. The seed scripts bypass the resolver layer to populate data that would normally be created by internal admin or backend workflows.

Shared Utilities

All 11 vertical scripts import from a common shared/ directory to eliminate duplication:

scripts/db/verticals/
├── shared/
│   ├── config.ts          # GATEWAY_URL, MONGODB_URI, POSTGRES_URI, TOKEN
│   ├── gql-client.ts      # GraphQL client with user impersonation
│   ├── mongo.ts           # Lazy Mongoose connection factory
│   ├── ids.ts             # oid(), daysAgo(), daysFromNow(), img()
│   └── users.ts           # 22 users, 2 orgs, 11 malet definitions
├── seed-full.ts           # Master orchestrator (all phases)
├── seed-all.ts            # Verticals-only orchestrator (3 phases)
├── seed-users.ts          # Auth users (Postgres)
├── seed-profiles.ts       # User profiles (MongoDB)
├── seed-social.ts         # Follows, wishlists, likes
├── seed-commerce.ts       # Orders, carts, reviews
├── seed-community.ts      # Discussions, comments, posts
├── seed-enterprise.ts     # SAML, SCIM, roles, SIEM
├── clean.ts               # Drops all seed collections
└── seed-{vertical}.ts     # One per vertical (11 total)

Key Design: `ensureMalet()`

The shared gql-client.ts exposes an ensureMalet() function that handles idempotent Malet creation:

const { id, handle } = await ensureMalet({
  handle: 'fashion-demo',
  name: "Amara's Boutique",
  tagline: 'Curated African fashion',
  description: '...',
  verticalType: 'fashion',
  ownerType: 'USER',
  ownerId: USER_SOLO_FASHION.id,
  sectionTags: ['luxury', 'handmade'],
}, USER_SOLO_FASHION.id);

Internally, ensureMalet():

1. Queries by handle — if found, returns existing Malet (idempotent)
2. Creates via createOneMalet mutation — only passes GQL-valid fields
3. Patches ownerType/ownerId directly via MongoDB (not on MaletInput DTO)

User Simulation

The seed system simulates real-world multi-tenancy with 22 deterministic users, 2 Organizations, and both solo and team-based ownership patterns. See Seed Infrastructure for the full 22-archetype matrix.

Solo Malet Owners (Starter Tier)

Individual Malet Owners who own exactly one Malet:

Organization-Owned Malets

Two Organizations with team structures and role-based access:

AfriArts Collective — A creative agency operating 4 Malets:

Teams: "Events & Culture" (Thabo, Zanele), "Food & Tours" (Naledi, Sipho, Bongani)

Circuit Board Inc. — Enterprise-tier consumer electronics with SAML/SCIM:

Vertical Breakdown

Malet Registry

Seeded Entities Per Vertical

Execution

Full Seed

# Seed all 11 verticals (3 phases, ~1 second)
make seed-verticals

# Full platform seed (all 22 archetypes, ~5 seconds)
make seed-full

# Or run the orchestrator directly
npx ts-node scripts/db/verticals/seed-all.ts

The orchestrator runs in dependency order:

Phase 1: Organizations  → AfriArts Collective, Circuit Board Inc.
Phase 2: Solo Malets    → fashion, author, photographer, wellness, professional
Phase 3: Org Malets     → entertainment, culture, tour, restaurant, tech, arcade

Individual Verticals

make seed-fashion           # Amara's Boutique
make seed-entertainment     # The Grand Venue
make seed-wellness          # Serenity Wellness Spa
make seed-orgs              # Organizations only
# ... etc (one target per vertical)

Clean Slate

# Drop 38 seed-related MongoDB collections
make seed-clean

# Or via the standalone script (no container CLI needed)
npx ts-node scripts/db/verticals/clean.ts

# Wipe + re-seed
make seed-clean && make seed-verticals

Environment Variables

Frontend Catalog Integration

The catalog page ([malet]/catalog/+page.ts) uses a parallel fetch + graceful fallback strategy to display vertical-specific entities alongside core Products, Services, and Articles.

Data Loading Pattern

// Core data — always fetched
const [products, services, blogs] = await Promise.all([
  client.request(GET_MALET_PRODUCTS, { maletId }),
  client.request(GET_MALET_SERVICES, { maletId }),
  client.request(GET_MALET_BLOGS, { maletId }),
]);

// Vertical-specific — wrapped in safeFetch()
const [events, exhibitions, plans] = await Promise.all([
  safeFetch(client.request(GET_UPCOMING_EVENTS, { maletId }), { upcomingEvents: [] }),
  safeFetch(client.request(GET_ACTIVE_EXHIBITIONS, { maletId }), { activeExhibitions: [] }),
  safeFetch(client.request(GET_MEMBERSHIP_PLANS, { maletId }), { membershipPlans: [] }),
]);

`safeFetch()` Pattern

The safeFetch() wrapper ensures the catalog page never crashes when a subgraph query doesn't match the current Malet's vertical. For example, a Fashion Malet has no Events — the upcomingEvents query returns [] via graceful fallback rather than throwing.

async function safeFetch<T>(promise: Promise<T>, fallback: T): Promise<T> {
  try { return await promise; } catch { return fallback; }
}

Dynamic Sections

The catalog template conditionally renders sections based on what data is available:

Idempotency

All scripts are safe to re-run:

• Malet creation: ensureMalet() checks for existing handle first
• Product creation: ensureProduct() checks for existing slug+maletId before creating (idempotent)
• MongoDB inserts: wrapped in try/catch that skips E11000 duplicate key errors
• Deterministic IDs: User UUIDs are hardcoded in shared/users.ts
• Meilisearch reindex: seed-full.ts Phase 10 automatically reindexes (non-fatal if Meilisearch is unavailable)

For a completely clean state, run make seed-clean before seeding.

Common Pitfalls

Related

• Seed Infrastructure — Full 22-archetype platform seeding, social graph, commerce, enterprise
• Entertainment & Experiences — Event ticketing, credit wallets, and loyalty systems
• Fashion Vertical — Size charts, variant grids, and lookbooks
• Wellness & Beauty — Membership plans, wellness profiles, and subscriptions
• Local Development Environment — Service startup and legacy seed commands
• Teams & Sub-Groups — Organization structure and role-based access