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

Central Coordination (CRUM): Users with roles such as Dispatcher or Manager, operating within a coordination center (coordination_center), orchestrate emergency responses.
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.
Communication Logging: The communications_log table maintains auditable records of significant communications (e.g., radio, phone) related to events.
Resource Management: The resources table tracks resource availability (status, available_units) for dispatchers making assignment decisions.

1. 🏢 Registering a New Institution

Overview

Authorized users, such as Superadmins or Admins, can add institutions to the system, including hospitals, rescue bases, coordination centers, and other emergency facilities. This workflow ensures that institutions are properly registered and linked to the system for resource management and operational coordination.

Detailed Description

This flow describes the step-by-step process for registering a new institution, including adding its details (e.g., name, location, sector type, parent institution), handling validations, and processing the creation in the backend. It also covers error scenarios, cancellation options, and system feedback.

Actor: Superadmin or Admin
Preconditions:

User is authenticated and authorized to manage institutions.
User has access to the Institutions Dashboard.

Postconditions:

A new institution is successfully added to the system and appears in the Institutions Dashboard.
Audit logs are created to record the action for accountability.

Key Steps in the Workflow

1. Accessing the Institutions Dashboard

The user begins by navigating to the Institutions Dashboard. This section provides a list of all active institutions and options for managing them.

2. Opening the Institution Registration Form

The user clicks the "Add New Institution" button, which opens the Create Institution form. This intuitive form includes essential fields, such as:

Institution Name: A unique identifier for the institution.
Sector Type: Public or private.
Institution Type: Medical center, rescue base, coordination center, etc.
Location ID: Selected from a map or list to ensure geographical accuracy.
Parent Institution ID: Optional, for hierarchical relationships (e.g., sub-centers).

3. Filling Out the Form

The user fills out the required fields. The system performs client-side validation to check for missing or invalid inputs (e.g., required fields like Name are empty).

4. Submitting the Form

Once the form is complete, the user clicks "Save". The system validates the data, displays a loading spinner, and disables the "Save" button to prevent duplicate submissions.

5. Backend Processing

The form data is sent to the backend via an API call (POST /api/institutions). The backend performs the following actions:

Authentication & Authorization: Ensures the user has the correct permissions.
Data Validation: Checks for unique institution names and valid location IDs.
Database Operations: Creates a record in the institutions table and logs the action in the audit_logs table.

6. Handling Responses

Success: The system responds with 201 Created, displays a success toast notification, and closes the form. The new institution appears in the dashboard.
Validation Errors: If validation fails (e.g., duplicate name), the system responds with 422 Unprocessable Entity. The form highlights the errors for correction.
System Errors: If a server/database issue occurs, the system responds with 500 Internal Server Error and displays a generic error alert.

7. Cancellation

At any point, the user can cancel the process by clicking "Cancel", returning to the dashboard without saving.

Improved Workflow Diagram

flowchart TD
    %% Start the Process
    A[Start: User accesses the Institutions Dashboard] --> B[User clicks 'Add New Institution']
    B --> C[System displays the 'Create Institution' form]

    %% Filling Out the Form
    C --> D[User fills in Institution Details]
    subgraph FormFields [Form Fields]
        direction LR
        D1[Institution Name]
        D2[Sector Type: Public/Private]
        D3[Institution Type: Medical Center/Rescue Base/etc.]
        D4[Location ID: Selected from map/list]
        D5[Parent Institution ID Optional]
    end
    D --> E[User clicks 'Save']

    %% Client-Side Validation
    E --> F[Client-Side Validation]
    F -->|Invalid Input| G[Highlight errors on the form, e.g., 'Name is required']
    G --> D
    F -->|Valid Input| H[Display loading spinner and disable 'Save' button]

    %% Backend Processing
    H --> I[API Call: POST /api/institutions]
    I --> J[Backend Processing]
    subgraph BackendActions [Backend Actions]
        J1[Authenticate & Authorize User]
        J2[Validate Data: Check unique name, valid location ID]
        J3[Create record in 'institutions' table]
        J4[Create record in 'audit_logs' table]
    end

    %% Handling Backend Responses
    J -->|Validation Errors| K[API responds with 422 Unprocessable Entity]
    K --> L[Display error messages on the form]
    L --> D
    J -->|System Errors| M[API responds with 500 Internal Server Error]
    M --> N[Display generic error alert: 'Unexpected error occurred. Please try again']
    N --> E
    J -->|Success| O[API responds with 201 Created]
    O --> P[Display 'Success' toast notification]
    P --> Q[Form closes and redirects to dashboard]
    Q --> R[New Institution appears in Institutions Dashboard]
    R --> Z[End]

    %% Cancellation Path
    C --> Cancel[User clicks 'Cancel']
    Cancel --> Return[Form closes without saving]
    Return --> A

Additional Information for Developers

Audit Logging

Every action (e.g., creating a new institution) is logged in the audit_logs table. This ensures accountability and traceability for all changes made by administrators.

Validation Rules

Name: Must be unique across all institutions.
Location ID: Must correspond to a valid entry in the locations table.
Sector Type: Restricted to predefined options (Public, Private).

Error Handling

Client-Side Validation: Prevents submission of incomplete forms.
Server-Side Validation: Ensures database integrity.
Generic System Errors: Provides fallback messaging to guide the user.

Future Enhancements

Bulk Upload: Allow admins to upload CSV files to register multiple institutions at once.
Geolocation Integration: Improve location accuracy by integrating maps with geocoding.

Key Takeaways

User-Friendly Interface: Simplified form design ensures a seamless experience.
Robust Validation: Protects data integrity and prevents errors.
Accountability: Audit logging provides traceability for all administrative actions.

This workflow ensures that institutions are registered efficiently and accurately, forming the backbone of the StateForce platform's emergency resource management system.

2. 🚨 Creating a New Event

Overview

Event creation is a critical workflow in the StateForce system, allowing dispatchers or managers to log emergency reports (e.g., phone calls, radio communications) into the platform. This process ensures that emergencies are accurately recorded, prioritized, and tracked in real-time, forming the foundation for resource allocation and response coordination.

Detailed Description

This flow illustrates the process for creating a new event, from receiving the external report to logging it in the system. It covers the steps involved, validations, backend processing, and error handling. The goal is to ensure that emergencies are logged efficiently with all necessary details.

Actor: Dispatcher or Manager

Preconditions:

User is authenticated and authorized to create events.
The dispatcher has received an incoming emergency report.

Postconditions:

A new event is successfully created and visible in the Event Dashboard.
Audit logs and communication logs are recorded for traceability.

Detailed Workflow

1. Receiving the Emergency Report

The dispatcher receives an external report, such as a phone call or radio communication, regarding an emergency incident. They log into the system and navigate to the Event Dashboard.

2. Initiating Event Creation

The dispatcher clicks the "Create New Event" button, which opens the Create Event form. This form is designed to capture all essential details of the emergency.

3. Filling Out the Event Form

The form includes the following fields:

Incident Type: Selects from predefined categories (e.g., Traffic Accident, Fire, Medical Emergency).
Location: Specifies the location of the incident using a map or text input.
Priority: Sets the urgency level (e.g., Low, Medium, High).
Reported By: Indicates the source of the report (e.g., Civilian, Police Officer).
Description: Provides additional details about the incident.

4. Submitting the Event

Once the form is complete, the dispatcher clicks "Create Event". The system performs client-side validation to ensure all required fields are filled and correct.

5. Backend Processing

The validated data is sent to the backend via an API call (POST /api/events). The backend performs the following actions:

Authentication & Authorization: Ensures the user has permissions to create the event.
Data Validation: Checks for valid inputs and consistency (e.g., location exists).
Database Operations: Creates a new record in the events table.
Log Updates: Records the action in both the communications_log and audit_logs tables for traceability.

