thrilltrack-explorer/migration/PHASE_03_SACRED_PIPELINE.md

PHASE 3: Sacred Pipeline - Submissions

Status: ⬜ Not Started
Estimated Time: 20-25 hours
Priority: ⚠️ CRITICAL - THIS IS THE HEART OF THRILLWIKI
Depends On: Phase 1 (Foundation), Phase 2 (Authentication)
Blocks: All entity creation/editing features

---

🎯 Phase Goal

Replace the ENTIRE submission system from Supabase to Django while maintaining 100% Sacred Pipeline integrity: Form → Submission → Moderation → Approval → Versioning → Display

---

⚠️ CRITICAL WARNING

The Sacred Pipeline is NON-NEGOTIABLE. Every single entity creation/edit MUST flow through:

1. User submits form
2. Creates submission record
3. Goes to moderation queue
4. Moderator approves/rejects
5. On approval → creates/updates entity + version history
6. Displays on site

NEVER bypass moderation! Exception: Users with moderator+ roles skip queue.

---

📋 Prerequisites

• Phase 1 complete (API client, types, base service)
• Phase 2 complete (Authentication working)
• Django submission endpoints tested
• Understanding of entitySubmissionHelpers.ts (1,200+ lines!)
• Django Sacred Pipeline working and tested

---

🗂️ Files to Create/Modify

src/services/submissions/
├── submissionService.ts    (NEW)
├── types.ts                (NEW)
└── index.ts                (NEW)

src/lib/
├── entitySubmissionHelpers.ts  (MAJOR REWRITE - 1,200+ lines!)

Forms that need updating:
src/components/forms/
├── ParkForm.tsx           (MODIFY)
├── RideForm.tsx           (MODIFY)
├── CompanyForm.tsx        (MODIFY)
├── RideModelForm.tsx      (MODIFY)
└── TimelineEventForm.tsx  (MODIFY)

---

✅ Task 3.1: Submission Service Core (8 hours)

Checklist

• Create src/services/submissions/submissionService.ts
• Implement create submission
  • createSubmission(data: SubmissionData): Promise<Submission>
  • Handle single entity submissions
  • Handle composite submissions (park + operator)
  • Map form data to Django schema
• Implement create with items
  • createSubmissionWithItems(items: SubmissionItem[]): Promise<Submission>
  • Handle dependency order
  • Handle temp IDs for relationships
• Implement get submission
  • getSubmission(id: string): Promise<Submission>
  • Include all submission items
  • Include relational data
• Implement list submissions
  • listSubmissions(filters?: SubmissionFilters): Promise<Submission[]>
  • Filter by user
  • Filter by status
  • Filter by type
• Implement update submission status
  • For moderators only
  • Handle in moderation service
• Handle errors properly
  • Validation errors
  • Rate limiting
  • Network errors
• Add retry logic
• Test with simple submission
• Test with composite submission

Django Endpoints

POST   /api/v1/submissions/              // Create submission
POST   /api/v1/submissions/with-items/   // Create with items
GET    /api/v1/submissions/{id}/         // Get submission
GET    /api/v1/submissions/              // List submissions
GET    /api/v1/submissions/my/           // User's submissions

Acceptance Criteria

• Can create park submission
• Can create ride submission
• Can create composite (park + operator)
• Submission goes to moderation queue
• Errors are handled correctly
• Rate limiting works

---

✅ Task 3.2: Rewrite entitySubmissionHelpers.ts (12 hours)

⚠️ THIS IS THE BIG ONE

This file has 1,200+ lines of Supabase code. Every function must be rewritten to use Django service.

Functions to Rewrite

Park Submissions

• submitParkCreation() - Create new park

  • Use submission service
  • Handle location data
  • Handle operator/owner references
  • Handle images
  • Test simple park creation
  • Test park + operator creation
  • Test park + operator + owner creation

• submitParkUpdate() - Edit existing park

  • Fetch existing park data
  • Extract changed fields only
  • Block new photo uploads (use gallery)
  • Allow banner/card reassignments
  • Test park edit

Ride Submissions

• submitRideCreation() - Create new ride

  • Handle park reference
  • Handle manufacturer/designer references
  • Handle ride model reference
  • Handle images
  • Handle technical specifications
  • Test simple ride creation
  • Test ride + manufacturer creation
  • Test ride + park + manufacturer creation

• submitRideUpdate() - Edit existing ride

  • Fetch existing ride data
  • Extract changed fields
  • Block new photo uploads
  • Test ride edit

Company Submissions

• submitManufacturerCreation() - Create manufacturer
• submitManufacturerUpdate() - Edit manufacturer
• submitDesignerCreation() - Create designer
• submitDesignerUpdate() - Edit designer
• submitOperatorCreation() - Create operator
• submitOperatorUpdate() - Edit operator
• submitPropertyOwnerCreation() - Create property owner
• submitPropertyOwnerUpdate() - Edit property owner

Ride Model Submissions

