> ## Documentation Index
> Fetch the complete documentation index at: https://sportsindex.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tag System

> How topics and tags work across the platform

## Overview

The topic tagging system manages how posts are associated with topics (tags) and how those associations are queried. There are two distinct tag storage systems with different semantics.

## Two Post Types, Two Tag Systems

| Post Type           | Identifier               | Tag Source          | Behavior                             |
| ------------------- | ------------------------ | ------------------- | ------------------------------------ |
| **Owned posts**     | `created_by IS NOT NULL` | `content_post_tags` | Owner's tags are permanent           |
| **Canonical posts** | `created_by IS NULL`     | `topic_post_index`  | Tags exist while users maintain them |

**Canonical posts** are external media (tweets, YouTube videos, articles) that exist independently. Multiple users can tag the same canonical post.

## Tag Storage Tables

| Table                   | Purpose                            | Cleanup                                        |
| ----------------------- | ---------------------------------- | ---------------------------------------------- |
| `content_post_tags`     | Permanent tags on owned posts      | Never cleaned up                               |
| `topic_post_index`      | Active tags from user curation     | Row deleted when `association_count` reaches 0 |
| `post_tag_associations` | User attribution (who tagged what) | Tracks individual actions                      |

## Tag Facets

Tags can have metadata facets for filtered discovery:

* **Sport**: e.g., "Pickleball", "Football"
* **Level**: e.g., "Professional", "Collegiate"

These enable endpoints like `GET /api/explore/sport/{sport_name}/topics` to filter topics by sport.

## Tag Groups

Tags can be organized into hierarchical groups using an adjacency list model. Groups have:

* A `parent_id` for tree structure (e.g., league → team)
* `display_order` for sibling ordering
* Members linked via `TagGroupMember`

## Topic Relationships

Directed relationships between tags model real-world connections:

```
Ben Johns --plays_for--> Jacksonville Jaguars (PPA)
Ben Johns --competes_in--> PPA Tour
```

Used for grouping topics on explore pages (e.g., showing players grouped by team).