Turfi Platform Documentation

Turfi needs a platform-level narrative that explains why the product exists before readers dive into engine-specific implementation detail. This document frames the ecosystem problem Turfi solves, how users and operators experience the platform, and why the product strategy matters to the rest of the architecture.

Before deep technical reading, see Platform Philosophy and Scope for what Turfi is not (competition governance, registration replacement, federation workflows), the Consensus Engine for Sports Reality model, and how game-centric design and derived outputs should be interpreted.

It fits at the top of the documentation system because every deeper technical decision ultimately serves this product model. As Turfi expands, this file should remain the strategic front door that connects the market story, user context, and platform direction.

What Makes Turfi Different (partners, prospects, positioning)

Turfi is not a league management system in the sense of owning registrations, federation compliance, or centralized scheduling mandate for an entire ecosystem.

Turfi is a consensus engine that reconstructs sports reality using media, AI, official data when available, and community input—instead of assuming one manual spreadsheet or one upstream feed is always correct.

Short line: Turfi turns video, data, and community input into verified performance and visibility.

Longer line: Instead of relying solely on manual data entry or a single authority, Turfi builds reliable player and game insight from real evidence and reconciled signals across sources.

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

---

AI Context Notice

This document contains the full architecture documentation for the Turfi platform.

It is intended to be used as a complete system reference for:

• software developers
• AI development assistants
• architecture reviews
• system design decisions

When this document is provided as context, it should be treated as the authoritative description of the Turfi platform architecture unless explicitly overridden.

All sections of this document represent active or planned components of the Turfi system.

This document represents the authoritative architecture reference for the Turfi platform.

All system implementations, database changes, API changes, and architectural decisions must remain consistent with this documentation unless this document is explicitly updated.

Generated documentation snapshots represent the platform architecture at the time of generation.

Documentation Metadata

Generated: 2025-03-06 Documentation Version: Snapshot Platform Environment: Development Database Schema Snapshot: Current Supabase Schema

Documentation Expansion Summary

This section summarizes the documentation expansion performed to ensure all platform sections are fully documented.

Sections Updated

• Player Engine: Expanded Player Lifecycle and Deletion Strategy (Archive, Safe Delete, Force Delete); added Historical Identity Preservation, Snapshot Identity Trigger; documented match history preservation architectural rule
• Competition Engine: Added Event Identity Model (player_id, player_name_text, assist_player_id; rendering logic; snapshot importance)
• Infrastructure Engine: Documented player deletion RPCs (archive_player, delete_player_safe, force_delete_player, fn_player_dependency_summary)
• Admin Data Architecture: Added Player Deletion Workflow (dependency preview, Archive/Safe Delete/Force Delete flow, role-based Force Delete)
• Future Data Governance: Added Player Merge System (Planned) subsection
• Database Documentation: Added players table with Player Identity Lifecycle (active, archived, deleted; match history preservation)
• Platform Overview: Added new section summarizing platform capabilities and architecture
• Identity Engine: Added full section with Purpose, Architecture, Database Models, Workflows, and status (IMPLEMENTED)
• Player Engine: Added full section consolidating player identity, duplicate detection, claim engine references (IMPLEMENTED)
• Recruitment Engine: Added full section; tables and workflows partially implemented (IMPLEMENTED for workspace; PLANNED for advanced features)
• Social Engine: Added full section with activity feed architecture (IMPLEMENTED)
• Broadcast Engine: Added IMPLEMENTED/PLANNED status labels
• RPC Functions: Updated with confirmed application-invoked RPCs (auto_resolve_entities, resolve_*_entity, archive_player, delete_player_safe, force_delete_player, ignore_entity_resolution_queue)
• Recruitment Engine Tables: Expanded with shared models and planned tables
• Status labels: Applied IMPLEMENTED/PLANNED to all engine and system sections

Sections Created

• Turfi Registry Governance and Entity Lifecycle: Controlled entity lifecycle, safe deletion, historical identity protection, direct delete triggers, dependency inspection, universal deletion engine
• Platform Overview: High-level platform summary and capability map
• Identity Engine (Technical Architecture): Full engine documentation
• Player Engine (Technical Architecture): Full engine documentation
• Recruitment Engine (Technical Architecture): Full engine documentation
• Social Engine (Technical Architecture): Full engine documentation

