User Flow Actions

🚀 StateForce User Flow Actions

This page provides detailed diagrams for specific user actions within the StateForce platform. These actions represent critical workflows such as creating events, registering institutions, managing resources, and handling patients. Each diagram illustrates the steps involved, from user interaction to API calls and database updates, including happy paths and error scenarios.

---

Core Concepts for Developers

Before diving into the flows, it's important to understand the guiding principles derived from the operational manual and the ERD:

🧑‍💻 Key Concepts

1. Central Coordination (CRUM): Users with roles such as Dispatcher or Manager, operating within a coordination center (coordination_center), orchestrate emergency responses.

2. Patient-Centric Workflow: Tables like patients, patient_vitals, and patient_transfers are pivotal, enabling full tracking of a patient's journey from incident to medical facility.

3. Communication Logging: The communications_log table maintains auditable records of significant communications (e.g., radio, phone) related to events.

4. Resource Management: The resources table tracks resource availability (status, available_units) for dispatchers making assignment decisions.

---

1. 🏢 Registering a New Institution

Overview

Authorized users can add institutions (hospitals, rescue bases, coordination centers) to the system.

Description:

This flow illustrates how an administrator registers a new institution, including adding its location, director, and sector type.

Actor: Superadmin or Admin
Preconditions: User is authenticated and has permissions to manage institutions.

flowchart TD
    A[Start] --> B{User navigates to the 'Institutions' dashboard};
    B --> C{User clicks 'Add New Institution'};
    C --> D[System displays the 'Create Institution' form];
    D --> E{User fills out the form};
    subgraph Form Fields
        direction LR
        E1[Name: 'General Hospital North']
        E2[Sector Type: 'Public']
        E3[Institution Type: 'Medical Center']
        E4[Location ID: Selects from a map/list]
        E5[Parent Institution ID: Optional]
    end
    E --> F{User clicks 'Save'};
    F --> G{Client-Side Validation};
    G -->|Invalid Data| H["Form highlights invalid fields with error messages, e.g., 'Name is required'"];
    H --> E;
    G -->|Valid Data| I[Frontend displays a loading spinner and disables the 'Save' button];
    I --> J[API Call: POST /api/institutions with form data];
    J --> K{Backend Processing};
    subgraph "Backend"
        K1[Authenticate & Authorize User]
        K2[Validate Data: Check if name is unique, location_id exists]
        K3[Create record in 'institutions' table]
        K4[Create record in 'audit_logs' for the creation action]
    end
    K -->|Validation Fails| L[API responds with 422 Unprocessable Entity & specific field errors];
    L --> M[Frontend hides spinner, enables button, and displays errors on the form];
    M --> E;
    K -->|Database/System Error| N[API responds with 500 Internal Server Error];
    N --> O["Frontend hides spinner and displays a generic error alert: 'An unexpected error occurred. Please try again.'"];
    O --> F;
    K -->|Success| P[API responds with 201 Created & new institution data];
    P --> Q[Frontend hides spinner, shows 'Success' toast notification, and closes the form];
    Q --> R[The new institution is now visible on the 'Institutions' dashboard];
    R --> Z[End];

    %% Cancellation Path
    D --> D_Cancel{User clicks 'Cancel'};
    D_Cancel --> R_Cancel[Form is closed without saving];
    R_Cancel --> B;

Loading

---

2. 🚨 Creating a New Event

Overview

Event creation occurs when a dispatcher logs details of an emergency based on incoming reports (e.g., phone call).

Actor: Dispatcher or Manager
Preconditions: User is authenticated.

