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
- [x] Phase 1 complete (API client, types, base service)
- [x] 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
```typescript
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](./PHASE_04_ENTITY_SERVICES.md)

---

## 🆘 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