thrillwiki_django_no_react/docs/state_machines/diagrams.md

# State Machine Diagrams

This document contains Mermaid state diagrams for all models with state machines in ThrillWiki.

## EditSubmission / PhotoSubmission States

User submissions for edits and photos follow the same state flow.

```mermaid
stateDiagram-v2
    [*] --> PENDING: User submits
    
    PENDING --> APPROVED: Moderator approves
    PENDING --> REJECTED: Moderator rejects
    PENDING --> ESCALATED: Moderator escalates
    
    ESCALATED --> APPROVED: Admin approves
    ESCALATED --> REJECTED: Admin rejects
    
    APPROVED --> [*]
    REJECTED --> [*]
    
    note right of PENDING
        Guards: None (any authenticated user)
        Callbacks: None
    end note
    
    note right of APPROVED
        Guards: PermissionGuard (moderator+)
        Callbacks: 
        - Apply changes to target object
        - Send approval notification
        - Invalidate cache
    end note
    
    note right of REJECTED
        Guards: PermissionGuard (moderator+)
        Callbacks:
        - Send rejection notification with reason
    end note
    
    note right of ESCALATED
        Guards: PermissionGuard (moderator+)
        Callbacks:
        - Notify admins of escalation
        - Update escalation_level
    end note
```

### Transition Matrix

| From State | To State | Required Role | Guard |
|------------|----------|---------------|-------|
| PENDING | APPROVED | MODERATOR+ | PermissionGuard |
| PENDING | REJECTED | MODERATOR+ | PermissionGuard |
| PENDING | ESCALATED | MODERATOR+ | PermissionGuard |
| ESCALATED | APPROVED | ADMIN+ | PermissionGuard |
| ESCALATED | REJECTED | ADMIN+ | PermissionGuard |

## ModerationReport States

Content reports from users follow a review workflow.

```mermaid
stateDiagram-v2
    [*] --> PENDING: User reports content
    
    PENDING --> UNDER_REVIEW: Moderator claims report
    
    UNDER_REVIEW --> RESOLVED: Issue fixed
    UNDER_REVIEW --> DISMISSED: Invalid report
    
    RESOLVED --> [*]
    DISMISSED --> [*]
    
    note right of PENDING
        Priority: LOW, MEDIUM, HIGH, CRITICAL
        Auto-assigned based on report type
    end note
    
    note right of UNDER_REVIEW
        Guards: PermissionGuard (moderator+)
        Sets: assigned_moderator
        Callbacks: Update queue counts
    end note
    
    note right of RESOLVED
        Guards: AssignmentGuard (assigned moderator)
        Sets: resolved_at, resolution_action
        Callbacks: Notify reporter
    end note
    
    note right of DISMISSED
        Guards: AssignmentGuard (assigned moderator)
        Sets: resolved_at, resolution_notes
        Callbacks: Notify reporter
    end note
```

### Transition Matrix

| From State | To State | Required Role | Additional Guard |
|------------|----------|---------------|------------------|
| PENDING | UNDER_REVIEW | MODERATOR+ | None |
| UNDER_REVIEW | RESOLVED | MODERATOR+ | AssignmentGuard |
| UNDER_REVIEW | DISMISSED | MODERATOR+ | AssignmentGuard |

## ModerationQueue States

Queue items for moderator work.

```mermaid
stateDiagram-v2
    [*] --> PENDING: Item created
    
    PENDING --> IN_PROGRESS: Moderator claims
    PENDING --> CANCELLED: Cancelled
    
    IN_PROGRESS --> COMPLETED: Work finished
    IN_PROGRESS --> CANCELLED: Cancelled
    
    COMPLETED --> [*]
    CANCELLED --> [*]
    
    note right of IN_PROGRESS
        Guards: PermissionGuard (moderator+)
        Sets: assigned_to, assigned_at
    end note
    
    note right of COMPLETED
        Guards: AssignmentGuard
        Sets: completed_at
    end note
```

## BulkOperation States

Admin bulk operations with progress tracking.