flowchart TD
    A[Start] --> B{"Receive External Report"}
    B --> C{Click 'Create New Event'}
    C --> D[Display 'Create Event' Form]
    D --> E{Fill Event Details}
    subgraph EventFields
        E1[Incident Type]
        E2[Location]
        E3[Priority]
        E4[Reported By]
        E5[Description]
    end
    E --> F{Click 'Create Event'}
    F --> G{Validation}
    G -->|Invalid| H[Highlight Errors]
    H --> E
    G -->|Valid| I[Spinner and Disable Button]
    I --> J[API: POST /api/events]
    J --> K{Backend Processing}
    subgraph BackendActions
        K1[Validate Data]
        K2[Insert into 'events']
        K3[Log in 'communications_log']
        K4[Create 'audit_logs' Entry]
    end
    K -->|Success| L[201 Created]
    L --> M[Redirect to Event Details]
    M --> Z[End]
    K -->|Validation Error| O[422 Error]
    O --> P[Show Error Messages]
    P --> E
    K -->|System Error| Q[500 Error]
    Q --> R[Show 'Unexpected Error' Alert]
    R --> F
    D --> Cancel[User Clicks 'Cancel']
    Cancel --> B

Loading

---

3. 🚒 Managing an Active Event

This workflow details the core actions a dispatcher takes after an event is created: assigning institutions and resources, and updating the event's status. This reflects the CRUM's role in coordinating response.

Actor: Dispatcher or Manager. Preconditions: An event exists with status: 'pending' or 'active'.

flowchart TD
    A["Start: User is on the Event Detail page"] --> B{What action to take?};

    B --> B1[Assign Institution];
    B1 --> C1{User clicks 'Assign Institution'};
    C1 --> D1[System shows a list of available institutions, possibly filtered by proximity or specialty];
    D1 --> E1{User selects 'City General Hospital' and 'Rescue Unit 5'};
    E1 --> F1{User clicks 'Confirm Assignment'};
    F1 --> G1["API Call: POST /api/events/{id}/institutions with list of institution_ids"];
    G1 --> H1{Backend Processing};
    subgraph H1_Backend [For each institution]
        H1a[Create a record in 'event_institutions' with status 'assigned']
        H1b[Create an 'audit_logs' entry]
        H1c[Future Step: Send notification to the institution]
    end
    H1 --> I1[API responds 200 OK];
    I1 --> J1[UI updates to show the assigned institutions];
    J1 --> A;

    B --> B2[Assign Resource];
    B2 --> C2{User clicks 'Assign Resource'};
    C2 --> D2[System shows a list of available resources, filterable by type and owning institution];
    D2 --> E2{User selects 'Ambulance A-08' and specifies quantity 1};
    E2 --> F2{User clicks 'Confirm Assignment'};
    F2 --> G2["API Call: POST /api/events/{id}/resources"];
    G2 --> H2{Backend Processing};
    subgraph H2_Backend [Backend]
        H2a[Create record in 'event_resources']
        H2b[Update 'resources' table: available_units = available_units - 1, status = 'assigned']
        H2c[Create 'audit_logs' entry]
    end
    H2 --> I2[API responds 200 OK];
    I2 --> J2[UI updates to show the assigned resource];
    J2 --> A;

    B --> B3[Update Event Status];
    B3 --> C3{User clicks 'Update Status'};
    C3 --> D3["System displays a dropdown with valid 'EventStatus' options (e.g., 'Active', 'Resolved', 'Closed')"];
    D3 --> E3{User selects 'Resolved'};
    E3 --> F3{User clicks 'Save'};
    F3 --> G3["API Call: PUT /api/events/{id}/status"];
    G3 --> H3[Backend updates the 'status' field in the 'events' table];
    H3 --> I3[API responds 200 OK];
    I3 --> J3[UI updates to show the new event status badge];
    J3 --> Z[End];

    %% Generic Error Handling
    G1 --> G1_Error{Error};
    G1_Error --> G1_Alert["Show error alert: 'Failed to assign institutions.'"];
    G1_Alert --> A;
    G2 --> G2_Error{Error};
    G2_Error --> G2_Alert["Show error alert: 'Failed to assign resource.'"];
    G2_Alert --> A;
    G3 --> G3_Error{Error};
    G3_Error --> G3_Alert["Show error alert: 'Failed to update status.'"];
    G3_Alert --> A;

