feat: Implement versioning documentation

2025-12-23 03:51:13 -05:00 · 2025-10-15 17:54:53 +00:00
parent 96a5d235e9
commit ea78aff4a7
9 changed files with 2183 additions and 0 deletions
--- a/docs/versioning/README.md
+++ b/docs/versioning/README.md
@@ -0,0 +1,150 @@
+# Universal Versioning System
+
+**Complete documentation for the relational versioning system**
+
+## Overview
+
+The Universal Versioning System automatically tracks all changes to entities (parks, rides, companies, ride models) using a pure relational database structure. Every INSERT or UPDATE creates a timestamped version with full attribution and audit trail.
+
+### Key Features
+
+✅ **Automatic Version Creation** - Triggers handle versioning transparently  
+✅ **Pure Relational Structure** - No JSONB, fully queryable and type-safe  
+✅ **Full Audit Trail** - User, timestamp, and submission tracking  
+✅ **Version Comparison** - Visual diff between any two versions  
+✅ **Rollback Support** - Restore to any previous version  
+✅ **Moderation Integration** - Links versions to content submissions  
+
+### Why Relational Versioning?
+
+| Benefit | Description |
+|---------|-------------|
+| **Queryable** | Filter and search across version fields efficiently with SQL |
+| **Type-safe** | Foreign keys enforce referential integrity |
+| **Performant** | Indexed columns enable fast queries |
+| **Secure** | Row-Level Security at column level |
+| **Maintainable** | Standard SQL operations, no JSONB parsing |
+
+## Documentation Structure
+
+### Core Documentation
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System design and data flow
+- **[SCHEMA.md](./SCHEMA.md)** - Database tables, triggers, and functions
+- **[FRONTEND.md](./FRONTEND.md)** - React hooks and components
+
+### Integration Guides
+- **[MODERATION.md](./MODERATION.md)** - How versioning integrates with moderation flow
+- **[MIGRATION.md](./MIGRATION.md)** - Migrating from old JSONB system
+
+### Reference
+- **[API.md](./API.md)** - Complete API reference for all functions and hooks
+- **[BEST_PRACTICES.md](./BEST_PRACTICES.md)** - Guidelines and recommendations
+- **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)** - Common issues and solutions
+
+## Quick Start
+
+### For Developers
+
+```typescript
+// Add version indicator to entity page
+import { VersionIndicator } from '@/components/versioning/VersionIndicator';
+
+<VersionIndicator 
+  entityType="park" 
+  entityId={park.id} 
+  entityName={park.name}
+/>
+```
+
+### For Database Admins
+
+```sql
+-- Get all versions of a specific park
+SELECT * FROM park_versions 
+WHERE park_id = 'uuid-here' 
+ORDER BY version_number DESC;
+
+-- Compare two versions
+SELECT * FROM get_version_diff('park', 'version-1-uuid', 'version-2-uuid');
+```
+
+### For Moderators
+
+When approving submissions, versions are automatically created with:
+- Attribution to original submitter (not moderator)
+- Link to content submission
+- Full change tracking
+
+## Architecture at a Glance
+
+```mermaid
+graph TB
+    A[User Submits Edit] --> B[Content Submission]
+    B --> C[Moderator Approves]
+    C --> D[Edge Function]
+    D --> E[Set Session Variables]
+    E --> F[UPDATE Entity Table]
+    F --> G[Trigger Fires]
+    G --> H[create_relational_version]
+    H --> I[INSERT Version Table]
+    I --> J[Version Created]
+```
+
+## Supported Entities
+
+| Entity Type | Version Table | Main Table |
+|-------------|---------------|------------|
+| `park` | `park_versions` | `parks` |
+| `ride` | `ride_versions` | `rides` |
+| `company` | `company_versions` | `companies` |
+| `ride_model` | `ride_model_versions` | `ride_models` |
+
+## Version Lifecycle
+
+1. **Creation** - Entity INSERT triggers first version (version_number: 1)
+2. **Updates** - Each UPDATE creates new version, increments version_number
+3. **Current Flag** - Only latest version has `is_current = true`
+4. **Retention** - Old versions retained (configurable cleanup)
+5. **Rollback** - Any version can be restored, creates new version
+
+## Security Model
+
+### Row-Level Security Policies
+
+- **Public** - Can view current versions only (`is_current = true`)
+- **Moderators** - Can view all versions
+- **Users** - Can view versions they created
+- **System** - Can create versions via triggers
+
+### Session Variables
+
+The system uses PostgreSQL session variables for attribution:
+
+- `app.current_user_id` - Original submitter (not moderator)
+- `app.submission_id` - Link to content_submissions record
+
+## Performance Considerations
+
+- **Indexes** - All version tables have indexes on `entity_id`, `created_at`, `version_number`
+- **Cleanup** - Use `cleanup_old_versions()` to retain only N recent versions
+- **Queries** - Version queries are fast due to proper indexing
+
+## Next Steps
+
+1. Read [ARCHITECTURE.md](./ARCHITECTURE.md) for system design details
+2. Review [SCHEMA.md](./SCHEMA.md) for database structure
+3. Check [FRONTEND.md](./FRONTEND.md) for React integration
+4. See [API.md](./API.md) for complete function reference
+
+## Support
+
+For issues or questions:
+- Check [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) first
+- Review [BEST_PRACTICES.md](./BEST_PRACTICES.md) for guidelines
+- Consult main project documentation
+
+---
+
+**Status:** ✅ Production Ready  
+**Last Updated:** 2025-10-15  
+**Version:** 1.0.0