6. Handling Responses

Success: The backend responds with 201 Created. The system redirects to the Event Details page and displays a success notification.
Validation Errors: If validation fails (e.g., empty required fields), the system responds with 422 Unprocessable Entity. The form highlights the errors for user correction.
System Errors: If a server/database issue occurs, the system responds with 500 Internal Server Error and displays a generic error alert.

7. Cancellation

At any point, the dispatcher can cancel the process, returning to the dashboard without saving.

Improved Workflow Diagram

flowchart TD
    %% Start the Process
    A[Start: Dispatcher receives emergency report] --> B[Dispatcher navigates to Event Dashboard]
    B --> C[Click 'Create New Event']
    C --> D[System displays 'Create Event' form]

    %% Filling Out the Form
    D --> E[Dispatcher fills in event details]
    subgraph EventFields [Event Details]
        direction LR
        E1[Incident Type: Select from predefined categories]
        E2[Location: Specify using map or text input]
        E3[Priority: Set urgency level]
        E4[Reported By: Source of the report]
        E5[Description: Additional details about the incident]
    end
    E --> F[Click 'Create Event']

    %% Client-Side Validation
    F --> G[Client-Side Validation]
    G -->|Invalid Input| H[Form highlights errors, e.g., 'Location is required']
    H --> E
    G -->|Valid Input| I[Display loading spinner and disable 'Create Event' button]

    %% Backend Processing
    I --> J[API Call: POST /api/events]
    J --> K[Backend Processing]
    subgraph BackendActions [Backend Actions]
        K1[Authenticate & Authorize User]
        K2[Validate Data: Check inputs and consistency]
        K3[Create record in events table]
        K4[Log action in communications_log and audit_logs]
    end

    %% Handling Backend Responses
    K -->|Validation Errors| L[API responds with 422 Unprocessable Entity]
    L --> M[Display error messages on form]
    M --> E
    K -->|System Errors| N[API responds with 500 Internal Server Error]
    N --> O[Display generic error alert: 'Unexpected error occurred']
    O --> F
    K -->|Success| P[API responds with 201 Created]
    P --> Q[Redirect to Event Details page]
    Q --> R[Event is visible in Event Dashboard]
    R --> Z[End]

    %% Cancellation Path
    D --> Cancel[Dispatcher clicks 'Cancel']
    Cancel --> Return[Form closes without saving]
    Return --> B

Developer Notes

Validation Rules

Incident Type: Must be selected from predefined categories.
Location: Must correspond to a valid entry in the locations table.
Priority: Restricted to predefined levels (Low, Medium, High).

Audit Logging

Every action is logged in the audit_logs table for accountability. Communication details may also be logged in the communications_log table, depending on the event's context.

Error Handling

Client-Side Validation: Prevents submission of incomplete or invalid forms.
Server-Side Validation: Ensures database integrity and consistency.
Fallback Messaging: Guides users in case of unexpected errors.

Future Enhancements

Auto-Fill Location: Integrate with geolocation services to auto-detect incident locations.
Bulk Event Creation: Allow dispatchers to batch-create events for large-scale emergencies.
Priority Analytics: Provide insights into priority trends for better resource allocation.

Key Takeaways

Streamlined Workflow: The Create Event process is intuitive and efficient, ensuring that emergencies are logged accurately.
Robust Validation: Protects against errors and ensures data quality.
Accountability: Audit logs and communication logs provide a full trace of actions taken.

This workflow is essential for ensuring that emergency incidents are logged promptly and correctly, forming the foundation for resource allocation and response coordination.

3. 🚒 Managing an Active Event

Overview

Managing an active event is a critical workflow within StateForce, enabling dispatchers or managers to coordinate emergency responses effectively. This process includes assigning institutions and resources to the event, as well as updating the event's status to reflect its progression. These actions are central to the role of the Central Coordination Center (CRUM) in orchestrating emergency management.

Detailed Description

This workflow details the primary actions a dispatcher can take when managing an active or pending event. It covers assigning institutions (e.g., hospitals, rescue bases), allocating resources (e.g., ambulances, medical supplies), and updating the event's status. The workflow ensures all actions are logged for accountability and traceability.

Actor: Dispatcher or Manager

Preconditions:

An event exists with status: 'pending' or 'active'.
User is authenticated and authorized to manage events.

Postconditions:

Institutions and resources are successfully assigned to the event.
The event's status is updated as needed.
Audit logs are created for all actions.

Key Workflow Actions

1. Assign Institutions

Dispatchers can assign institutions such as hospitals or rescue bases to an event. This ensures the necessary facilities are aware of the emergency and can prepare to respond.

Steps:

Initiate Assignment: The dispatcher clicks "Assign Institution" on the Event Detail page.
Select Institutions: The system displays a list of available institutions, filtered by proximity or specialty. The dispatcher selects one or more institutions.
Confirm Assignment: The dispatcher clicks "Confirm Assignment" to finalize the selection.
Backend Processing: The system creates records in the event_institutions table and logs the action in audit_logs.
Feedback: The UI updates to show the assigned institutions, and the dispatcher receives a success notification.

Error Handling:

Validation Errors: If the institution is invalid or unavailable, the system displays an error alert.
System Errors: If the assignment fails due to backend issues, a generic error message is displayed.

2. Assign Resources

Resources such as ambulances, medical equipment, or personnel can be allocated to the event to ensure an effective response.

Steps:

Initiate Resource Assignment: The dispatcher clicks "Assign Resource" on the Event Detail page.
Select Resources: The system displays a list of available resources, filterable by type and owning institution. The dispatcher selects the required resource(s) and specifies quantities.
Confirm Assignment: The dispatcher clicks "Confirm Assignment" to finalize the selection.
Backend Processing: The system creates records in the event_resources table, updates the resources table (e.g., reduces available units), and logs the action in audit_logs.
Feedback: The UI updates to show the assigned resources, and the dispatcher receives a success notification.

Error Handling:

Validation Errors: If the resource is invalid or unavailable, the system displays an error alert.
System Errors: If the assignment fails due to backend issues, a generic error message is displayed.

3. Update Event Status

The event's status can be updated to reflect changes in its progression, such as transitioning from "Active" to "Resolved" or "Closed".

Steps:

Initiate Status Update: The dispatcher clicks "Update Status" on the Event Detail page.
Select Status: The system displays a dropdown with valid status options (Active, Resolved, Closed). The dispatcher selects the desired status.
Confirm Update: The dispatcher clicks "Save" to finalize the update.
Backend Processing: The system updates the status field in the events table and logs the action in audit_logs.
Feedback: The UI updates to show the new status badge, and the dispatcher receives a success notification.

Error Handling:

Validation Errors: If the status is invalid, the system displays an error alert.
System Errors: If the update fails due to backend issues, a generic error message is displayed.

Improved Workflow Diagram