```mermaid
stateDiagram-v2
    [*] --> PENDING: Operation created
    
    PENDING --> RUNNING: Operation starts
    PENDING --> CANCELLED: Admin cancels
    
    RUNNING --> COMPLETED: All items processed
    RUNNING --> FAILED: Fatal error
    RUNNING --> CANCELLED: Admin cancels (if cancellable)
    
    COMPLETED --> [*]
    FAILED --> [*]
    CANCELLED --> [*]
    
    note right of PENDING
        Guards: PermissionGuard (admin+)
        Fields: total_items, parameters
    end note
    
    note right of RUNNING
        Guards: PermissionGuard (admin+)
        Sets: started_at
        Progress: processed_items / total_items
    end note
    
    note right of COMPLETED
        Sets: completed_at
        Fields: processed_items, results
    end note
    
    note right of FAILED
        Sets: completed_at
        Fields: failed_items, results (error)
    end note
```

### Transition Matrix

| From State | To State | Required Role | Condition |
|------------|----------|---------------|-----------|
| PENDING | RUNNING | ADMIN+ | None |
| PENDING | CANCELLED | ADMIN+ | None |
| RUNNING | COMPLETED | ADMIN+ | None |
| RUNNING | FAILED | ADMIN+ | None |
| RUNNING | CANCELLED | ADMIN+ | can_cancel=True |

## Park Status States

Park lifecycle management.

```mermaid
stateDiagram-v2
    [*] --> UNDER_CONSTRUCTION: New park announced
    [*] --> OPERATING: Existing park

    UNDER_CONSTRUCTION --> OPERATING: Grand opening
    
    OPERATING --> CLOSED_TEMP: Seasonal/temporary closure
    OPERATING --> CLOSED_PERM: Permanent closure
    
    CLOSED_TEMP --> OPERATING: Reopens
    CLOSED_TEMP --> CLOSED_PERM: Becomes permanent
    
    CLOSED_PERM --> DEMOLISHED: Site cleared
    CLOSED_PERM --> RELOCATED: Moved to new location
    
    DEMOLISHED --> [*]
    RELOCATED --> [*]
    
    note right of OPERATING
        Default state for active parks
        Guards: Any authenticated user
    end note
    
    note right of CLOSED_TEMP
        Seasonal closures, maintenance
        Guards: Any authenticated user
    end note
    
    note right of CLOSED_PERM
        Guards: PermissionGuard (moderator+)
        Sets: closing_date
        Callbacks: Update ride statuses
    end note
    
    note right of DEMOLISHED
        Guards: PermissionGuard (moderator+)
        Final state - no transitions out
    end note
    
    note right of RELOCATED
        Guards: PermissionGuard (moderator+)
        Final state - link to new location
    end note
```

### Transition Matrix

| From State | To State | Required Role | Sets |
|------------|----------|---------------|------|
| UNDER_CONSTRUCTION | OPERATING | USER+ | None |
| OPERATING | CLOSED_TEMP | USER+ | None |
| OPERATING | CLOSED_PERM | MODERATOR+ | closing_date |
| CLOSED_TEMP | OPERATING | USER+ | None |
| CLOSED_TEMP | CLOSED_PERM | MODERATOR+ | closing_date |
| CLOSED_PERM | DEMOLISHED | MODERATOR+ | None |
| CLOSED_PERM | RELOCATED | MODERATOR+ | None |

## Ride Status States

Ride lifecycle with scheduled closures.