Sections Marked Implemented

• Identity Engine, Player Engine, Infrastructure Engine, Match Intelligence Engine, Media Engine
• Import System, Entity Resolution System, Admin Data Architecture, Registry Governance and Entity Lifecycle, Highlight Detection System
• Audit System (architecture; full table implementation may vary)
• Entity Resolver Queue, Auto Resolver, Manual Resolution, Player Career Timeline

Sections Marked Planned

• Recruitment Engine advanced features (saved searches, scouting playlists)
• Social Engine extended features (follows, notifications)
• Broadcast Engine stream ingestion, clip generation pipelines
• Future Data Governance Systems (Duplicate Team Detection, Entity Merge Tools)
• Event Driven Editorial Drafts, Studio Editorial Automation

Platform Roles

Turfi navigation is role-aware. The authenticated user's roles are resolved from user_roles joined to roles and interpreted in the frontend through useCurrentUserRole().

Core role groups used for navigation access:

• system_admin
• super_admin
• association_admin
• club_admin
• coach
• recruiter
• scout
• player

If role resolution is unavailable, Turfi defaults to least privilege navigation (Play only).

system_admin is treated as the global platform administrator role and is granted all workspace navigation groups: Play, Recruit, Compete, Media, and Admin.

Platform Overview

Turfi is a sports platform that connects players, teams, competitions, media, recruiting visibility, and publishing workflows through a unified data architecture. The platform supports multiple workspaces (Play, Recruit, Compete, Studio, Admin) with role-based access. Core capabilities include:

• Identity & Access: Supabase Auth with OAuth and email/password; role-driven workspace visibility.
• Player & Competition Data: Canonical entities (players, teams, clubs, competitions, seasons, venues, turfs) managed through Admin Data registries and CSV/League Package imports.
• Match Intelligence: Game events, timelines, stats, moments, and highlight collections.
• Media & Highlights: Media ingestion, video intelligence, moment detection, clip extraction, and highlight reels for matches and players.
• Entity Resolution: Automatic and manual resolution of text references (e.g. player names) to internal IDs.
• Recruitment & Discovery: Player discovery, scouting workflows, and search (implemented and planned).
• Content & Publishing: Club updates, summaries, and reusable publishing outputs generated from structured sports activity.
• Admin Operations: User management, data governance, moderation, imports, and system settings.

The architecture is PostgreSQL-first with Supabase, API views for read contracts, and trigger/RPC-driven server logic. See the Platform Engine Index for navigation to detailed engine documentation.

Platform Vision

Soccer is the largest sport in the world, yet grassroots digital infrastructure remains fragmented. Players compete every week, but their performances often disappear as soon as the match ends. Clubs create media, but it often lives in disconnected tools, private folders, and short-lived social posts with no durable connection to the competition that produced it.

Turfi exists to connect that ecosystem. Matches generate data. Media generates highlights. Clubs generate updates. AI can generate summaries. Together they produce a continuous stream of meaningful sports content around the same underlying reality.

When the platform works as intended, Turfi functions as a game-centric, media-driven network where reconstructed competition context, media, recruiting, and publishing coexist in one connected environment—without Turfi acting as an external governing body for leagues or federations.

Living Sports Network

• Competition infrastructure: schedules, standings, game events, and structured match context
• Media management: highlights, moments, and club media connected to real players and matches
• Recruiting visibility: player discovery supported by verified competition evidence
• Content distribution: club updates, summaries, and reusable publishing outputs created from structured sports activity

Audience Ecosystem

Turfi creates value because different parts of the soccer ecosystem need different outcomes from the same underlying reality. A match can be history for a club, evidence for a player, scouting material for a coach, audience attention for a business, and raw material for ongoing sports content.

The platform works best when these audiences are not separated. Each one benefits from the same connected graph of competition data, media evidence, publishing output, and recruiting visibility.

Soccer Players

Build a soccer reputation.