flowchart TD
    %% Start the Process
    A[Start: Dispatcher is on the Event Detail page] --> B[Decide Action]

    %% Assign Institutions
    B --> B1[Assign Institutions]
    B1 --> C1[Click 'Assign Institution']
    C1 --> D1[System displays list of available institutions]
    D1 --> E1[Select institutions 'e.g., City General Hospital, Rescue Unit 5']
    E1 --> F1[Click 'Confirm Assignment']
    F1 --> G1[API Call: POST /api/events/'id'/institutions]
    G1 --> H1[Backend Processing]
    subgraph BackendInstitutions [Institution Backend Actions]
        H1a[Create records in event_institutions table]
        H1b[Log action in audit_logs]
        H1c[Send notifications to institutions future enhancement]
    end
    H1 --> I1[API responds 200 OK]
    I1 --> J1[UI updates to show assigned institutions]
    J1 --> B

    %% Assign Resources
    B --> B2[Assign Resources]
    B2 --> C2[Click 'Assign Resource']
    C2 --> D2[System displays list of available resources]
    D2 --> E2[Select resources 'e.g., Ambulance A-08, specify quantity 1']
    E2 --> F2[Click 'Confirm Assignment']
    F2 --> G2[API Call: POST /api/events/'id'/resources]
    G2 --> H2[Backend Processing]
    subgraph BackendResources [Resource Backend Actions]
        H2a[Create records in event_resources table]
        H2b[Update resources table 'reduce available units, set status to assigned']
        H2c[Log action in audit_logs]
    end
    H2 --> I2[API responds 200 OK]
    I2 --> J2[UI updates to show assigned resources]
    J2 --> B

    %% Update Event Status
    B --> B3[Update Event Status]
    B3 --> C3[Click 'Update Status']
    C3 --> D3[System displays dropdown with valid status options]
    D3 --> E3[Select status 'e.g., Resolved']
    E3 --> F3[Click 'Save']
    F3 --> G3[API Call: PUT /api/events/'id'/status]
    G3 --> H3[Backend Processing]
    subgraph BackendStatus [Status Backend Actions]
        H3a[Update status field in events table]
        H3b[Log action in audit_logs]
    end
    H3 --> I3[API responds 200 OK]
    I3 --> J3[UI updates to show new status badge]
    J3 --> Z[End]

    %% Error Handling
    G1 --> G1_Error[Error: Failed to assign institutions]
    G1_Error --> B
    G2 --> G2_Error[Error: Failed to assign resources]
    G2_Error --> B
    G3 --> G3_Error[Error: Failed to update status]
    G3_Error --> B

Developer Notes

Audit Logging

All actions (assigning institutions, assigning resources, updating status) are logged in the audit_logs table to provide accountability and traceability.

Validation Rules

Institution Availability: Institutions must be active and not already fully assigned to other events.
Resource Availability: Resources must have remaining units available and not be marked as "inactive."
Status Options: Status transitions must follow predefined rules (e.g., Active → Resolved → Closed).

Error Handling

Frontend Validation: Prevents submission of invalid or incomplete actions.
Backend Validation: Ensures consistency and adherence to database rules.
Fallback Messaging: Provides clear guidance in case of errors.

Future Enhancements

Notifications: Automatically notify assigned institutions and resource owners about their roles in the event.
Resource Analytics: Enable tracking of resource utilization trends for better planning.
Priority-Based Sorting: Display institutions and resources sorted by relevance to the event's priority.

Key Takeaways

Efficient Coordination: The workflow ensures seamless management of institutions and resources for emergency events.
Robust Validation: Protects against errors and ensures data integrity.
Accountability: Audit logging provides traceability for every action taken.

This workflow enables dispatchers to coordinate emergency responses effectively, ensuring resources are allocated efficiently and events progress smoothly.

4. 📧 Inviting and Onboarding a New User

Overview

This workflow explains the process by which an admin invites a new user to join the StateForce platform and how the invited user completes their onboarding by accepting the invitation and creating their account. It ensures secure user registration while maintaining role-based access control and accountability.

Detailed Description

The invitation and onboarding workflow consists of two parts:

Admin's Flow: The admin sends an invitation to a new user via email, specifying their role and primary institution.
New User's Flow: The invited user accepts the invitation, registers on the platform, and is linked to their assigned institution and role.

Actors:

Admin: Responsible for initiating the user invitation process.
New User: Completes registration and onboarding after receiving the invitation.

Preconditions:

Admin is logged into the platform and authorized to invite users.
New user receives the invitation email successfully.

Postconditions:

The new user is registered on the platform with the specified role and institution.
All actions are logged for traceability.

Key Workflow Actions

1. Admin's Flow: Sending the Invitation

The admin invites a new user by providing their email, role, and primary institution through the platform's User Management dashboard.

Steps:

Access User Management: Admin navigates to the User Management dashboard.
Open Invite Form: Admin clicks "Invite User" to open the Invite User form.
Fill Form Details: Admin enters the user's email, selects their role (e.g., Standard, Manager, Admin), and assigns their primary institution.
Send Invitation: Admin clicks "Send Invite." The system performs client-side validation and sends the data to the backend.
Backend Processing: The backend validates the data, generates a unique token, creates a record in the invites table, and sends an invitation email containing the token link.
Feedback:
- Success: The system displays a confirmation message ("Invite Sent") and resets the form.
- Error: If the invitation fails, an error message is displayed, and the admin can retry or correct the form.

2. New User's Flow: Accepting the Invitation

The invited user completes the onboarding process by clicking the invitation link and registering their account.

Steps:

Receive Invitation Email: The user receives an email containing the invitation link.
Open Registration Page: By clicking the link, the user is redirected to the platform's registration page, where the token is captured.
Fill Registration Form: The system pre-fills the user's email field. The user enters their first name, last name, and password.
Submit Registration: User clicks "Create Account," and the frontend sends the form data and token to the backend.
Backend Processing:
- Verify the token's validity (ensure it hasn't expired or been used).
- Validate user inputs (e.g., password strength).
- Create a new user record in the users table and confirm their account.
- Link the user to their assigned institution and role in the user_institutions table.
- Update the invites table to mark the invitation as completed.
Feedback:
- Success: The system logs the user in and redirects them to their dashboard.
- Error: If the token is invalid or expired, the system displays an error message.

Improved Workflow Diagram

flowchart TD
    %% Admin's Flow: Sending the Invitation
    A[Start: Admin is on User Management dashboard] --> B[Click 'Invite User']
    B --> C[System displays 'Invite User' form]
    C --> D[Admin fills in details: email, role, and primary institution]
    D --> E[Click 'Send Invite']
    E --> F[API Call: POST /api/invites]
    F --> G[Backend Processing]
    subgraph BackendActions [Backend Actions]
        G1[Validate data]
        G2[Generate unique token with expiration]
        G3[Create record in invites table]
        G4[Send invitation email with token link]
    end
    G -->|Success| H[UI shows 'Invite Sent' confirmation]
    H --> A
    G -->|Error| I[UI displays alert: Failed to send invite]
    I --> D

    %% New User's Flow: Accepting the Invitation
    J[User receives invitation email] --> K[Click invitation link]
    K --> L[Redirect to registration page. Token is captured]
    L --> M[System displays pre-filled registration form]
    subgraph RegistrationForm [Registration Form]
        M1[Read-only email field]
        M2[User enters First Name, Last Name, and Password]
    end
    M --> N[Click 'Create Account']
    N --> O[API Call: POST /api/users/register-from-invite]
    O --> P[Backend Processing]
    subgraph UserBackendActions [Backend Actions]
        P1[Verify token validity]
        P2[Validate user input 'e.g., password strength']
        P3[Create user record in users table]
        P4[Link user to institution and role in user_institutions table]
        P5[Update invites table: status set to done]
        P6[Log user in]
    end
    P -->|Success| Q[UI redirects user to dashboard]
    Q --> Z[End]
    P -->|Error: Invalid or Expired Token| R[UI displays error: Invitation is invalid or expired]
    R --> Z

Developer Notes

Validation Rules

Email: Must be unique and properly formatted.
Role: Restricted to predefined enums (Standard, Manager, Admin).
Institution: Must be active and valid in the institutions table.
Token: Expiration and usage are verified during backend processing.

Audit Logging

All actions are logged for accountability:

Invitation creation is logged in the audit_logs table.
User registration is recorded with timestamps for traceability.

Error Handling

