# Scenario Scaffolding

## Baseline Scenario

The baseline scenario is always created first. It provides the minimum data set for the app to function.

### What to include

For each entity with a create resolver:
1. Create 1-3 records — enough for referential integrity and basic queries
2. Use realistic but generic data (e.g., "Acme Corp", "Widget A")
3. Ensure all required fields are populated
4. Add `outputCapture` to capture server-generated IDs for any entity referenced by others
5. Use `$ref` in downstream entities to reference captured IDs — never hardcode UUIDs

### Data file format (JSONL)

File: `ingest/scenarios/baseline/<entity-name>/data.jsonl`

Each line is a complete JSON object. **Do not include an `id` field** — the server generates IDs. Use human-readable reference fields (e.g., `companyRef`, `supplierRef`) for `$ref` lookup.

```jsonl
{"legalName":"Acme Corp","baseCurrencyId":"bde27b46-...","street":"100 Main St","city":"New York","postalCode":"10001","country":"US"}
```

Downstream entity referencing the above:
```jsonl
{"name":"Global Supplies","type":"ORGANIZATION","companyRef":"Acme Corp","role":"SUPPLIER"}
```

### Rules for baseline data

- Field names must match the GraphQL input type field names (check introspection)
- **Do not include `id` fields** — server generates them; use `outputCapture` to capture them
- Use `$ref` for all cross-entity references (see [mapping config](mapping-config.md))
- Values should be realistic and self-explanatory
- Seed entity IDs (Currency, Unit, etc.) are stable and can be hardcoded — they come from `seed/data/`

## Business Flow Scenarios

For each business flow doc:
1. Read the flow steps
2. Identify which mutations each step calls
3. Generate data that walks through the flow
4. **Use `$ref` to reference baseline entities** — run baseline + flow together in one invocation
5. For nested arrays (e.g., PO lines), use data-level `$ref` for IDs inside the array

### Example: Purchase Order Lifecycle

If the business flow describes: "Create PO for supplier, receive goods, create invoice":

```
scenarios/purchase-order-lifecycle/
├── purchase-order/
│   ├── entity.json    # outputCapture on externalRef, $ref for companyId/supplierId
│   └── data.jsonl     # lines contain data-level $ref for itemId
├── goods-receipt/
│   ├── entity.json    # $ref for companyId/supplierId
│   └── data.jsonl     # lines contain data-level $ref for itemId
└── purchase-invoice/
    ├── entity.json    # $ref for companyId/supplierId
    └── data.jsonl
```

Run together with baseline:
```bash
npx gql-ingest \
  ./ingest/scenarios/baseline/*/entity.json \
  ./ingest/scenarios/purchase-order-lifecycle/*/entity.json \
  -e $ENDPOINT -c ./ingest/config.yaml \
  -h '{"Authorization": "Bearer $TOKEN"}' \
  -n Company,Item,Role,BusinessPartner,Site,User,PurchaseOrder,GoodsReceipt,PurchaseInvoice
```

## Data Generation Tips

- Check the introspected schema for required vs optional fields
- Use enum values from the schema for enum fields
- For date fields, use `yyyy-MM-dd` format: `"2025-01-15"` (not ISO datetime)
- For decimal/float fields, use strings for precision: `"19.99"` (GraphQL Float variables)
- For boolean fields, use `true`/`false` not strings
- Seed UUIDs (Currency, Unit, UoMCategory) are stable across resets — safe to hardcode
- All other entity IDs must use `outputCapture` + `$ref`