Turfi Platform Documentation

Global Rules

• CSV imports must map into documented entity contracts only.
• Raw database UUID columns are allowed only when the contract explicitly lists direct *_id support.
• Human-readable relationship input must never be written directly to FK columns without resolution.

Column Naming Conventions

• *_key: resolve against the target table key column first.
• Non-suffixed relationship fields such as organization, league, season, club, team, or venue: resolve by key, then slug, then name.
• Shared address fields use normalized address inputs such as address_line1, city, province, postal_code, and country rather than expecting a direct address_id from operators.
• Lookup-backed fields should prefer canonical keys when supplied by CSV.

Resolution Order

1. Direct id, if the contract allows it and the CSV maps to an *_id field.
2. *_key lookup against the target table key column.
3. Non-suffixed relationship field resolved by key.
4. Fallback to slug.
5. Fallback to name.

Validation Flow

1. Column mapping must resolve to documented accepted columns only.
2. Required fields are checked before row writes.
3. Relationship and lookup values are normalized or paused for review before DB validation.
4. Fail-fast relationships reject the row instead of silently persisting null foreign keys.
5. Database constraints remain authoritative after import-layer normalization completes.