Loading

---

4. 📧 Inviting and Onboarding a New User

This workflow details how an admin invites a new user to the platform and the process the new user follows to accept the invitation and create their account.

Actor: Admin, New User. Preconditions: Admin is logged in.

flowchart TD
    %% Admin's Flow
    A["Start: Admin is on User Management dashboard"] --> B{Admin clicks Invite User};
    B --> C[System displays the Invite User form];
    C --> D{Admin fills in details: email, role to assign, and primary institution};
    D --> E{Admin clicks Send Invite};
    E --> F[API Call: POST /api/invites];
    subgraph F_Backend [Backend]
        F1[Validate data]
        F2[Generate a unique token with expiration]
        F3[Create a record in the invites table with status: sent, token, and details]
        F4[Send invitation email with token link]
    end
    F -->|Success| G[API responds 200 OK. UI shows Invite Sent confirmation];
    G --> B;
    F -->|Error| F_Err["API responds with error. UI shows alert: Failed to send invite"];
    F_Err --> D;

    %% New User's Flow
    I[Invited User receives email] --> J{User clicks the invitation link};
    J --> K[User is redirected to the StateForce registration page. Token from the link is captured];
    K --> L[System displays pre-filled registration form];
    subgraph L_Form [Registration Form]
        L1[Email field is read-only]
        L2[User enters First Name, Last Name, and Password]
    end
    L --> M{User completes the form and clicks Create Account};
    M --> N[Frontend sends POST /api/users/register-from-invite with form data and token];
    N --> O{Backend Processing};
    subgraph O_Backend [Backend]
        O1[Find invite record using the token. Verify token validity]
        O2[Validate user input like password strength]
        O3[Create a new record in the users table and set confirmed to true]
        O4[Create a record in the user_institutions table linking the user to the institution and role]
        O5[Update invites table: set status to done and used_at to current time]
        O6[Log the user in]
    end
    O -->|Invalid Token or Expired| P["API responds 404 or 410. UI shows error: Invitation is invalid or expired"];
    P --> Z[End User Flow];
    O -->|Success| Q[API responds 201 Created. UI redirects user to their dashboard];
    Q --> Z;

Loading

---

5. 👤 Managing User Roles and Permissions

This workflow describes how an administrator modifies a user's role within a specific institution, a core feature for managing access control.

Actor: Admin or Superadmin. Preconditions: User to be managed exists. Admin is authenticated and has permissions over the target institution.

flowchart TD
    A[Start] --> B{Admin navigates to 'User Management' and selects a user};
    B --> C{Admin is on the User Profile page};
    C --> D[System displays a list of institutions the user belongs to from the 'user_institutions' table];
    D --> E{Admin finds the institution to modify and clicks 'Edit Role'};
    E --> F["A dropdown or modal appears, showing available 'Role' enum values (e.g., 'Standard', 'Manager', 'Restricted')"];
    F --> G{Admin selects a new role, e.g., changes 'Standard' to 'Manager'};
    G --> H{Admin clicks 'Save Changes'};
    H --> I{Confirmation Prompt};
    I -->|Confirm| J["API Call: PUT /api/user-institutions with payload {user_id, institution_id, new_role}"];
    I -->|Cancel| K[Modal closes. No changes are made.];
    K --> C;
    J --> L{Backend Processing};
    subgraph L_Backend [Backend]
        L1[Authenticate and authorize the Admin]
        L2[Find the record in the 'user_institutions' table where user_id and institution_id match]
        L3[Update the 'role' column with the new role]
        L4[Create an 'audit_logs' entry detailing the role change]
    end
    L -->|Success| M[API responds 200 OK];
    M --> N[UI displays a 'Success' toast and updates the role shown for that institution];
    N --> C;
    L -->|Error: User not found in institution| O[API responds 404 Not Found];
    O --> P["UI displays error: 'User is not a member of this institution.'"];
    P --> C;
    L -->|Error: System/DB| Q[API responds 500 Internal Server Error];
    Q --> R[UI displays a generic error alert];
    R --> H;

