---
description: Mandatory Rich Choice Objects system enforcement for ThrillWiki project replacing Django tuple-based choices with rich metadata-driven choice fields
author: ThrillWiki Development Team
version: 1.0
globs: ["apps/**/choices.py", "apps/**/models.py", "apps/**/serializers.py", "apps/**/__init__.py"]
tags: ["django", "choices", "rich-choice-objects", "data-modeling", "mandatory"]
---

# Rich Choice Objects System (MANDATORY)

## Objective
This rule enforces the mandatory use of the Rich Choice Objects system instead of Django's traditional tuple-based choices for ALL choice fields in the ThrillWiki project. It ensures consistent, metadata-rich choice handling with enhanced UI capabilities and maintainable code patterns.

## Brief Overview
Mandatory use of Rich Choice Objects system instead of Django tuple-based choices for all choice fields in ThrillWiki project.

## Rich Choice Objects Enforcement

### Absolute Requirements
🚨 **NEVER use Django tuple-based choices** (e.g., `choices=[('VALUE', 'Label')]`) - ALWAYS use RichChoiceField

### Implementation Standards
- **Field Usage**: All choice fields MUST use `RichChoiceField(choice_group="group_name", domain="domain_name")` pattern
- **Choice Definitions**: MUST be created in domain-specific `choices.py` files using RichChoice dataclass
- **Rich Metadata**: All choices MUST include rich metadata (color, icon, description, css_class at minimum)
- **Registration**: Choice groups MUST be registered with global registry using `register_choices()` function
- **Auto-Registration**: Import choices in domain `__init__.py` to trigger auto-registration on Django startup

### Required Patterns
- **Categorization**: Use ChoiceCategory enum for proper categorization (STATUS, CLASSIFICATION, TECHNICAL, SECURITY)
- **Business Logic**: Leverage rich metadata for UI styling, permissions, and business logic instead of hardcoded values
- **Serialization**: Update serializers to use RichChoiceSerializer for choice fields

### Migration Requirements
- **NO Backwards Compatibility**: DO NOT maintain backwards compatibility with tuple-based choices - migrate fully to Rich Choice Objects
- **Model Refactoring**: Ensure all existing models using tuple-based choices are refactored to use RichChoiceField
- **Validation**: Validate choice groups are correctly loaded in registry during application startup

### Domain Consistency
- **Follow Established Patterns**: Follow established patterns from rides, parks, and accounts domains for consistency
- **Domain-Specific Organization**: Maintain domain-specific choice organization in separate `choices.py` files

## Implementation Checklist

Before implementing choice fields, verify:
- [ ] RichChoiceField is used instead of Django tuple choices
- [ ] Choice group and domain are properly specified
- [ ] Rich metadata includes color, icon, description, css_class
- [ ] Choices are defined in domain-specific `choices.py` file
- [ ] Choice group is registered with `register_choices()` function
- [ ] Domain `__init__.py` imports choices for auto-registration
- [ ] Appropriate ChoiceCategory enum is used
- [ ] Serializers use RichChoiceSerializer for choice fields
- [ ] No tuple-based choices remain in the codebase

## Examples

### ✅ CORRECT Implementation
```python
# In apps/rides/choices.py
from core.choices import RichChoice, ChoiceCategory, register_choices

RIDE_STATUS_CHOICES = [
    RichChoice(
        value="operating",
        label="Operating",
        color="#10b981",
        icon="check-circle",
        description="Ride is currently operating normally",
        css_class="status-operating",
        category=ChoiceCategory.STATUS
    ),
    # ... more choices
]

register_choices("ride_status", RIDE_STATUS_CHOICES, domain="rides")

# In models.py
status = RichChoiceField(choice_group="ride_status", domain="rides")
```

### ❌ FORBIDDEN Implementation
```python
# NEVER DO THIS - Tuple-based choices are forbidden
STATUS_CHOICES = [
    ('operating', 'Operating'),
    ('closed', 'Closed'),
]

status = models.CharField(max_length=20, choices=STATUS_CHOICES)
```

## Verification Steps

To ensure compliance:
1. Search codebase for any remaining tuple-based choice patterns
2. Verify all choice fields use RichChoiceField
3. Confirm all choices have complete rich metadata
4. Test choice group registration during application startup
5. Validate serializers use RichChoiceSerializer where appropriate