```mermaid
stateDiagram-v2
    [*] --> UNDER_CONSTRUCTION: New ride announced
    [*] --> OPERATING: Existing ride

    UNDER_CONSTRUCTION --> OPERATING: Grand opening
    
    OPERATING --> CLOSED_TEMP: Maintenance/refurb
    OPERATING --> SBNO: Extended closure
    OPERATING --> CLOSING: Scheduled closure
    
    CLOSED_TEMP --> OPERATING: Reopens
    CLOSED_TEMP --> SBNO: Extended to SBNO
    CLOSED_TEMP --> CLOSED_PERM: Permanent closure
    
    SBNO --> OPERATING: Revival
    SBNO --> CLOSED_PERM: Confirmed closure
    
    CLOSING --> SBNO: Becomes SBNO
    CLOSING --> CLOSED_PERM: Closure date reached
    
    CLOSED_PERM --> DEMOLISHED: Removed
    CLOSED_PERM --> RELOCATED: Moved
    
    DEMOLISHED --> [*]
    RELOCATED --> [*]
    
    note right of OPERATING
        Active ride
        Guards: Any authenticated user
    end note
    
    note right of CLOSED_TEMP
        Short-term closure
        Guards: Any authenticated user
    end note
    
    note right of SBNO
        Standing But Not Operating
        Guards: PermissionGuard (moderator+)
        Long-term uncertainty
    end note
    
    note right of CLOSING
        Scheduled to close
        Guards: PermissionGuard (moderator+)
        Requires: closing_date, post_closing_status
        Automated transition on date
    end note
    
    note right of CLOSED_PERM
        Guards: PermissionGuard (moderator+)
        Sets: closing_date
    end note
    
    note right of DEMOLISHED
        Guards: PermissionGuard (moderator+)
        Final state
    end note
    
    note right of RELOCATED
        Guards: PermissionGuard (moderator+)
        Final state - link to new installation
    end note
```

### CLOSING State Automation

The CLOSING state is special - it represents a ride that has been announced to close on a specific date. When the `closing_date` is reached, the ride automatically transitions to the `post_closing_status` (SBNO, CLOSED_PERM, DEMOLISHED, or RELOCATED).

```mermaid
sequenceDiagram
    participant User
    participant Ride
    participant Scheduler
    
    User->>Ride: mark_closing(closing_date, post_closing_status)
    Ride->>Ride: transition_to_closing()
    Ride->>Ride: Set closing_date, post_closing_status
    Ride->>Ride: Save
    
    Note over Scheduler: Daily job runs
    
    Scheduler->>Ride: Check closing_date <= today
    alt Date reached
        Scheduler->>Ride: apply_post_closing_status()
        Ride->>Ride: Transition to post_closing_status
        Ride->>Ride: Save
    end
```

### Transition Matrix

| From State | To State | Required Role | Sets |
|------------|----------|---------------|------|
| UNDER_CONSTRUCTION | OPERATING | USER+ | None |
| OPERATING | CLOSED_TEMP | USER+ | None |
| OPERATING | SBNO | MODERATOR+ | None |
| OPERATING | CLOSING | MODERATOR+ | closing_date, post_closing_status |
| CLOSED_TEMP | OPERATING | USER+ | None |
| CLOSED_TEMP | SBNO | MODERATOR+ | None |
| CLOSED_TEMP | CLOSED_PERM | MODERATOR+ | closing_date |
| SBNO | OPERATING | MODERATOR+ | None |
| SBNO | CLOSED_PERM | MODERATOR+ | None |
| CLOSING | SBNO | MODERATOR+ | None |
| CLOSING | CLOSED_PERM | MODERATOR+ | None |
| CLOSED_PERM | DEMOLISHED | MODERATOR+ | None |
| CLOSED_PERM | RELOCATED | MODERATOR+ | None |

## State Color Legend

All state machines use consistent colors for states:

| Color | Meaning | Example States |
|-------|---------|----------------|
| 🟡 Yellow | Pending/Waiting | PENDING, UNDER_REVIEW, CLOSING |
| 🟢 Green | Active/Approved | OPERATING, APPROVED, COMPLETED |
| 🔴 Red | Closed/Rejected | REJECTED, FAILED, CLOSED_PERM |
| 🟠 Orange | Warning/SBNO | SBNO, ESCALATED, IN_PROGRESS |
| ⚫ Gray | Final/Terminal | DEMOLISHED, RELOCATED, CANCELLED |
| 🔵 Blue | Temporary | CLOSED_TEMP, UNDER_CONSTRUCTION |

## Guard Icons

| Icon | Guard Type | Description |
|------|-----------|-------------|
| 🔐 | PermissionGuard | Role-based access |
| 👤 | OwnershipGuard | Owner verification |
| 📋 | AssignmentGuard | Assigned user check |
| 📊 | StateGuard | State validation |
| 📝 | MetadataGuard | Required fields |