# Understanding Saleor Domain

> Explains Saleor e-commerce domain and Configurator business rules. Use when working with entity identification (slug vs name), YAML config structure, entity relationships, deployment pipeline stages, or synchronization logic. Do NOT use for general TypeScript questions or non-Saleor e-commerce platforms. Use when this capability is needed.

- Skill: `tomevault-io/understanding-saleor-domain` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/understanding-saleor-domain`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/understanding-saleor-domain/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/understanding-saleor-domain

---


# Saleor Domain Expert

## Overview

Deep domain knowledge about the Saleor e-commerce platform and the Configurator's business logic for entity management, configuration, deployment, and synchronization.

## When to Use

- Implementing new entity types or features
- Understanding entity identification patterns (slug vs name)
- Working with deployment pipeline stages
- Debugging configuration synchronization issues
- Understanding business rules and constraints

## Quick Reference

| CLI Command | Purpose |
|-------------|---------|
| `pnpm dev introspect` | Download remote config to local YAML |
| `pnpm dev deploy` | Apply local YAML to remote Saleor |
| `pnpm dev diff` | Compare local vs remote config |
| `pnpm dev start` | Interactive first-time setup |

## Core Concepts

A "commerce as code" CLI tool for declarative configuration management of Saleor e-commerce platforms:
- Single source of truth for store state (YAML in git)
- Version-controlled, reproducible deployments
- Declarative over imperative management

## Entity Identification System

**Critical Rule**: Every entity has exactly ONE identification strategy.

### Slug-Based Entities

Identified by `slug` field (URL-friendly identifiers):

| Entity | Example |
|--------|---------|
| Categories | `electronics` |
| Channels | `default-channel` |
| Collections | `summer-sale` |
| Menus | `main-navigation` |
| Products | `iphone-15-pro` |
| Warehouses | `us-east-warehouse` |

### Name-Based Entities

Identified by `name` field (internal configuration):

| Entity | Example |
|--------|---------|
| ProductTypes | `Physical Product` |
| PageTypes | `Blog Post` |
| TaxClasses | `Standard Rate` |
| ShippingZones | `North America` |
| Attributes | `Color` |

### Singleton Entities

Only one instance exists (no identifier needed): **Shop** (global store settings).

## Deployment Pipeline

### Stage Order (Dependencies Matter)

```
1. Validation       -> Pre-flight checks
2. Shop Settings    -> Global configuration
3. Product Types    -> Must exist before products
4. Page Types       -> Must exist before pages
5. Attributes       -> Used by product/page types
6. Categories       -> Product organization
7. Collections      -> Product groupings
8. Warehouses       -> Required for inventory
9. Shipping Zones   -> Geographic shipping rules
10. Products        -> Depends on types, categories
11. Tax Config      -> Tax rules and classes
12. Channels        -> Sales channels
13. Menus           -> Navigation (may reference products)
14. Models          -> Custom data models
```

**Key dependency**: Cannot create a Product without its ProductType existing first.

### Stage Execution Pattern

Each stage follows: Fetch remote state -> Compare local vs remote -> Plan creates/updates/deletes -> Execute with chunking -> Report results.

## Configuration Schema

Top-level keys: `shop`, `channels`, `taxClasses`, `productTypes`, `pageTypes`, `attributes`, `categories`, `collections`, `warehouses`, `shippingZones`, `products`, `menus`, `models`. See `designing-zod-schemas` skill and `src/modules/config/schema/schema.ts` for full schema details.

## Bulk Operations

Large operations are chunked (default: 50 items per chunk) to avoid timeouts. The GraphQL client handles HTTP 429 automatically with exponential backoff (max 5 retries).

## Diff & Comparison Logic

### Comparison Dimensions

For each entity type: **Existence** (does it exist remotely?), **Equality** (are fields equal?), **Children** (are nested structures equal?).

### Diff Result Types

Actions: `create`, `update`, `delete`, `unchanged`. Each entity has a dedicated comparator (e.g., `src/core/diff/comparators/category-comparator.ts`) that matches by slug or name.

## Common Patterns

### Adding a New Entity Type

1. Define Zod schema in `src/modules/config/schema/`
2. Create service in `src/modules/<entity>/`
3. Create repository with GraphQL operations
4. Add comparator in `src/core/diff/comparators/`
5. Add deployment stage in pipeline
6. Update schema documentation

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Wrong identification strategy | Check entity table: slug-based vs name-based |
| Creating entity before dependency | Follow deployment pipeline order |
| Missing chunking for bulk ops | Use `splitIntoChunks()` with default chunk size |
| Not handling rate limits | Use urql retry exchange (built-in) |

## References

For detailed information, see:
- `understanding-saleor-domain/references/entity-identification.md` - Complete entity identification rules
- `understanding-saleor-domain/references/deployment-stages.md` - Pipeline stage details
- `understanding-saleor-domain/references/schema-patterns.md` - YAML configuration patterns
- `docs/ENTITY_REFERENCE.md` - Full entity documentation
- `docs/ARCHITECTURE.md` - System architecture
- `src/modules/config/schema/schema.ts` - Zod schema definitions

## Related Skills

- **Implementing entities**: See `adding-entity-types` for complete implementation workflow
- **Config schemas**: See `designing-zod-schemas` for schema patterns
- **GraphQL operations**: See `writing-graphql-operations` for Saleor API integration

## Quick Reference Rules

For condensed quick references, see:
- `.claude/rules/entity-development.md` (automatically loaded when editing `src/modules/**/*.ts`)
- `.claude/rules/diff-engine.md` (automatically loaded when editing `src/core/diff/**/*.ts`)

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/saleor) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->