Developer Docs

Shared Query Package — `@ngwenya/queries`

@ngwenya/queries is a pnpm workspace package that serves as the canonical source of truth for all GraphQL queries, mutations, and TypeScript response interfaces shared across the platform's three frontend applications.

Repository: mall-dev/ngwenya-packages

IMPORTANT

All shared GraphQL operations must be defined in this package. Do not duplicate queries into individual app src/lib/queries/ directories unless they are truly app-specific (e.g., Tower-only DevOps queries).

Motivation

Before extraction, the Storefront, The Deck, and The Tower applications each maintained their own copies of shared GraphQL queries. During the Standalone Tower Dashboard and Deck extractions, query files were copied wholesale between repositories. An audit found:

  • 21 byte-identical files between ngwenya-front and ngwenya-deck
  • 9 shared files between ngwenya-front and ngwenya-tower (6 identical, 3 curated subsets)
  • Total duplicated code: ~15,000 lines across 4 domains (Malets, Murchases, Organizations, Lobby)

This duplication created a maintenance burden: any schema change required synchronized updates across all three repositories with no compile-time guarantee of consistency.

Architecture

The package lives at the pnpm workspace root alongside the three frontend repositories:

ngwenya/
├── pnpm-workspace.yaml           # Links ngwenya-packages/* and all frontends
├── ngwenya-packages/             # GitHub: mall-dev/ngwenya-packages
│   └── queries/
│       ├── package.json          # @ngwenya/queries
│       ├── tsconfig.json
│       ├── README.md
│       └── src/
│           ├── index.ts          # Barrel export (all domains)
│           ├── malet.ts          # Malets subgraph queries
│           ├── orders.ts         # Murchases subgraph queries
│           ├── organizations.ts
│           ├── lobby.ts
│           ├── auth.ts
│           ├── community.ts
│           └── ... (21 domain files)
├── ngwenya-front/                # Storefront (port 5173)
├── ngwenya-deck/                 # The Deck — Malet owner workspace (port 5171)
└── ngwenya-tower/                # The Tower — Platform admin (port 5170)

No Build Step Required

The package uses TypeScript source imports — SvelteKit's Vite bundler transpiles TypeScript directly from workspace-linked source files. There is no separate compilation or dist/ directory.

Workspace Resolution

Each consumer app declares the dependency via pnpm workspace protocol:

{
  "dependencies": {
    "@ngwenya/queries": "workspace:*"
  }
}

This resolves to the local ngwenya-packages/queries/ directory at install time.

Usage

Import from domain-specific sub-paths for clarity and tree-shaking:

import { GET_MY_OWNED_MALETS, type OwnedMaletNode } from '@ngwenya/queries/malet';
import { GET_ORDERS_BY_MALET, type Order } from '@ngwenya/queries/orders';
import { CREATE_PRODUCT } from '@ngwenya/queries/lobby';
import { GET_ORGANIZATION_TEAMS, type Team } from '@ngwenya/queries/organizations';

Barrel Import

For convenience when importing across multiple domains:

import { GET_MY_OWNED_MALETS, GET_ORDERS_BY_MALET, CREATE_PRODUCT } from '@ngwenya/queries';

Domain File Mapping

Each file in the package corresponds to a backend subgraph:

File Subgraph Key Exports
malet.ts Malets GET_MALET_BY_HANDLE, GET_MY_OWNED_MALETS, MALET_PREVIEW, UPDATE_MALET, GET_VERTICAL_CONFIG
orders.ts Murchases GET_MY_ORDERS, GET_ORDERS_BY_MALET, CHECKOUT_CART, REASSIGN_GUEST_ORDERS
organizations.ts Organizations CREATE_ORGANIZATION, GET_ORGANIZATION_TEAMS, MY_MEMBERSHIPS
lobby.ts Products / Malets (admin) CREATE_PRODUCT, CREATE_MALET, GET_PRODUCTS, GET_MALETS
auth.ts Auth Login, registration, session management
community.ts Community Posts, comments, threads, engagement
admin.ts Admin queries Platform-level admin operations
services.ts Services Service management, bookings
workroom.ts Workroom Custom order workflows

Adding a New Shared Query

  1. Identify the domain — which subgraph does the query target?
  2. Edit the correct file in ngwenya-packages/queries/src/ (e.g., malet.ts for Malets subgraph)
  3. Export the TypeScript interface alongside the query for type-safe responses
  4. Verify — the barrel index.ts uses export * wildcards, so new exports are automatically available
  5. Run pnpm run check in the consumer apps to validate

When to Put Queries in the Shared Package

Scenario Location
Query used by ≥2 frontend apps @ngwenya/queries
Query used only by Storefront ngwenya-front/src/lib/queries/
Query used only by Tower ngwenya-tower/src/lib/queries/
Query used only by Deck ngwenya-deck/src/lib/queries/

App-Specific Query Directories

After centralization, each app retains a local src/lib/queries/ directory only for truly app-specific operations:

ngwenya-front (Storefront)

25 unique files: alerts.ts, arcade.ts, cart.ts, checkout.ts, collections.ts, fashion.ts, entertainment.ts, search.ts, etc.

ngwenya-tower (Tower)

7 unique files: towerDevOps.ts, towerHealth.ts, errorTracking.ts, alerts.ts, search.ts, searchConfig.ts, sectionTags.ts

ngwenya-deck (Deck)

No app-specific query files — all queries come from @ngwenya/queries.

Private Registry Roadmap

Currently distributed via pnpm workspace links (workspace:*), which requires all repositories to be checked out locally.

Phase 1 (current): Local workspace resolution — ideal for development. Phase 2 (planned): Local private registry (e.g., Verdaccio on internal infrastructure) for CI/CD and production builds where full monorepo checkout is not practical. Configuration will be managed via .npmrc:

@ngwenya:registry=http://registry.internal.mallnline.com:4873/