Loading

---

6. 🛠️ Managing a Resource

This workflow details how a user adds a new resource (like an ambulance or medical supplies) and updates its operational status.

Actor: Manager or Admin. Preconditions: User is logged in and associated with an institution.

flowchart TD
    subgraph Add New Resource
        A[Start] --> B{User navigates to 'Resource Management'};
        B --> C{User clicks 'Add Resource'};
        C --> D[System displays 'Add Resource' form];
        D --> E{User fills out details};
        subgraph E_Details [Form Fields from 'resources' table]
            E1[Name: 'Ambulance Unit 101']
            E2[Resource Type: Selects 'Ambulance' from 'resource_types']
            E3[Owning Institution: Defaults to user's current institution]
            E4[Status: Sets 'ResourceStatus' to 'Available']
            E5[Total Units: 1]
            E6[Identifier: 'Plate ABC-123']
        end
        E --> F{User clicks 'Save'};
        F --> G[API Call: POST /api/resources];
        G --> H{Success?};
        H -->|Yes| I[New resource appears in the list. Show 'Success' toast.];
        H -->|No: Validation Error| J[Form shows specific field errors. API returns 422.];
        J --> E;
        H -->|No: System Error| K[Show generic error alert. API returns 500.];
        K --> F;
    end

    subgraph Update Resource Status
        I --> L{User selects 'Ambulance Unit 101' from the list and clicks 'Update Status'};
        L --> M[System displays a status update modal with 'ResourceStatus' enum options];
        M --> N{User selects 'Maintenance'};
        N --> O{User clicks 'Confirm'};
        O --> P["API Call: PUT /api/resources/{id}/status with payload {status: 'maintenance'}"];
        P --> Q{Success?};
        Q -->|Yes| R["Resource status is updated in the UI. A record could be added to a 'ResourceMaintenanceLog' if that table existed."];
        Q -->|No| S["Show error alert: 'Failed to update status.'"];
        S --> O;
    end
    R --> B;
    I --> Z[End];

Loading

---

7. 📞 Managing Contacts

This workflow shows how to create a generic contact and then link that contact to one or more institutions or users with a specific type.

Actor: Admin or Manager. Preconditions: User is authenticated.

flowchart TD
    A[Start] --> B{User navigates to 'Directory / Contacts'};

    subgraph Create Generic Contact
        B --> C{User clicks 'Create New Contact'};
        C --> D[System displays 'Create Contact' form];
        D --> E{User enters contact info: Name, Email, Radio Frequency};
        E --> F{User clicks 'Save'};
        F --> G[API Call: POST /api/contacts];
        G --> H{Backend creates record in 'contacts' table};
        H -->|Success| I[New contact is created. UI shows 'Success' toast.];
        H -->|Error| I_Err["UI shows error alert, e.g., 'Email is already in use.'"];
        I_Err --> E;
    end

    I --> J{User wants to link this contact to an institution};
    J --> K{From the contact's page, user clicks 'Link to Institution'};
    K --> L[System displays a search box for institutions and a 'ContactTypes' dropdown];
    L --> M{User searches and selects 'City General Hospital' and selects type 'Emergency'};
    M --> N{User clicks 'Link'};
    N --> O[API Call: POST /api/institution-contacts];
    subgraph O_Backend [Backend]
        O1["Creates a record in the 'institution_contacts' table with {institution_id, contact_id, contact_type}"];
        O2["Uses a composite primary key (institution_id, contact_id, contact_type) to ensure a contact has a unique type per institution."]
    end
    O -->|Success| P[UI updates to show that the contact is now linked to the hospital as an 'Emergency' contact];
    O -->|Error| P_Err["UI shows error alert, e.g., 'This contact is already linked with this type.'"];
    P --> Z[End];
    P --> B;

Loading

---

8. 🚑 Registering and Transferring a Patient

This critical workflow, derived from the CRUM manual, details how a patient is registered in an event and how their transfer to a medical facility is managed and tracked.

Actor: Paramedic, Dispatcher. Preconditions: An active event exists.

flowchart TD
    A["Start: Paramedic is at an event scene"] --> B["Paramedic accesses the event on their mobile device"]
    B --> C["Paramedic clicks 'Add Patient'"]
    C --> D["System displays the 'New Patient' form"]
    subgraph D_Form [Patient Details]
        D1["Name (if known)"]
        D2["Age / Gender"]
        D3["Initial Triage Status: 'Red' from TriageStatus enum"]
        D4["Preliminary Diagnosis: Head trauma"]
    end
    D --> E["Paramedic clicks 'Save Patient'"]
    E --> F["API Call: POST /api/patients with event_id and patient data"]
    F -->|Success| G["Backend creates a record in the patients table and returns new patient_id"]
    G --> H["Paramedic starts recording vitals"]
    H --> I["Periodically, paramedic enters vitals (Heart Rate, BP, etc.)"]
    I --> J["API Call: POST /api/patient-vitals with patient_id and vitals data"]
    J --> K["Backend creates a new record in patient_vitals"]
    K --> H

    G --> L["Dispatcher at CRUM determines patient needs transfer"]
    L --> M["Dispatcher selects the patient and clicks 'Initiate Transfer'"]
    M --> N["System displays the 'Patient Transfer' form"]
    subgraph N_Form [Transfer Details]
        N1["Destination: Dispatcher selects City General Hospital from available medical_centers"]
        N2["Transport Resource: Dispatcher selects Ambulance A-08 from event_resources"]
    end
    N --> O["Dispatcher clicks 'Confirm Transfer'"]
    O --> P["API Call: POST /api/patient-transfers"]
    subgraph P_Backend [Backend]
        P1["Create a record in patient_transfers with status 'in_progress', linking patient, event, ambulance, and destination"]
    end
    P -->|Success| Q["UI updates for all relevant parties: Dispatcher, Ambulance, Hospital"]
    Q --> R["Ambulance arrives at the hospital"]
    R --> S["Receiving hospital user confirms arrival"]
    S --> T["API Call: PUT /api/patient-transfers/{id}/complete"]
    T --> U["Backend updates patient_transfers status to 'done' and arrival_time. Updates patient's current_location_id"]
    U --> V["Patient's resource (Ambulance A-08) status updated back to 'available' in the resources table"]
    V --> Z["End"]

    %% Error Paths
    F --> F_Err["Error: Show 'Failed to register patient'"]
    F_Err --> E
    J --> J_Err["Error: Show 'Failed to save vitals'"]
    J_Err --> I
    P --> P_Err["Error: Show 'Failed to initiate transfer'"]
    P_Err --> O
    T --> T_Err["Error: Show 'Failed to confirm arrival'"]
    T_Err --> S

Loading

---

9. 💬 Logging a Communication Entry

This workflow models the process described in the manual where a dispatcher at the CRUM logs a significant communication (like a radio call for support) related to an event.

Actor: Dispatcher. Preconditions: An active event is being managed.

flowchart TD
    A["Start: Significant communication occurs (e.g., ambulance requesting medical advice)"] --> B["Dispatcher clicks 'Log Communication' on Event Detail page"]
    B --> C["System displays the 'New Communication Log' form"]
    subgraph D_Form ["Log Details"]
        D1["Channel: Selects 'Radio' from CommunicationChannel enum"]
        D2["From: Enters 'Ambulance A-08' or selects from assigned resources"]
        D3["To: Enters 'CRUM Medical Director'"]
        D4["Summary: Ambulance requests advice for patient X with difficulty breathing"]
    end
    C --> E["User clicks 'Save Log'"]
    E --> F["API Call: POST /api/communications-log with event_id and log data"]
    F --> G["Backend Processing"]
    subgraph G_Backend ["Backend Actions"]
        G1["Authenticate user"]
        G2["Validate log data"]
        G3["Create a new record in the communications_log table and link it to the event and user"]
    end
    G -->|Success| H["API responds 201 Created"]
    H --> I["UI shows 'Success' toast and adds entry to event's timeline"]
    I --> C
    G -->|Error| J["API responds with error. UI displays alert: Failed to save log entry"]
    J --> E

    %% Cancellation Path
    C --> D_Cancel["User clicks 'Cancel'"]
    D_Cancel --> Z_Cancel["Form closes without saving"]
    Z_Cancel --> B

Loading

---

10. 📜 Reviewing Audit Logs

This workflow describes how a privileged user can review the audit trail for actions taken within the system, providing accountability and traceability.

Actor: Superadmin, Admin. Preconditions: User is authenticated and has audit-viewing permissions.

flowchart TD
    A[Start] --> B{User navigates to 'System Administration' -> 'Audit Logs'};
    B --> C[System displays the audit log view];
    C --> D{By default, the system shows the most recent logs for all entities};
    D --> E{User wants to filter the logs};
    subgraph E_Filters [Filtering Options]
        E1[Entity Name: Select 'events' from a dropdown of table names]
        E2["Entity ID: Enter a specific event ID, e.g., '12345'"]
        E3["Action: Checkboxes for 'created', 'updated', 'deleted' from 'LogActions' enum"]
        E4[User: Search for a specific user]
        E5[Date Range: Select a start and end date]
    end
    E --> F{User applies the filters};
    F --> G[Frontend sends a GET /api/audit-logs request with filter parameters in the query string];
    G --> H{Backend Processing};
    subgraph H_Backend [Backend]
        H1[Parse query parameters]
        H2[Construct a database query on the 'audit_logs' table using the provided filters]
        H3[Execute the query with pagination]
    end
    H -->|Success| I[API responds 200 OK with a paginated list of matching log entries];
    I --> J[UI clears the existing list and displays the filtered results in a table];
    subgraph J_Table [Results Table]
        J1[Timestamp]
        J2[User]
        J3[Action]
        J4[Entity]
        J5["Details (e.g., a button to view JSON diff)"]
    end
    J --> E;
    H -->|Error| K[API responds with 500/400 error];
    K --> L["UI displays an error message above the filter panel: 'Could not retrieve logs.'"];
    L --> D;
    J --> Z[End];

Loading

---

📅 Create Calendar Event

Description:

This flow demonstrates how to schedule a new calendar entry for an institution or team.

sequenceDiagram
    actor Manager as Calendar Scheduler
    Manager->>UI: Open "Create Calendar Event" form
    UI->>Manager: Display form fields (title, description, date, recurrence)
    Manager->>API: Submit calendar event details
    API->>DB: Create record in `calendar_entries` table
    API->>DB: Link entry to institution (calendar_entries_institutions)
    API->>UI: Return confirmation and event ID
    Manager->>UI: View calendar entry

Loading

---

📎 Attach File

Description:

This flow explains how a user uploads a file and links it to an event, institution, or resource.

sequenceDiagram
    actor User as File Uploader
    User->>UI: Open "Attach File" form
    UI->>User: Display file upload interface
    User->>API: Upload file (metadata + content)
    API->>DB: Create record in `attachments` table
    API->>DB: Link file to entity (event_attachments, institution_attachments, etc.)
    API->>UI: Return confirmation and file URL
    User->>UI: View attached file details

Loading

---

🛠 Notes

• Real-Time Updates: All flows leverage real-time updates with Hotwire (Turbo Streams) to reflect changes instantly.
• Error Handling: Ensure each flow includes fallback mechanisms for common errors, such as invalid inputs or network issues.
• Data Privacy: Visibility settings (public, private, restricted) control access to sensitive data, ensuring compliance with operational requirements.

---

Related Pages

• User Flows
• System Architecture
• Database Schema Overview
• Testing Guide