Turfi Platform Documentation

This document defines Turfi’s strategic positioning: what the platform is for, what it deliberately is not, and how technical systems should be interpreted. It sits ahead of engine-specific documentation so readers do not mistake implementation depth for product authority.

Shared status legend: [docs/_shared/status-legend.md](./_shared/status-legend.md)

---

Platform Philosophy and Scope

What Turfi is not

Turfi is not a competition governance platform. It does not replace provincial, national, or federation systems that own registration, sanctioning, scheduling mandates, or official eligibility.

Turfi is not a replacement for products such as Spordle or other league-operational suites whose primary job is to run registrations, rosters, and federation-mandated workflows end to end.

Turfi does not manage registrations, eligibility, or federation compliance workflows. Those concerns may exist elsewhere; they are out of scope for Turfi’s current product surface.

What Turfi is

Turfi is:

• Game-centric: the match is the primary unit around which evidence, media, and statistics accumulate.
• A player visibility and recruitment engine: identity, media, and performance context support discovery and evaluation—not administrative control of who may play where.
• A media and storytelling system: video, highlights, and moments attach to real games and players.
• A data layer that reconstructs competition context: leagues, seasons, phases, groups, and rounds exist to organize and explain play on the platform, not to govern sport outside it.

Core Identity

Turfi is a Consensus Engine for Sports Reality.

It reconstructs games, events, and player performance using multiple data sources instead of relying on a single external authority.

Turfi is powered by:

• Media — videos, clips, and highlights
• Official data — when available (federation, league, or trusted feeds)
• AI extraction and scraping — automated detection, tagging, and enrichment
• Community input — players, coaches, clubs, and operators contributing data

Turfi does not rely on a single source of truth. It builds truth through consensus across multiple signals.

Core statement

Turfi enhances and reconstructs competitions through games, events, and media. It does not govern them.

---

Official vs Observed Truth and Locking Model

This section is a foundational guideline for how authoritative results and evolving evidence coexist on the platform. It describes intent; concrete fields (for example is_locked on games) are future implementation notes and are not assumed to exist in the schema today.

Official vs Observed Truth

Turfi distinguishes between two parallel layers of truth:

1. Official Truth (governance layer) — the authoritative result of a game or competition for standings, rankings, champions, and historical records as represented on the platform (typically aligned with leagues, clubs, or governing bodies when that data is supplied or entered as the declared result).
2. Observed Truth (Turfi layer) — knowledge derived from events (game_events), media (video, highlights), AI detection, and user or club inputs. It can evolve over time and may differ from official truth.

Official Truth is used for:

• standings
• rankings
• champions
• historical records that are treated as settled for that scope

Observed Truth is used for:

• player statistics and performance analysis
• highlight validation and media-backed verification
• timelines and evidence that continue to improve as inputs are reviewed

Official truth is considered stable relative to observed truth and may be locked after a competition or season is completed (see Locking Model below).

Locking Model

After a competition or season is completed, official results may be placed in a locked state (conceptual; implementation may attach to games, competitions, or seasons in the future).

When a game or competition is locked (design intent):

• Official scores (declared results used for standings) must not be automatically modified by new events, AI, or background reconciliation.
• Standings must not be rebuilt from newly ingested events alone in a way that rewrites the official historical outcome for that scope.

Still allowed after lock:

• Events can still be added, edited, and validated for observed truth.
• Media can still be attached.
• Observed truth can continue to evolve (stats, highlights, consensus views).
• Consensus comparisons (for example declared score vs event-derived score) can still be shown; mismatches remain visible.

Consensus behavior with locked data

Consensus scoring (comparing declared scores to event-derived scores) continues when official data is locked:

• The official (declared) score is treated as fixed for that governance snapshot.
• The event-derived score may change as events are approved or corrected.
• Mismatches remain visible for review.
• The platform does not perform automatic reconciliation that overwrites official results; any change to official truth after lock must be an explicit, controlled action (see System principles).

System principles

• Turfi is not a governing body.
• Turfi does not rewrite official history after lock without an explicit, auditable action.
• Turfi enriches and refines observed data over time.
• All corrections to official results must be explicit and controlled — never silent or automatic from events alone.

Future implementation notes (non-binding)

When implemented, locking might use fields such as:

• is_locked (game-level) — official result for that game is frozen for standings/history in scope.
• is_closed (competition-level or season-level) — official results in that scope are frozen; may propagate expectations to member games in product rules.

Exact names, triggers, and migration paths belong in schema and engine docs when built.

---

Game-centric architecture

Primary object

The game (games and its linked match data) is the primary operational object. Most user-visible sport outcomes—scores, timelines, media, stats—are anchored to games.

Competitions as context, not authority

Competitions (and related entities such as seasons, phases, groups, rounds) are contextual containers. They group games for display, scheduling, and derived outputs. They are not authoritative governance systems for external bodies.

Events and consensus (match facts)