Players gain a permanent soccer identity built on match history, performance tracking, and highlight media. Instead of their performances vanishing after the final whistle, their games and moments become visible over time and can be discovered by coaches and recruiters through structured context.

Soccer Coaches

Find and evaluate real talent.

Coaches can discover players through real match data and verified performance moments rather than relying on random social media clips. That creates a more trustworthy recruiting environment, where talent is evaluated through actual competition evidence instead of disconnected self-promotion.

Soccer Organizations

Manage and showcase the soccer community.

Organizations gain a centralized environment where matches, players, teams, and club media can be organized and distributed together. They can preserve local soccer history, promote athletes and teams through structured content, and turn everyday competition into durable visibility for their community.

Soccer Businesses

Connect with the people who live the game.

Businesses, brands, and commercial partners benefit from being present where the sport is actively happening. Instead of trying to reach fragmented attention across disconnected channels, they can participate in an environment where the soccer audience is already organized around competition, clubs, and player visibility.

Audience Use Cases

Audience Use Cases explains how each core audience interacts with Turfi in practice. The platform is valuable because it turns the same competition activity into different kinds of outcomes: reputation for players, evaluation for coaches, visibility for organizations, and audience access for businesses.

Soccer Players

Build a soccer reputation.

Players gain a permanent soccer identity built on match history, performance tracking, and highlight media. Instead of their performances vanishing after the final whistle, their games and moments become visible over time and can be discovered by coaches and recruiters through structured context.

• Track matches and performance
• Manage soccer profile
• Store and share highlights
• Show abilities to coaches
• Build competition history
• Connect with teams and opportunities

Soccer Coaches

Find and evaluate real talent.

Coaches can discover players through real match data and verified performance moments rather than relying on random social media clips. That creates a more trustworthy recruiting environment, where talent is evaluated through actual competition evidence instead of disconnected self-promotion.

• Watch matches and player moments
• Discover players through real competition
• Evaluate performance in context
• Track player development
• Identify athletes that fit the system
• Recruit with confidence

Soccer Organizations

Manage and showcase the soccer community.

Organizations gain a centralized environment where matches, players, teams, and club media can be organized and distributed together. They can preserve local soccer history, promote athletes and teams through structured content, and turn everyday competition into durable visibility for their community.

• Manage teams and competitions
• Record matches and results
• Organize club media and highlights
• Promote players and teams
• Preserve club history
• Publish content across social platforms

Soccer Businesses

Connect with the people who live the game.

Businesses, brands, and commercial partners benefit from being present where the sport is actively happening. Instead of trying to reach fragmented attention across disconnected channels, they can participate in an environment where the soccer audience is already organized around competition, clubs, and player visibility.

• Reach active soccer audiences
• Promote products and services
• Partner with clubs and competitions
• Support events and tournaments
• Sponsor players and teams
• Grow within the soccer ecosystem

Competitive Landscape

Competitive Landscape explains how Turfi sits inside a fragmented sports technology market where administration, video, capture, recruiting, and club operations are often sold as separate products.

Instead of compressing that comparison into one long page, this section breaks each market category into its own subsection so readers can browse the market context, evaluate individual competitors, and understand where Turfi still has room to grow.

Market Context

The sports technology market is fragmented across multiple categories. Administration platforms manage registration, payments, governance, and scheduling. Video analysis platforms focus on tactical review and team performance. Capture hardware companies specialize in recording and livestreaming. Recruiting platforms are optimized for athlete exposure, while club management systems concentrate on season operations and communication.

Most competitors solve only one layer of that stack. Turfi is positioned differently. It aims to connect the layers that matter most to grassroots soccer by organizing matches, players, media, and recruiting into one ecosystem instead of treating them as isolated workflows.

Legend

• 🟢 Full feature
• 🟠 Partial capability
• 🔴 Not offered

Turfi vs Spordle

Spordle is strongest in the administrative infrastructure layer, where governing bodies, leagues, clubs, registration, officiating, and operational workflows need to be coordinated in one system.

Turfi addresses a different center of gravity. Its value is in making competition, player visibility, media, and recruiting more connected around the lived reality of matches.

