Turfi Platform Documentation
Official Turfi documentation portal for users, admins, and developers.
Documentation Search
Search only within Turfi documentation pages.
C
Players
Player registry contract.
Entity: Players
1. Overview
- Player identity registry for athlete naming, gender metadata, lifecycle status, and downstream registration/media attribution.
- Uses gender lookup metadata.
- Participates in clubs and teams through registrations rather than a single direct FK.
- Feeds media, stats, and claim systems downstream.
- Visible at
/admin/data/registries/players.
2. Database Schema
Columns
| column | type | nullable | default | notes | |
|---|---|---|---|---|---|
| birth_year | number \ | null | yes | null | Base table field. |
| club_text | string \ | null | yes | null | Base table field. |
| created_at | string | no | database default or generated | Base table field. | |
| first_name | string | no | none | Base table field. | |
| gender_id | string \ | null | yes | null | Relationship-bearing column. |
| id | string | no | generated UUID default | Base table field. | |
| key | string | no | none | Base table field. | |
| last_name | string | no | none | Base table field. | |
| normalized_name | string \ | null | yes | null | Base table field. |
| slug | string \ | null | yes | null | Base table field. |
| status | string | no | database default or generated | Lifecycle field when present. | |
| updated_at | string | no | database default or generated | Base table field. |
Foreign Keys
| column | references | table | on delete |
|---|---|---|---|
| gender_id | id | genders | NO ACTION |
Indexes
No migration-defined indexes were discovered in the checked-in SQL history for this table.
Constraints
- Unique: none discovered in checked-in migrations.
- Check: none discovered in checked-in migrations.
Triggers
No migration-defined triggers were discovered in the checked-in SQL history for this table.
Views (if any)
| name | purpose |
|---|---|
| v_players | Curated admin registry read model for players. |
3. Import Contract
Accepted Columns
keyfirst_namelast_namebirth_yeargender_keygendergender_idclub_textslug
Resolution Rules
- Player base imports are primarily direct-field imports; club affinity is captured as text in the player base template.
- Gender supports key-first lookup resolution with label fallback through mismatch handling.
Required Fields
first_namelast_name
Optional Fields
keybirth_yeargender_keygendergender_idclub_textslug
Failure Rules
- Missing first or last name fails immediately.
- Invalid gender values route through mismatch handling before hitting lookup/database validation.
- Player lifecycle operations must preserve historical identity references.
4. Frontend Registry Mapping
Grid Columns
| label | field | source |
|---|---|---|
| Last Name | last_name | derived from v_players.full_name / players.last_name |
| First Name | first_name | derived from v_players.full_name / players.first_name |
| Birth Year | birth_year | players.birth_year |
| Gender | gender_key | genders |
| Status | status | players.status |
Filters
| filter | field | type |
|---|---|---|
| Search | name, club_name, team_name | text substring |
| Club | club_id | relationship select |
| Birth Year | birth_year | derived select |
| Gender | gender_id | lookup select |
| Status | status | select |
Display Logic
- First and last name columns are derived from
full_namewhen structured name parts are absent. - Search spans related club and team context even though the grid only shows player-centric columns.
5. Lifecycle Rules
- Player lifecycle is protected by the finalized delete system. Historical match participation must never be erased.
- Player delete behavior must use the official archive/delete functions rather than ad hoc row deletes.
- Snapshot fields and match history invariants remain authoritative across lifecycle transitions.