Match events (game_events and related structures) are how Turfi records attributed actions for statistics and timelines. Events may originate from multiple inputs (official feeds, manual entry, video-derived tagging, AI-assisted detection, community contribution). A row may move from proposed to canonical through review, confidence, and reconciliation—not by assuming one inbound pipe is always correct.

Aggregates such as team or player statistics are derived from canonical events (and related rules), not maintained as a parallel handwritten truth. Canonical stats must remain traceable to underlying events and, where applicable, to source media or import provenance.

Derived outputs

Scores, standings, schedules, and bracket-style views are derived outputs. They are computed or assembled from games, events, and structural links. They remain valuable for UX and analysis; they are not independent “master” records that override underlying games or events.

Flow

Use this mental model:

Media / events → Game → Competition context → Derived outputs (standings, schedules, brackets)

• Ingestion paths may supply media and events before or alongside a fully articulated competition tree.
• A game can exist with minimal surrounding structure; phases, groups, and rounds are optional where the schema allows.
• Competition links provide context for filtering, display, and rebuild rules for standings.
• Standings, schedules, and bracket renderings are outputs of that graph, not a separate governing layer.

Partial and incomplete data

The system must tolerate incomplete or partial data: friendly matches, showcases, imported histories, or video-first workflows may arrive without a full hierarchy. Structural fields that are nullable exist partly for that reason. Product and engineering decisions should prefer progressive enrichment over blocking users on non-critical missing data.

---

Consensus Engine Model

Turfi treats sports reality as something assembled from signals, not copied from one system.

Reconciliation: Games, events, statistics, standings, schedules, and profiles are outputs of pipelines that ingest, validate, and reconcile these sources over time. The platform must tolerate conflicting or partial inputs and resolve them through workflow, confidence, and explicit rules—not by discarding everything that does not match a single upstream feed.

---

Truth Layers

These layers describe how information matures inside the consensus model (conceptual; implementation may span tables, status fields, and review queues):

Principle: Canonical data is not the same as “someone typed it in a spreadsheet and locked it.” It emerges when proposed inputs pass validation, consensus rules, or operator review appropriate to the domain. Raw and proposed layers must remain inspectable so disagreements can be resolved without losing evidence.

---

Data confidence model

Not all data in Turfi carries the same epistemic weight. The platform can host information at different confidence levels (conceptual labels—not necessarily a single database enum). These levels align with Truth Layers and source mix above:

Principles

• The same schema row may move up or down confidence over time.
• Turfi does not claim external sporting authority unless an integration explicitly says so.
• Rendered outputs (standings tables, stat leaders, public copy) should respect confidence: drafts should not silently present as canonical league truth.

---

Non-goals (current phase)

The following are explicitly out of scope for the product as shipped today. The architecture may still contain hooks; they are not product commitments.

• No competition governance workflows (sanctioning, discipline, protest handling as a system of record).
• No player eligibility enforcement against external rulebooks.
• No official scheduling engine for entire leagues as the single source of mandate.
• No registration system comparable to full-season roster and fee workflows.
• No federation compliance logic as an authoritative gate.

---

Future expansion (hidden capability)

The data model and engines are structurally capable of supporting richer competition governance, tighter eligibility, and deeper scheduling in the future. That capability is intentionally not exposed in the current phase.

Requirement for engineering: avoid one-way doors that would prevent a later governance or integration layer from sitting above the same games-and-events core. Prefer clear boundaries, nullable context, and documented extension points over hard-coded assumptions that Turfi “is” the league system of record.

---

Consensus Driven Development Principles

Engineering and product decisions should reinforce the Consensus Engine model:

• Never assume a single source of truth — design for multiple feeds, media-first evidence, and reconciliation.
• Always preserve raw input data — lossy pipelines hide disputes; retain enough to audit and replay decisions.
• Support multiple inputs for the same entity — games, events, and media assets may duplicate or conflict; model IDs, provenance, and merge paths explicitly.
• Separate proposed data from canonical data — status, review, and promotion rules must be first-class.
• Ensure canonical data is traceable to its sources — lineage for events, stats, and derived outputs.
• Design for conflict — tolerate disagreement; resolve over time with explicit rules rather than silent overwrite.

These principles apply across registries, imports, media ingestion, match intelligence, and admin tooling.

---

How to read the rest of the documentation

• Competition Engine — structural schema, triggers, and derived standings. Read it as technical modeling of how Turfi reconstructs competition context from games and events—not direct governance of real-world bodies.
• Media and Match Intelligence — events, moments, and highlights. Read media as evidence, events as reconciled inputs, and stats as derived from canonical layers.
• Registries and imports — operational data management on the platform, not federation registry replacement.

When documentation elsewhere uses words like “official” or “authoritative,” interpret them in platform terms (for example, is_official driving standings rebuilds), unless explicitly scoped to an external body. Prefer consensus and provenance over implying a single upstream monopoly on truth.