# 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

```python
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)

```python
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