# Ingest Directory Structure

## Layout

```
<app>/backend/ingest/
├── config.yaml
├── mutations/
│   ├── createCustomer.graphql
│   └── createSalesOrder.graphql
└── scenarios/
    ├── baseline/
    │   ├── customer/
    │   │   ├── entity.json
    │   │   └── data.jsonl
    │   └── product/
    │       ├── entity.json
    │       └── data.jsonl
    └── <scenario-name>/
        └── sales-order/
            ├── entity.json
            └── data.jsonl
```

## Rules

- `config.yaml` and `mutations/` live at `ingest/` root — shared by all scenarios
- Each scenario contains entity subdirectories, each with `entity.json` and `data.jsonl`
- Entity directory names are freeform — the `name` field in `entity.json` is what matters
- Scenario names are kebab-case
- `entity.json` must include a `name` field matching the entity name used in `entityDependencies`

## Execution

```bash
# Run all entities in a scenario
npx gql-ingest ./ingest/scenarios/baseline/*/entity.json \
  -e $ENDPOINT -c ./ingest/config.yaml -h '{"Authorization": "Bearer $TOKEN"}'

# Run baseline + a flow scenario together (required for cross-scenario $ref)
npx gql-ingest \
  ./ingest/scenarios/baseline/*/entity.json \
  ./ingest/scenarios/<flow>/*/entity.json \
  -e $ENDPOINT -c ./ingest/config.yaml \
  -h '{"Authorization": "Bearer $TOKEN"}' \
  -n Entity1,Entity2,...
```

Note: when combining scenarios that share entity names (e.g., both have PurchaseOrder), use `-n` to list the specific entities to process in dependency order.

## config.yaml Format

```yaml
retry:
  maxAttempts: 3
  baseDelay: 1000
  exponentialBackoff: true

parallelProcessing:
  concurrency: 5
  entityConcurrency: 2
  preserveRowOrder: false

entityDependencies:
  # Derived from resolver input types — entity with foreign key depends on referenced entity
  Product: []
  Customer: []
  SalesOrder: [Customer, Product]
  SalesOrderLine: [SalesOrder, Product]
```

### entityDependencies

Build from resolver analysis:

1. For each entity's mutation input type, find fields ending in `Id` (e.g., `customerId`)
2. Strip the `Id` suffix to get the dependency entity name (e.g., `Customer`)
3. Entities with no foreign key fields have empty dependency arrays