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.

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.

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.

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.

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.

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.

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).

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