thrillwiki_django_no_react/.clinerules/django-moderation-integration.md

Brief overview

Guidelines for integrating new Django moderation systems while preserving existing functionality, based on ThrillWiki project patterns. These rules ensure backward compatibility and proper integration when extending moderation capabilities.

Integration approach

• Always preserve existing models and functionality when adding new moderation features
• Use comprehensive model integration rather than replacement - combine original and new models in single files
• Maintain existing method signatures and property aliases for backward compatibility
• Fix field name mismatches systematically across services, selectors, and related components

Django model patterns

• All models must inherit from TrackedModel base class and use pghistory for change tracking
• Use proper Meta class inheritance: class Meta(TrackedModel.Meta):
• Maintain comprehensive business logic methods on models (approve, reject, escalate)
• Include property aliases for backward compatibility when field names change

Service and selector updates

• Update services and selectors to match restored model field names systematically
• Use proper field references: user instead of submitted_by, created_at instead of submitted_at
• Maintain transaction safety with select_for_update() in services
• Keep comprehensive error handling and validation in service methods

Migration strategy

• Create migrations incrementally and handle field changes with proper defaults
• Test Django checks after each major integration step
• Apply migrations immediately after creation to verify database compatibility
• Handle nullable field changes with appropriate migration prompts

Documentation requirements

• Update docs/types-api.ts with complete TypeScript interface definitions
• Update docs/lib-api.ts with comprehensive API client implementation
• Ensure full type safety and proper error handling in TypeScript clients
• Document all new API endpoints and integration patterns

Testing and validation

• Run Django system checks after each integration step
• Verify existing functionality still works after adding new features
• Test both original workflow and new moderation system functionality
• Confirm database migrations apply successfully without errors