Frontend Validation: Prevents submission of incomplete forms or improper data.
Backend Validation: Ensures token validity and consistency in database operations.
Fallback Messaging: Provides clear instructions in case of errors.

Future Enhancements

Bulk Invitations: Allow admins to invite multiple users at once via CSV upload.
Token Resend Option: Enable admins to resend invitations for expired or unused tokens.
Invitation Analytics: Track invitation acceptance rates and statuses.

Key Takeaways

Streamlined Process: The invitation and onboarding workflow ensures seamless user registration with role-based access control.
Robust Validation: Protects against errors and ensures data integrity.
Accountability: Audit logs provide traceability for all administrative actions.

This workflow is essential for onboarding new users efficiently and securely, supporting the scalability and operational needs of the StateForce platform.

5. 👤 Managing User Roles and Permissions

Overview

Managing user roles and permissions is a core feature of the StateForce platform that enables administrators to control access to resources and functionalities within specific institutions. This ensures that users have the appropriate level of access and responsibilities based on their role within the organization.

Detailed Description

This workflow describes how an administrator can update a user's role within an institution. It covers the steps from accessing the user's profile to confirming the role change, handling errors, and ensuring accountability through audit logs.

Actors:

Admin: Responsible for managing user roles within institutions.
Superadmin: Has broader permissions across multiple institutions.

Preconditions:

The user to be managed exists in the system.
Admin is authenticated and has permissions over the target institution.

Postconditions:

The user's role is successfully updated within the specified institution.
Audit logs record the role change for accountability.

Key Workflow Actions

1. Access User Management

The admin navigates to the User Management section of the platform to manage roles and permissions.

Steps:

Select User: The admin selects the user whose role needs modification from the list of users.
View User Profile: The platform displays the user's profile page, including a list of institutions the user is associated with.

2. Edit User Role

The admin identifies the target institution and initiates the role change process.

Steps:

Select Institution: The admin clicks "Edit Role" for the specific institution from the list.
Choose Role: The system displays a dropdown or modal with available role options (Standard, Manager, Admin, etc.).
Confirm Role Selection: The admin selects the new role for the user.

3. Save Changes

The admin finalizes the role change by saving the updates.

Steps:

Confirmation Prompt: The system asks for confirmation to proceed with the role change.
API Call: Upon confirmation, the frontend sends a PUT /api/user-institutions request with the user ID, institution ID, and new role.
Backend Processing: The backend validates the request, updates the user's role in the database, and logs the action in the audit_logs table.

4. Handling Responses

The system processes the admin's request and provides feedback.

Steps:

Success: The backend responds with 200 OK, the UI updates to reflect the new role, and a success notification is displayed.
Errors:
- Validation Error: If the user is not associated with the institution, the system returns a 404 Not Found error.
- System Error: If the database operation fails, the system returns a 500 Internal Server Error.

Improved Workflow Diagram

flowchart TD
    %% Start the Process
    A[Start: Admin navigates to User Management] --> B[Select user from the list]
    B --> C[View User Profile]
    C --> D[Display list of institutions the user belongs to]
    D --> E[Click Edit Role for the target institution]
    E --> F[Show dropdown/modal with available roles]
    F --> G[Select new role, e.g., Standard to Manager]
    G --> H[Click Save Changes]
    H --> I[Show confirmation prompt]

    %% Confirm or Cancel
    I --> J[Confirm changes]
    I --> K[Cancel changes]
    K --> C

    %% API Call and Backend Processing
    J --> L[API Call: PUT /api/user-institutions]
    L --> M[Backend Processing]
    subgraph BackendActions [Backend Actions]
        M1[Authenticate and authorize admin]
        M2[Validate user and institution linkage]
        M3[Update role in user_institutions table]
        M4[Create audit log entry for role change]
    end

    %% Handle Responses
    M --> N[API responds 200 OK]
    N --> O[UI updates role and shows success notification]
    O --> C

    M --> P[API responds 404 Not Found]
    P --> Q[Show error: User not found in institution]
    Q --> C

    M --> R[API responds 500 Internal Server Error]
    R --> S[Show generic error alert]
    S --> H

Developer Notes

Validation Rules

User-Institution Linkage: Ensure the user exists within the specified institution before updating their role.
Role Options: Restricted to predefined enums (Standard, Manager, Admin).
Authorization: Admin must have permission to manage roles within the institution.

Audit Logging

Every role change is logged in the audit_logs table, including details such as:

User ID: The user whose role was modified.
Institution ID: The institution where the role change occurred.
Changed By: The admin who performed the action.
Timestamp: When the change occurred.

Error Handling

Frontend Validation: Prevents submission of incomplete or invalid forms.
Backend Validation: Ensures consistency and adherence to database rules.
Fallback Messaging: Provides clear guidance in case of errors.

Future Enhancements

Bulk Role Updates: Allow admins to update roles for multiple users at once.
Role History: Provide a log of all role changes for each user.
Role Analytics: Enable tracking of role assignments across institutions.

Key Takeaways

Centralized Control: Admins can efficiently manage user roles across multiple institutions.
Robust Validation: Protects against errors and ensures data integrity.
Accountability: Audit logs provide traceability for all role changes.

This workflow ensures that user roles are updated securely and accurately, supporting the platform's role-based access control and operational needs.

7. 📞 Managing Contacts

Overview

Managing contacts is a crucial feature within the StateForce platform that allows admins and managers to create generic contacts and associate them with institutions or users using specific types (e.g., Emergency, Administrative). This workflow ensures a centralized directory of contacts, enabling effective communication and coordination during emergencies.

Detailed Description

The workflow consists of two main actions:

Creating a Generic Contact: Adding a contact's essential details (e.g., name, email, radio frequency) to the system.
Linking Contacts to Institutions: Associating contacts with institutions or users and assigning specific types.

Actors:

Admin: Responsible for managing contacts across multiple institutions.
Manager: Typically manages contacts within their assigned institution.

Preconditions:

User is authenticated and authorized to manage contacts.
Institutions or users exist in the system for linking purposes.

Postconditions:

Contacts are stored in the system with their essential details.
Contacts are successfully linked to institutions or users with defined types.

Key Workflow Actions

1. Creating a Generic Contact

Admins or managers can add new contacts to the directory by entering their details into the system.

Steps:

Navigate to Contacts Directory: User opens the Directory / Contacts section from the dashboard.
Open Create Contact Form: User clicks "Create New Contact," and the system displays the Create Contact form.
Fill Contact Details: User enters the following information:
- Name: Contact's full name.
- Email: Unique identifier for the contact.
- Radio Frequency: Communication frequency for emergency services (optional).
Submit Contact: User clicks "Save," triggering client-side validation.
Backend Processing: The validated data is sent to the backend (POST /api/contacts), which performs:
- Authentication & Authorization: Ensures the user is authorized to create contacts.
- Data Validation: Checks for unique email addresses and valid inputs.
- Database Operations: Inserts a new record into the contacts table.
Feedback:
- Success: The new contact is created, and the UI displays a success toast notification.
- Validation Error: If the email is already in use, the form highlights the error for correction.
- System Error: For backend issues, a generic error alert is displayed.

2. Linking Contacts to Institutions

Contacts can be associated with one or more institutions, defining their role or type within the institution.

Steps:

Open Contact Profile: User navigates to the contact's profile page.
Initiate Linking: User clicks "Link to Institution" from the contact's page.
Search Institution: System displays:
- Search Box: Allows the user to find institutions by name or proximity.
- Contact Type Dropdown: Enables selection of predefined types (e.g., Emergency, Administrative).
Select Institution and Type: User selects an institution (e.g., City General Hospital) and assigns a type (e.g., Emergency).
Submit Link: User clicks "Link," and the frontend sends a POST /api/institution-contacts request.
Backend Processing:
- Validate Inputs: Ensures the institution and contact exist in the system.
- Create Link: Inserts a record into the institution_contacts table using a composite primary key (institution_id, contact_id, contact_type).
Feedback:
- Success: The contact is linked to the institution, and the UI updates to reflect the association.
- Error: If the contact is already linked with the selected type, an error alert is displayed.