• submitRideModelCreation() - Create ride model

  • Handle manufacturer reference
  • Handle technical specifications
  • Test ride model creation

• submitRideModelUpdate() - Edit ride model

  • Test ride model edit

Timeline Event Submissions

• submitTimelineEvent() - Create timeline event

  • Handle entity references
  • Handle date precision
  • Test timeline creation

• submitTimelineEventUpdate() - Edit timeline event

  • Test timeline edit

Composite Submissions

• submitCompositeCreation() - Master function
  • Handle dependency ordering
  • Map temp IDs to order indices
  • Validate all temp refs
  • Handle all entity combinations:
    • Park + Operator
    • Park + Operator + Owner
    • Ride + Manufacturer
    • Ride + Manufacturer + Model
    • Ride + Park + Manufacturer + Model
  • Test all combinations

CRITICAL REQUIREMENTS

1. NO JSON in SQL - Use relational tables:

   • park_submissions
   • ride_submissions
   • company_submissions
   • ride_model_submissions
   • timeline_event_submissions

2. Rate Limiting - Keep existing logic:

   • checkRateLimitOrThrow()
   • recordSubmissionAttempt()

3. Ban Checking - Keep existing logic:

   • Check if user is banned
   • Report ban evasion attempts

4. Image Handling:

   • Upload images first
   • Only allow uploads on creation
   • Block uploads on edits (use gallery)
   • Allow banner/card reassignments

5. Error Handling:

   • Retry logic with exponential backoff
   • Validation errors don't retry
   • Network errors do retry (max 3)
   • User-friendly error messages

6. Validation:

   • Client-side validation before submit
   • Use validation functions
   • Clear error messages

Testing Checklist

• Create park (simple)
• Create park + operator
• Create park + operator + owner (same company)
• Create park + operator + owner (different companies)
• Edit park
• Create ride (simple)
• Create ride + manufacturer
• Create ride + manufacturer + model
• Create ride + park + manufacturer + model
• Edit ride
• Create manufacturer
• Edit manufacturer
• Create designer
• Edit designer
• Create operator
• Edit operator
• Create property owner
• Edit property owner
• Create ride model
• Edit ride model
• Create timeline event
• Edit timeline event
• Rate limiting works
• Ban checking works
• Validation works
• Error handling works
• Retry logic works
• All go to moderation queue
• Moderators skip queue

Acceptance Criteria

• Zero supabase.* calls in file
• All 16+ submission types work
• Composite submissions work
• Sacred Pipeline intact
• Rate limiting works
• Ban checking works
• Images upload correctly
• Validation prevents bad data
• Errors are user-friendly
• All submissions go to moderation
• TypeScript compiles without errors

---

🎯 Phase Completion Criteria

Code Quality

• Zero Supabase calls in entitySubmissionHelpers.ts
• Zero Supabase calls in form components
• All TypeScript errors resolved
• No linter warnings
• Code well-documented
• Consistent error handling

Functionality - MUST TEST ALL

• Park creation works
• Park editing works
• Park + operator creation works
• Ride creation works
• Ride editing works
• Ride + manufacturer creation works
• Ride + manufacturer + model creation works
• Manufacturer creation/editing works
• Designer creation/editing works
• Operator creation/editing works
• Property owner creation/editing works
• Ride model creation/editing works
• Timeline event creation/editing works
• Composite submissions work
• All submissions go to moderation queue
• Moderators can skip queue
• Rate limiting prevents spam
• Ban checking prevents abuse
• Images upload correctly
• Validation catches errors
• Error messages are clear

Sacred Pipeline Integrity

• ✅ Form captured correctly
• ✅ Submission created in Django
• ✅ Goes to moderation queue
• ✅ Moderator can approve/reject
• ✅ Approval creates entity + version
• ✅ Entity displays on site
• ✅ Version history recorded
• ✅ NEVER bypasses moderation (except moderators)

---

📊 Progress Tracking

Started: [Date]
Completed: [Date]
Time Spent: [Hours]

Tasks Completed

• Task 3.1: Submission Service Core
• Task 3.2: Rewrite entitySubmissionHelpers.ts
  • Park submissions
  • Ride submissions
  • Company submissions
  • Ride model submissions
  • Timeline event submissions
  • Composite submissions
  • Testing all submission types

---

🚨 Blockers & Issues

Document any issues:

1. Issue: [Description]
   • Impact: [Impact]
   • Resolution: [Resolution]

---

📝 Notes

Important Decisions:

• [Date] - [Decision about submission flow]

Learnings:

• [Date] - [Important learning]

---

⏭️ Next Phase

Once complete, proceed to Phase 4: Entity Services

---

🆘 If You Get Stuck

1. Check Django submission endpoints work: django/api/v1/endpoints/submissions.py
2. Check Django submission services: django/apps/entities/services/
3. Review Sacred Pipeline docs: django/SACRED_PIPELINE_AUDIT_AND_IMPLEMENTATION_PLAN.md
4. Test with Postman/curl first
5. Don't proceed until submissions work end-to-end