Spordle dominates the administrative infrastructure layer, while Turfi is positioned around the competition and media experience layer. That means the two products can be understood less as direct feature clones and more as systems occupying different parts of the soccer stack.

Additional competitors in administration platforms

• TeamSnap
• SportsEngine
• LeagueApps
• Stack Sports
• SportLoMo
• PlayMetrics
• Spond
• SportEasy

Turfi vs Hudl

Hudl is widely associated with video analysis, performance review, and connected camera workflows for coaches and teams.

Turfi approaches media from another direction. Rather than starting with film breakdown, it focuses on connecting media to a broader competition ecosystem where players, matches, moments, and recruiting all reinforce one another.

Hudl focuses on video analysis and tactical breakdown tools, while Turfi is better understood as a platform that connects video content to competition identity, player reputation, and recruiting context. Hudl is strongest in film intelligence; Turfi is strongest when media needs to live inside a larger soccer ecosystem.

Additional competitors in video analysis platforms

• Nacsport
• Dartfish
• Coach Paint
• LongoMatch
• Once Sport
• Video Coach
• KlipDraw

Turfi vs Veo

Veo specializes in automated sports capture. Its value proposition begins with recording, livestreaming, and AI-assisted event tagging from the field.

Turfi does not currently compete on camera hardware. Its differentiation is in how media is organized, preserved, and distributed inside the competition ecosystem after the match context exists.

Veo specializes in automated match capture hardware, while Turfi focuses on organizing and distributing media inside the competition ecosystem. In practice, Veo addresses how footage is captured; Turfi addresses how that footage gains long-term meaning through matches, players, and recruiting visibility.

Additional competitors in automated sports video capture

• Pixellot
• Trace
• Spiideo
• Reely
• XbotGo
• Soloshot
• AiScout

Turfi vs SportsEngine

SportsEngine is built around club, league, and program operations, especially registration, payments, communication, websites, scheduling, and season management.

Turfi is oriented toward a different outcome. Its center is competition visibility, player reputation, and media storytelling rather than broad operational administration.

SportsEngine focuses on club and league administration tools, while Turfi is better positioned around competition visibility, player reputation, and media storytelling. SportsEngine helps organizations run their programs; Turfi aims to make the soccer activity inside those programs more visible, discoverable, and reusable.

Additional competitors in club management platforms

• TeamSnap
• LeagueApps
• PlayMetrics
• Spond
• SportEasy
• TeamLinkt
• ClubSpark

Turfi vs SportsRecruits

SportsRecruits is centered on athlete exposure to college coaches through profiles, messaging, video, and recruiting discovery tools.

Turfi approaches recruiting through competition context. The idea is that discovery should emerge from verified match history, structured player identity, and media that is already connected to real competition.

SportsRecruits focuses on recruiting exposure for athletes, while Turfi aims to integrate recruiting into real competition data and match media. SportsRecruits is strongest as a recruiting network; Turfi is strongest when recruiting must be grounded in the verified context of matches and player history.

Additional competitors in recruiting platforms

• NCSA College Recruiting
• FieldLevel
• CaptainU
• RecruitSpot
• Scoutforce
• Next College Student Athlete
• BeRecruited

Market Positioning Insight

The current market is occupied by products that each dominate a specific layer of the stack. Administration platforms own registration and governance. Video products own analysis. Capture companies own recording hardware. Recruiting platforms own athlete exposure. Club management systems own operational administration.

Turfi is not trying to win by becoming a copy of each of those products at once. Its positioning opportunity is to become the ecosystem layer that connects those domains through matches, media, recruiting, and competition visibility.

Current Category Anchors

• Administration layer: Spordle
• Video analysis layer: Hudl
• Capture layer: Veo
• Recruiting layer: SportsRecruits
• Club administration layer: SportsEngine

Turfi Positioning

If Turfi continues to connect verified competition records, match-linked media, player identity, and recruiting context, it can occupy the ecosystem layer between these fragmented categories. That gives the platform a differentiated role: not only managing sports data, but making the soccer environment itself visible, searchable, and compounding over time.

Content and Publishing Network