Improved Workflow Diagram

flowchart TD
    %% Creating a Generic Contact
    A[Start: User navigates to Contacts Directory] --> B[Click Create New Contact]
    B --> C[System displays Create Contact form]
    C --> D[User enters contact details]
    subgraph ContactDetails [Contact Form Fields]
        direction LR
        D1[Name: Contact's full name]
        D2[Email: Unique identifier]
        D3[Radio Frequency: Optional communication frequency]
    end
    D --> E[Click Save]
    E --> F[API Call: POST /api/contacts]
    F --> G[Backend Processing]
    subgraph BackendActions [Backend Actions]
        G1[Authenticate and authorize user]
        G2[Validate contact details]
        G3[Insert record into contacts table]
    end
    G --> H[API responds with success]
    H --> I[Contact appears in directory, show success notification]
    G --> J[API responds with validation error]
    J --> K[Highlight errors on form]
    K --> D
    G --> L[API responds with system error]
    L --> M[Show generic error alert]
    M --> E

    %% Linking Contacts to Institutions
    I --> N[Open contact profile]
    N --> O[Click Link to Institution]
    O --> P[System displays institution search and type selection]
    subgraph LinkingDetails [Linking Details]
        direction LR
        P1[Search Institution by name/proximity]
        P2[Select Contact Type from dropdown]
    end
    P --> Q[Select institution and type]
    Q --> R[Click Link]
    R --> S[API Call: POST /api/institution-contacts]
    S --> T[Backend Processing]
    subgraph LinkingBackendActions [Backend Actions]
        T1[Validate institution and contact exists]
        T2[Insert record into institution_contacts table]
    end
    T --> U[API responds with success]
    U --> V[UI updates to show contact linked to institution]
    T --> W[API responds with error]
    W --> X[Show error alert: Contact already linked with this type]
    X --> R
    V --> Z[End]

Developer Notes

Validation Rules

Email: Must be unique across all contacts in the system.
Institution: Must exist and be active in the institutions table.
Contact Type: Restricted to predefined enums (e.g., Emergency, Administrative).

Audit Logging

Every action (creating a contact, linking to an institution) is logged for accountability, including:

Contact Details: The contact being created or modified.
Institution ID: The institution linked to the contact.
Changed By: The user who performed the action.
Timestamp: When the action occurred.

Error Handling

Frontend Validation: Prevents submission of invalid or incomplete forms.
Backend Validation: Ensures consistency and adherence to database rules.
Fallback Messaging: Guides users in case of errors.

Future Enhancements

Bulk Linking: Allow users to link contacts to multiple institutions simultaneously.
Contact Analytics: Provide insights into contact associations and usage trends.
Role-Based Filtering: Enable filtering of contacts based on their assigned type.

Key Takeaways

Streamlined Workflow: Simplifies the process of managing and associating contacts.
Robust Validation: Ensures data accuracy and integrity.
Accountability: Audit logs provide traceability for all contact-related actions.

This workflow ensures that contacts are created and linked efficiently, enabling seamless communication and coordination during emergencies.

8. 🚑 Registering and Transferring a Patient

Overview

This workflow is a critical feature of the StateForce platform, derived from the CRUM manual, that details how paramedics register patients at an event scene and how dispatchers manage their transfer to medical facilities. It ensures streamlined tracking of patients throughout their emergency journey, providing accountability, efficient resource allocation, and real-time updates to all stakeholders.

Detailed Description

The workflow is divided into two main actions:

Registering a Patient: Paramedics at the event scene record patient details and vitals to create a new entry in the system.
Transferring a Patient: Dispatchers initiate and manage the patient's transfer to a medical facility, tracking the process until completion.

Actors:

Paramedic: Responsible for registering patients and recording vitals at the event scene.
Dispatcher: Manages patient transfers and resource allocation from the CRUM coordination center.

Preconditions:

An active event exists.
Paramedics and dispatchers have access to the StateForce platform.

Postconditions:

The patient is registered and their details are tracked in the system.
The patient's transfer is successfully completed, with updated records for resource usage and location.

Key Workflow Actions

1. Registering a Patient

Paramedics record patient details and periodically update their vitals at the event scene.

Steps:

Access Event: Paramedic logs into the mobile platform and accesses the active event.
Open Patient Form: Paramedic clicks "Add Patient," and the system displays the New Patient form.
Enter Patient Details: Paramedic fills out essential fields, such as:
- Name: If known.
- Age / Gender: Basic demographic information.
- Initial Triage Status: Emergency severity level (e.g., Red, Yellow, Green).
- Preliminary Diagnosis: Initial observations (e.g., Head trauma).
Submit Form: Paramedic clicks "Save Patient," triggering client-side validation.
Backend Processing: The validated data is sent to the backend (POST /api/patients), which performs:
- Authentication & Authorization: Ensures the user is authorized to create patient records.
- Database Operations: Creates a new record in the patients table and returns the patient ID.
Feedback:
- Success: The patient record is created, and the paramedic can begin recording vitals.
- Error: Validation or system errors are displayed, allowing the paramedic to retry.

Recording Vitals:

Enter Vitals: Paramedic periodically records measurements (e.g., Heart Rate, Blood Pressure) via the mobile platform.
Submit Vitals: Each entry triggers an API call (POST /api/patient-vitals), updating the patient_vitals table.
Feedback:
- Success: Vitals are saved and displayed in the patient's profile.
- Error: System issues or invalid inputs prompt an error alert.

2. Transferring a Patient

Dispatchers ensure the patient is transported to the appropriate medical facility using available resources.

Steps:

Determine Transfer Need: Dispatcher reviews patient details and identifies the need for transfer.
Open Transfer Form: Dispatcher clicks "Initiate Transfer," and the system displays the Patient Transfer form.
Enter Transfer Details: Dispatcher selects:
- Destination: A suitable medical facility (e.g., City General Hospital).
- Transport Resource: An available resource (e.g., Ambulance A-08).
Submit Transfer: Dispatcher clicks "Confirm Transfer," triggering an API call (POST /api/patient-transfers).
Backend Processing:
- Validate Inputs: Ensures the patient, destination, and resource are valid.
- Create Transfer Record: Inserts a new entry in the patient_transfers table with status: in_progress.
Feedback:
- Success: All relevant parties (Dispatcher, Ambulance, Hospital) receive updates, and the transfer process begins.
- Error: Validation or system errors prevent the transfer, prompting a retry.

Completing the Transfer:

Hospital Confirmation: Upon arrival, the hospital user confirms the patient's receipt.
Finalize Transfer: The platform updates the transfer status (PUT /api/patient-transfers/{id}/complete) and:
- Sets status: done in the patient_transfers table.
- Updates the patient's current_location_id.
- Marks the transport resource (e.g., Ambulance A-08) as available.
Feedback:
- Success: The patient transfer is finalized, and all records are updated.
- Error: System issues or invalid inputs prompt an error alert.

Improved Workflow Diagram

flowchart TD
    %% Registering a Patient
    A[Start: Paramedic is at event scene] --> B[Access event on mobile platform]
    B --> C[Click Add Patient]
    C --> D[System displays New Patient form]
    subgraph PatientForm [Patient Form Fields]
        direction LR
        D1[Name: If known]
        D2[Age / Gender]
        D3[Initial Triage Status: Emergency severity level]
        D4[Preliminary Diagnosis: Observations]
    end
    D --> E[Click Save Patient]
    E --> F[API Call: POST /api/patients]
    F --> G[Backend Processing]
    subgraph PatientBackendActions [Backend Actions]
        G1[Authenticate and authorize paramedic]
        G2[Validate patient details]
        G3[Insert record into patients table]
    end
    G --> H[Patient record created, start recording vitals]
    G --> I[API responds with error]
    I --> J[Show error alert, retry]
    J --> D

    %% Recording Patient Vitals
    H --> K[Periodically record vitals 'e.g., Heart Rate, BP']
    K --> L[API Call: POST /api/patient-vitals]
    L --> M[Backend Processing]
    M --> N[Vitals saved successfully]
    M --> O[API responds with error]
    O --> P[Show error alert, retry]
    P --> K

    %% Transferring a Patient
    N --> Q[Dispatcher reviews patient details]
    Q --> R[Click Initiate Transfer]
    R --> S[System displays Patient Transfer form]
    subgraph TransferForm [Transfer Form Fields]
        direction LR
        S1[Destination: Select medical facility]
        S2[Transport Resource: Select ambulance]
    end
    S --> T[Click Confirm Transfer]
    T --> U[API Call: POST /api/patient-transfers]
    U --> V[Backend Processing]
    subgraph TransferBackendActions [Backend Actions]
        V1[Validate transfer details]
        V2[Insert record into patient_transfers table]
    end
    V --> W[Transfer initiated, notify all parties]
    V --> X[API responds with error]
    X --> Y[Show error alert, retry]
    Y --> S

    %% Completing Transfer
    W --> Z[Ambulance arrives at hospital]
    Z --> AA[Hospital confirms patient arrival]
    AA --> AB[API Call: PUT /api/patient-transfers/complete]
    AB --> AC[Backend Processing]
    subgraph CompleteTransferActions [Backend Actions]
        AC1[Update transfer status to done]
        AC2[Update patient's current location]
        AC3[Mark transport resource as available]
    end
    AC --> AD[Transfer finalized, records updated]
    AC --> AE[API responds with error]
    AE --> AF[Show error alert, retry]
    AF --> AA
    AD --> AG[End]

Developer Notes

Validation Rules

Triage Status: Must be selected from predefined enums (Red, Yellow, Green).
Destination: Must exist in the medical_centers table.
Transport Resource: Must be available and valid.

Audit Logging

Log patient registration and transfer actions in the audit_logs table for accountability.

Error Handling

Frontend Validation: Prevents incomplete or invalid submissions.
Backend Validation: Ensures consistency and adherence to database rules.
Messaging: Provides clear guidance for retrying failed actions.

Future Enhancements

Automated Transfer Suggestions: Recommend destinations and resources based on proximity and availability.
Real-Time Notifications: Notify all parties of transfer status updates.
Vitals Analytics: Provide trends and insights into patient vitals for medical analysis.

Key Takeaways

Streamlined Process: Ensures seamless patient registration and transfer management.
Robust Validation: Protects against errors and maintains data integrity.
Accountability: Audit logs and communication updates provide traceability for all actions.

This workflow is crucial for efficient emergency response, enabling paramedics and dispatchers to work collaboratively while ensuring patient safety.

9. 💬 Logging a Communication Entry

Overview

This workflow describes the process by which a dispatcher at the CRUM (Central Coordination Center) logs significant communications related to an active event. Such entries may include radio calls, phone conversations, or other forms of communication that are critical for coordinating emergency responses. The workflow ensures that all communications are documented for accountability and reference.

Detailed Description

The workflow outlines the steps for logging a communication entry, from initiating the log to saving the details in the database. It also includes error handling and cancellation paths to ensure smooth operation.

Actor:

Dispatcher: Responsible for managing and logging communications during active events.

Preconditions:

An active event is being managed.
Dispatcher is logged into the platform and authorized to log communications.

Postconditions:

Communication entry is recorded in the system, linked to the event and user.
The entry appears in the event's timeline for reference and accountability.

Key Workflow Actions

1. Initiating the Communication Log

Dispatchers begin the process by accessing the active event on the platform and clicking "Log Communication."

Steps:

Event Context: The dispatcher is managing an active event where significant communication occurs (e.g., an ambulance requests medical advice).
Open Log Form: Dispatcher clicks "Log Communication" on the Event Detail page, and the system displays the New Communication Log form.

2. Filling Out the Log Form

The dispatcher enters the critical details of the communication in the form.

Form Fields:

Channel: Selects the communication channel (e.g., Radio, Phone) from predefined options.
From: Specifies the sender of the communication (e.g., Ambulance A-08) by selecting from assigned resources or entering manually.
To: Indicates the recipient of the communication (e.g., CRUM Medical Director).
Summary: Provides a concise description of the communication (e.g., Ambulance requests advice for patient X with difficulty breathing).

Steps:

Complete Form: Dispatcher fills in all required fields with accurate information.
Submit Log: Dispatcher clicks "Save Log," and the system performs client-side validation to ensure no fields are missing or invalid.

3. Saving the Log

The validated data is sent to the backend for processing.

Backend Processing:

Authenticate User: Ensures the dispatcher is authorized to log communications.
Validate Data: Checks for completeness and consistency in the entered details.
Database Operations: Creates a new record in the communications_log table, linking it to the event and user.

Feedback:

Success: The backend responds with 201 Created, and the UI displays a success toast notification while adding the log entry to the event's timeline.
Error: If the backend encounters validation or system errors, the dispatcher is notified with an alert message.

4. Cancellation

Dispatchers can cancel the process at any point, closing the form without saving.

Steps:

Click Cancel: Dispatcher clicks "Cancel" on the form.
Return to Event Detail: The form closes, and the user is redirected back to the Event Detail page.

Improved Workflow Diagram

flowchart TD
    %% Start the Process
    A[Start: Significant communication occurs] --> B[Dispatcher clicks Log Communication on Event Detail page]
    B --> C[System displays New Communication Log form]

    %% Filling Out the Form
    C --> D[Dispatcher enters communication details]
    subgraph LogForm [Log Form Fields]
        direction LR
        D1[Channel: Select communication channel]
        D2[From: Specify sender 'e.g., Ambulance A-08']
        D3[To: Specify recipient 'e.g., CRUM Medical Director']
        D4[Summary: Describe communication]
    end
    D --> E[Click Save Log]
    E --> F[API Call: POST /api/communications-log]
    F --> G[Backend Processing]
    subgraph BackendActions [Backend Processing]
        G1[Authenticate dispatcher]
        G2[Validate log details]
        G3[Insert record into communications_log table]
    end
    G --> H[API responds 201 Created]
    H --> I[UI shows success notification and updates event timeline]
    I --> B

    %% Error Handling
    G --> J[API responds with error]
    J --> K[Show error alert: Failed to save log entry]
    K --> E

    %% Cancellation Path
    C --> L[Dispatcher clicks Cancel]
    L --> M[Form closes without saving]
    M --> B

Developer Notes

Validation Rules

Channel: Must be selected from predefined enums (e.g., Radio, Phone).
Sender and Recipient: Must exist within the system or be valid resources.
Summary: Should be concise but descriptive (maximum character limit may apply).

Audit Logging

All communication logs are recorded in the audit_logs table, including:

Event ID: The event associated with the log.
User ID: The dispatcher who created the log.
Timestamp: Exact time the log was created.

Error Handling

Frontend Validation: Prevents submission of incomplete or invalid forms.
Backend Validation: Ensures consistency and adherence to database rules.
Fallback Messaging: Guides users in case of errors with actionable instructions.

Future Enhancements

Real-Time Notifications: Notify all relevant parties when a communication log is added.
Searchable Logs: Enable filtering and searching of communication logs within the event timeline.
Categorization: Allow grouping of logs by type (e.g., Medical Advice, Resource Request).

Key Takeaways

Streamlined Logging: Simplifies the process of documenting critical communications.
Robust Validation: Ensures data integrity and prevents errors during submission.
Accountability: Audit logs provide traceability for all communication entries.

This workflow is essential for maintaining accurate records of communications during emergency operations, ensuring transparency and effective coordination.

10. 📜 Reviewing Audit Logs

Overview

Audit logs are a critical feature of the StateForce platform, enabling privileged users such as Superadmins and Admins to review a detailed trail of actions taken within the system. This ensures accountability, traceability, and compliance with operational and security standards. The workflow describes how users can navigate, filter, and analyze audit logs for specific entities, users, actions, and timeframes.

Detailed Description

This workflow explains the process for accessing and filtering audit logs within the system. It ensures that privileged users can efficiently retrieve relevant logs while handling errors gracefully.

Actor:

Superadmin: Has full access to all audit logs across the system.
Admin: May have restricted access depending on organizational policies.

Preconditions:

User is authenticated and has permissions to view audit logs.
The system contains audit logs generated by actions across various entities (e.g., events, users, institutions).

Postconditions:

The user successfully retrieves relevant audit logs based on applied filters.
Logs are displayed in a paginated table with actionable details for review.

Key Workflow Actions

1. Accessing Audit Logs

Privileged users begin by navigating to the Audit Logs section within the System Administration module.

Steps:

Access System Administration: User logs into the platform and selects System Administration.
Open Audit Logs: User clicks on the Audit Logs option, and the system displays the audit log view.
Default View: By default, the system shows the most recent logs for all entities, sorted by timestamp.

2. Filtering Audit Logs

Users can apply various filters to narrow down the logs to specific entries of interest.

Filtering Options:

Entity Name: Selects the table or entity type (e.g., events, users, institutions) from a dropdown menu.
Entity ID: Enters a specific ID to focus on a particular record (e.g., 12345).
Action Type: Checks boxes for actions (created, updated, deleted) based on the LogActions enum.
User: Searches for logs associated with a specific user by name or email.
Date Range: Specifies a start and end date for filtering logs within a defined timeframe.

Steps:

Apply Filters: User configures the desired filters and clicks "Apply."
Frontend Request: The system sends a GET /api/audit-logs request, including the filter parameters in the query string.

3. Retrieving Filtered Results

The backend processes the filter request and retrieves matching audit logs.

Backend Processing:

Parse Query Parameters: Backend parses the filters received in the query string.
Construct Database Query: Backend constructs a query on the audit_logs table using the provided filters.
Execute Query: Executes the query with pagination to manage large datasets.

Feedback:

Success: Backend responds with 200 OK and a paginated list of matching log entries.
Error: If the query fails (e.g., invalid filters or system issues), the backend responds with 400 Bad Request or 500 Internal Server Error.

4. Displaying Results

The system updates the UI to display filtered results in a structured table.

Results Table:

Timestamp: When the action occurred.
User: The user who performed the action.
Action: Type of action taken (e.g., created, updated, deleted).
Entity: The entity affected by the action (e.g., events, users).
Details: A button or link to view additional details (e.g., JSON diff showing changes).

Steps:

Update UI: The existing logs are cleared, and the filtered results are displayed.
Pagination: Users can navigate through pages of results if the dataset is large.

5. Handling Errors

If the system encounters an error while retrieving logs, it displays an appropriate message.

Error Handling:

Display Alert: An error message appears above the filter panel (e.g., "Could not retrieve logs.").
Retry Option: Users can adjust filters or retry the request.

Improved Workflow Diagram

flowchart TD
    %% Accessing Audit Logs
    A[Start: User navigates to System Administration -> Audit Logs] --> B[System displays Audit Log view]
    B --> C[Default view shows recent logs for all entities]

    %% Filtering Audit Logs
    C --> D[User opens filter options]
    subgraph FilterOptions [Filtering Options]
        direction LR
        D1[Entity Name: Select entity type]
        D2[Entity ID: Enter specific record ID]
        D3[Action: Check action types 'created, updated, deleted']
        D4[User: Search specific user]
        D5[Date Range: Specify start and end date]
    end
    D --> E[User applies filters]
    E --> F[Frontend sends GET /api/audit-logs with filters]
    F --> G[Backend processes filter request]
    subgraph BackendActions [Backend Processing]
        G1[Parse filter parameters]
        G2[Construct query on audit_logs table]
        G3[Execute query with pagination]
    end

    %% Handling Response
    G --> H[API responds 200 OK with filtered results]
    H --> I[UI displays logs in a paginated table]
    subgraph ResultsTable [Results Table]
        direction LR
        I1[Timestamp]
        I2[User]
        I3[Action]
        I4[Entity]
        I5[Details: View JSON diff]
    end
    I --> D

    %% Error Handling
    G --> J[API responds with error]
    J --> K[Show error message: Could not retrieve logs]
    K --> D

    %% End Workflow
    I --> Z[End]

Developer Notes

Validation Rules

Entity Name: Must match valid table names in the system.
Entity ID: Should correspond to existing records in the selected entity.
Action Type: Must be one of the predefined values (created, updated, deleted).
Date Range: Start date cannot be later than the end date.

Audit Log Structure

Each log entry includes:

Timestamp: Exact time the action occurred.
User: Identifier for the user who performed the action.
Action: Type of action taken.
Entity Name: Table or entity affected.
Entity ID: ID of the affected record.
Details: JSON or other structured data showing changes made.

Error Handling

Frontend Validation: Prevents submission of invalid filters.
Backend Validation: Ensures query parameters are valid and consistent.
Fallback Messaging: Guides users to retry or adjust filters.

Future Enhancements

Export Logs: Allow users to export filtered logs as CSV or JSON for external analysis.
Log Visualization: Provide charts and summaries of audit activity (e.g., actions over time).
Advanced Filters: Enable more granular filtering, such as changes made to specific fields.

Key Takeaways

Accountability: Audit logs provide a reliable trail of all actions performed within the system.
Ease of Use: Filtering options and a structured table make reviewing logs intuitive.
Error Resilience: The system gracefully handles errors and allows users to retry or refine their queries.

This workflow ensures transparency and supports compliance requirements by enabling privileged users to audit system activities effectively.

11. 📅 Create Calendar Event

Overview

This workflow explains how a manager schedules a new calendar event for an institution or team. Calendar events are essential for organizing operational activities, such as team meetings, training sessions, or resource allocation deadlines. The flow describes the interaction between the user, the system's interface, backend, and database.

Detailed Description

The process involves filling out a form with event details, submitting the information, and ensuring the event is linked to the appropriate institution. It highlights the seamless integration between the frontend, backend, and database.

Actor:

Manager: Responsible for creating and managing calendar entries for their institution or team.

Preconditions:

User is authenticated and authorized to schedule calendar events.
Institution exists in the system and is accessible to the user.

Postconditions:

Calendar event is successfully created and linked to the specified institution or team.
Event appears in the institution's calendar view.

Key Workflow Actions

1. Access Calendar Event Form

The manager begins by opening the "Create Calendar Event" form in the system interface.

Steps:

Navigate to Calendar: Manager logs into the platform and selects the calendar module from the dashboard.
Open Create Event Form: Manager clicks "Create Calendar Event," and the system displays a form with input fields.

2. Fill Event Details

Manager enters the necessary information to define the calendar event.

Form Fields:

Title: Name of the event (e.g., "Monthly Team Meeting").
Description: Optional details about the event's purpose or agenda.
Date and Time: Specifies when the event will take place.
Recurrence: If applicable, sets the event to repeat daily, weekly, monthly, or annually.

Steps:

Complete Form: Manager fills out all required and optional fields.
Validation: System ensures all required fields (e.g., title, date) are filled correctly.

3. Submit Event Details

Once the form is completed, the manager submits the event to the system.

Steps:

Submit Form: Manager clicks "Save Event," and the frontend sends the data to the backend via an API request (POST /api/calendar-events).
Backend Processing:
- Authenticate User: Verifies the manager's permissions.
- Validate Inputs: Checks for valid data (e.g., date format, title length).
- Database Operations:
  - Creates a new record in the calendar_entries table with the event details.
  - Links the calendar entry to the specified institution in the calendar_entries_institutions table.

4. View Confirmation

The system processes the request and provides feedback to the manager.

Feedback:

Success: Backend responds with 201 Created, returning the event ID. The UI displays a confirmation message and updates the calendar view to include the new event.
Error: If validation or database issues occur, the system displays an alert with actionable instructions.

Improved Workflow Diagram

sequenceDiagram
    participant Manager as Calendar Scheduler
    participant UI as User Interface
    participant API as Backend API
    participant DB as Database

    %% Opening the Form
    Manager->>UI: Open "Create Calendar Event" form
    UI->>Manager: Display form fields (title, description, date, recurrence)

    %% Submitting Event Details
    Manager->>UI: Fill out and submit event details
    UI->>API: Send API request with calendar event data
    API->>DB: Create record in calendar_entries table
    API->>DB: Link entry to institution in calendar_entries_institutions table

    %% Feedback and Confirmation
    API->>UI: Return confirmation and event ID
    UI->>Manager: Display success message and update calendar view

Developer Notes

Validation Rules

Title: Must be non-empty and within character limits.
Date and Time: Must be in a valid format and not in the past.
Recurrence: If set, must follow predefined patterns (e.g., daily, weekly).

Audit Logging

All changes to calendar events should be logged in the audit_logs table, including:

User ID: The manager who created the event.
Timestamp: When the event was created.
Details: Summary of the event and its associated institution.

Error Handling

Frontend Validation: Prevents submission of incomplete or invalid forms.
Backend Validation: Ensures data integrity and adherence to database rules.
Fallback Messaging: Guides users to retry or correct errors.

Future Enhancements

Event Notifications: Send email or SMS reminders for upcoming events.
Conflict Detection: Warn managers of overlapping or conflicting events for the same institution.
Analytics: Provide insights into event frequency and participation.

Key Takeaways

Streamlined Scheduling: Simplifies the process of creating and linking calendar events.
Robust Validation: Ensures data accuracy and integrity.
Accountability: Audit logs track all event-related actions for transparency.

This workflow ensures efficient scheduling and tracking of activities, improving operational coordination for institutions and teams.

12. 📎 Attach File

Overview

The "Attach File" workflow allows users to upload files (e.g., images, documents, reports) and associate them with specific entities such as events, institutions, or resources. This feature is crucial for providing additional context or documentation during emergency management operations. The workflow ensures seamless integration of uploaded files with the system.

Detailed Description

This process involves uploading a file, storing its metadata and content, and linking it to the appropriate entity. It includes user interaction, backend processing, and database operations.

Actor:

User: Responsible for uploading files and linking them to entities.

Preconditions:

User is authenticated and authorized to attach files.
Target entity (event, institution, or resource) exists in the system.

Postconditions:

File is successfully uploaded and stored in the system.
File is linked to the specified entity and accessible through the system.

Key Workflow Actions

1. Access Attach File Form

The user begins by navigating to the appropriate section of the platform and opening the "Attach File" form.

Steps:

Navigate to Entity: User accesses the relevant entity (e.g., event, institution, or resource) they want to attach the file to.
Open Attach File Form: User clicks "Attach File," and the system displays the file upload interface.

2. Upload File

The user selects and uploads the file through the provided interface.

Form Fields:

File: User selects the file to upload from their local device.
Metadata: Optional details about the file, such as a description or tags.

Steps:

Select File: User chooses the file and enters metadata (if required).
Submit File: User clicks "Upload," and the frontend sends the file data to the backend (POST /api/attachments).

3. Backend Processing

The backend handles the file upload and linking process.

Steps:

Validate File: Ensures the file meets system requirements (e.g., size, type).
Store File: Saves the file content in the storage system and metadata in the attachments table.
Link File to Entity: Creates a record in the appropriate linking table (e.g., event_attachments, institution_attachments) to associate the file with the target entity.

4. View Confirmation

The system provides feedback to the user, confirming the file upload and its successful linkage.

Feedback:

Success: The backend responds with 201 Created, returning the file URL and confirmation. The UI updates to display the file details.
Error: If validation or system issues occur, the system displays an alert with actionable instructions.

Improved Workflow Diagram

sequenceDiagram
    participant User as File Uploader
    participant UI as User Interface
    participant API as Backend API
    participant DB as Database

    %% Opening the Form
    User->>UI: Open "Attach File" form
    UI->>User: Display file upload interface

    %% Uploading File
    User->>UI: Select file and enter metadata
    UI->>API: Send API request with file data and metadata
    API->>DB: Save file content and metadata in attachments table
    API->>DB: Link file to entity in event_attachments, institution_attachments, or resource_attachments table

    %% Feedback and Confirmation
    API->>UI: Return confirmation and file URL
    UI->>User: Display file details, including URL and metadata

Developer Notes

Validation Rules

File Size: Must not exceed the maximum allowed size (e.g., 10 MB).
File Type: Restricted to supported formats (e.g., PDF, JPEG, PNG).
Entity Linkage: Ensure the target entity exists and the user has permissions to modify it.

Audit Logging

All file uploads should be logged in the audit_logs table, including:

User ID: The user who uploaded the file.
Timestamp: When the file was uploaded.
Entity ID: The entity the file was linked to.
File Metadata: Summary of the file details.

Error Handling

Frontend Validation: Prevents submission of unsupported file types or oversized files.
Backend Validation: Ensures data consistency and adherence to database rules.
Fallback Messaging: Guides users to retry or correct errors during upload.

Future Enhancements

Preview Files: Allow users to preview uploaded files directly in the platform.
Bulk Upload: Enable uploading and linking multiple files at once.
Version History: Track changes or updates to attached files.

Key Takeaways

Seamless Integration: The workflow ensures files are uploaded and linked efficiently.
Robust Validation: Protects against unsupported files and ensures accurate metadata.
Accountability: Audit logs provide traceability for all file uploads and linkage actions.

This workflow supports efficient documentation and enhances coordination during emergency operations by enabling users to attach relevant files to entities.

🛠 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

📄 StateForce Wiki Footer

🤝 Contribute

We are always looking for feedback and contributions to improve StateForce. Feel free to open issues, suggest edits, or submit pull requests to the repository.

Repo: StateForce GitHub
Contact: martinmendozadev@gmail.com

🌐 Support

If you encounter issues or need assistance, please reach out via:

Email: martinmendozadev@gmail.com
GitHub Issues: Submit an Issue

📝 License

This documentation and the StateForce platform are licensed under the Apache License 2.0.

Thank you for using StateForce! 🚨
Together, we are improving emergency response operations in real-time.

📚 StateForce Wiki Sidebar

Welcome to the StateForce Wiki! Use this sidebar to navigate through the documentation.

🏠 Home

Home

🛠 System Design

🗄 Database

🎨 Design & Style

Style Guide

🚦 User Workflows

🧪 Testing

Testing Guide

📎 Others

Files Relevant

This sidebar provides quick access to all the documentation pages. For detailed information, click on the desired section.