elmeg-demo/.specify/tasks/16_glossary.md

Glossary Feature Specification

Overview

A wiki-style glossary system for defining and explaining fandom-specific terms, slang, and concepts. Users can suggest entries, and moderators/admins approve them before publication.

Use Cases

• Jam Band Terms: "Bustout", "Tease", "Segue", "Type II Jam"
• Venue Nicknames: "The Gorge", "Red Rocks"
• Song Nicknames: Already handled by PerformanceNickname, but glossary can define broader terms
• Cultural References: "Couch Tour", "Lot Scene", "Heady"

Data Model

GlossaryEntry

class GlossaryEntry(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    term: str = Field(unique=True, index=True)
    definition: str = Field(description="Main definition text")
    example: Optional[str] = Field(default=None, description="Usage example")
    category: str = Field(default="general", index=True) # general, venue, song, culture
    status: str = Field(default="pending", index=True) # pending, approved, rejected
    suggested_by: int = Field(foreign_key="user.id")
    created_at: datetime = Field(default_factory=datetime.utcnow)
    updated_at: datetime = Field(default_factory=datetime.utcnow)
    
    user: "User" = Relationship()

GlossaryEdit (Revision History)

class GlossaryEdit(SQLModel, table=True):
    id: Optional[int] = Field(default=None, primary_key=True)
    entry_id: int = Field(foreign_key="glossaryentry.id")
    user_id: int = Field(foreign_key="user.id")
    field_changed: str # definition, example, category
    old_value: str
    new_value: str
    status: str = Field(default="pending") # pending, approved, rejected
    created_at: datetime = Field(default_factory=datetime.utcnow)
    
    entry: "GlossaryEntry" = Relationship()
    user: "User" = Relationship()

API Endpoints

Public

• GET /glossary/ - List all approved entries (with search/filter)
• GET /glossary/{term} - Get a specific entry by term

Authenticated

• POST /glossary/ - Suggest a new entry
• POST /glossary/{id}/edit - Suggest an edit to an existing entry

Moderator/Admin

• GET /moderation/queue/glossary - List pending entries
• PUT /moderation/glossary/{id}/{action} - Approve/Reject entry
• GET /moderation/queue/glossary-edits - List pending edits
• PUT /moderation/glossary-edits/{id}/{action} - Approve/Reject edit

Frontend Components

Public

• /glossary - Glossary index page with search
• /glossary/[term] - Individual term page

Authenticated

• "Suggest Term" button on glossary index
• "Suggest Edit" button on term pages

Admin

• /admin/glossary - Queue for pending entries and edits

Workflow

New Entry

1. User submits a new term via form
2. Entry created with status=pending
3. Moderator reviews in /admin/glossary
4. On approval, status=approved and entry is public

Edit Existing Entry

1. User clicks "Suggest Edit" on a term page
2. GlossaryEdit record created with status=pending
3. Moderator reviews edit
4. On approval, the GlossaryEntry is updated and GlossaryEdit.status=approved

Integration Points

• Search: Include glossary terms in global search
• Inline Tooltips: Hovering over a glossary term in comments/reviews shows a tooltip with the definition
• Auto-linking: Detect glossary terms in user-generated content and auto-link them

Future Enhancements

• Voting: Community voting on definitions
• Aliases: Multiple terms pointing to the same entry (e.g., "The Gorge" → "Gorge Amphitheatre")
• Cross-references: Link related terms