Turfi is not only a competition system. It is also a publishing system. Matches generate structured data. Media generates highlights. Clubs generate updates. AI can generate summaries and editorial packaging. Together they create a continuous stream of meaningful sports content around the same underlying competition graph.

This matters because grassroots sports rarely suffer from a lack of activity. They suffer from a lack of durable structure around that activity. Turfi turns ordinary match operations into reusable publishing inputs that can power profiles, highlight collections, club updates, recruiting surfaces, and broader audience discovery.

Publishing Flow

Why It Matters

• Competition data becomes publishing fuel instead of remaining trapped in admin workflows.
• Media gains durable meaning because it is attached to real matches, players, and teams.
• Clubs can publish more consistently without rebuilding context from scratch every time.
• Recruiting visibility improves when content and competition evidence stay connected.

Network Effect

Turfi grows through a reinforcing ecosystem dynamic rather than a single-user utility model. Players go where competition exists. Coaches go where players are visible. Clubs go where their athletes gain exposure. Businesses go where the audience gathers.

When those audiences converge in the same environment, the platform becomes self-reinforcing. More competition produces more visibility, more visibility attracts more recruiting attention, and more attention creates more value for clubs and commercial participants.

The publishing layer strengthens that loop. Every new match, highlight, update, and summary increases the amount of structured content circulating through the network, which gives every audience more reasons to return.

Club Media Vision

Media is strategically central to Turfi because grassroots clubs already produce large volumes of content: game footage, highlights, photos, and livestreams. The problem is not lack of content. The problem is that the content is usually scattered across phones, chat groups, hard drives, and social platforms with no durable structure around it.

Turfi aims to become the environment where club soccer media is stored, organized, and connected to the competition ecosystem. Over time, clubs should be able to store match footage, attach media to players and matches, preserve club history, and distribute content outward to social platforms from a system that already understands the underlying game context.

The goal is not to replace federation administration systems. Turfi is positioned as the competition, media, and publishing layer that sits around the game itself, making the lived reality of grassroots soccer visible, searchable, reusable, and easier to distribute.

Platform Identity

Turfi is the competitive, media, recruiting, and publishing network of grassroots soccer.

It is where players build their reputation, clubs broadcast and publish their game, coaches discover talent, and competition activity becomes ongoing sports content.

User Guide

Navigation

Authenticated users see role-based navigation sections.

Play

Visible to all authenticated users.

• Players
• Teams
• Competitions
• Games

Recruit

Visible to:

• system_admin
• super_admin
• association_admin
• club_admin
• recruiter
• scout

Menu items:

• Player Discovery
• Scouting Notes
• Recruitment Boards

Compete

Visible to:

• system_admin
• super_admin
• association_admin
• club_admin
• coach

Menu items:

• Competition Management
• Teams
• Rosters
• Scheduling

Media

Visible to:

• system_admin
• super_admin
• club_admin
• coach

Menu items:

• Highlights
• Media Library
• Game Media

Admin

Visible only to:

• system_admin
• super_admin

Menu items:

• Platform Users
• Moderation
• Platform Settings
• System Logs

Media and Highlights

Turfi media and highlights features provide a shared way to upload, review, and reuse sports media across player, match, recruitment, and admin experiences.

At runtime, media workflows begin with a source asset and then branch into moments, highlight items, and highlight collections that can be surfaced in different contexts without duplicating the original file.

Typical user flows include:

• Uploading raw media for a game or player context
• Reviewing detected moments and selecting key clips
• Registering source match video and provider event imports before approval into canonical game_events
• Building highlight collections for recap or scouting use
• Publishing those highlights to player pages, game pages, and activity surfaces

Common use cases:

• A coach compiles a post-match highlight reel for team review
• A scout bookmarks specific player clips from match footage
• Admin staff validates media metadata and processing status before publication
• League or club operators process source videos through event attribution, moment generation, clip extraction, and player highlight ranking

Articles

Articles allow editorial content to be published on the Turfi platform. Articles may reference players, teams, games, competitions, and media assets.

Articles are connected to the sports graph through linking tables:

• article_players
• article_teams
• article_games
• article_competitions
• article_media
• article_tags

Articles appear on player pages, game pages, competition pages, and the public feed.