Users Flow

StateForce User Flows

This document details the typical interaction flows, system capabilities, and key responsibilities for each user role within the StateForce platform. StateForce is an emergency resource management system, and its user roles are designed to support efficient and coordinated responses. The flows illustrate how users navigate the system to perform their duties.

---

1. Superadmin Flow

Primary Objectives: Superadmins ensure the overall health, security, and configuration of the StateForce platform. They manage the highest-level settings, administrator accounts, and platform-wide policies. Their actions have a global impact on the system.

Key Responsibilities:

• Platform-wide configuration and maintenance.
• Management of Administrator-level user accounts.
• Oversight of system security and data integrity.
• Monitoring overall system performance and health.
• Defining and enforcing global operational policies.

User Flow Diagram:

graph TD
    SA_Login["Login via Google OAuth2"] --> SA_Dashboard{"Superadmin Dashboard"};

    SA_Dashboard --> SA_SysConfig["System-Wide Configuration"];
        SA_SysConfig --> SA_CoreSettings["Core Platform Settings (e.g., API keys, default behaviors)"];
        SA_SysConfig --> SA_AuthProviders["Authentication Provider Setup (e.g., Google OAuth2 details)"];
        SA_SysConfig --> SA_GlobalPolicies["Global Data Retention & Access Policies"];
        SA_SysConfig --> SA_FeatureToggles["Enable/Disable Platform Features"];

    SA_Dashboard --> SA_AdminMgmt["Manage Administrator Accounts"];
        SA_AdminMgmt --> SA_CreateAdmin["Create New Admin User"];
        SA_AdminMgmt --> SA_AssignAdminRoles["Assign/Revoke Admin Privileges"];
        SA_AdminMgmt --> SA_ViewAdminActivity["Monitor Admin User Actions"];

    SA_Dashboard --> SA_PlatformHealth["Platform Health & Analytics"];
        SA_PlatformHealth --> SA_PerformanceMetrics["View System Performance Metrics"];
        SA_PlatformHealth --> SA_ErrorLogs["Review System-Level Error Logs"];
        SA_PlatformHealth --> SA_DataIntegrityChecks["Initiate Data Integrity Checks"];

    SA_Dashboard --> SA_TenantMgmt["Manage Top-Level Institutions or Tenants (if multi-tenant)"];
    SA_Dashboard --> SA_SecurityAudits["Access Full Security Audit Logs (audit_logs table)"];
    SA_Dashboard --> SA_AllAdminActions["Perform All Admin Role Actions (see Admin Flow)"];
    SA_Dashboard --> SA_Logout["Logout"];

Loading

Key Data Interactions: users (for admins), institutions (top-level), audit_logs, system configuration tables (not explicitly in schema, but implied).

---

2. Administrator Flow (Institution/System Admin)

Primary Objectives: Administrators are responsible for managing one or more institutions within StateForce. This includes user management for their assigned institutions, configuration of institutional settings, resource catalog management, and ensuring operational readiness of their institution(s) within the platform.

Key Responsibilities:

• User account management (invitations, creation, role assignment) for their institution(s).
• Configuration and maintenance of institution-specific data (institutions, base_rescues, medical_centers).
• Management of the resource catalog (resource_types, resource_categories, specialty_types).
• Defining and managing roles and permissions within their institutional scope.
• Monitoring activity and ensuring data accuracy for their institution(s).

User Flow Diagram:

graph TD
    A_Login["Login via Google OAuth2"] --> A_Dashboard{"Admin Dashboard"};

    A_Dashboard --> A_UserMgmt["Manage Users - within institutional scope"];
        A_UserMgmt --> A_InviteUser["Invite New User (creates invites record)"];
        A_UserMgmt --> A_CreateUserAccount["Create User Account - manual (users table)"];
        A_UserMgmt --> A_EditUserProfile["Edit User Profile and Roles (users, user_institutions)"];
        A_UserMgmt --> A_AssignUserToInstitution["Assign User to Institution(s) (user_institutions)"];
        A_UserMgmt --> A_AssignUserRole["Assign Role - Manager, Standard, etc. (user_institutions.role)"];
        A_UserMgmt --> A_DeactivateReactivateUser["Deactivate/Reactivate User (users.deleted_at)"];
        A_UserMgmt --> A_ManageUserSkills["View/Manage User Skills (user_skills)"];

    A_Dashboard --> A_InstitutionMgmt["Manage Institutions"];
        A_InstitutionMgmt --> A_CreateNewInstitution["Create New Institution (institutions table)"];
        A_InstitutionMgmt --> A_EditInstitutionDetails["Edit Institution Details - Name, Location, Director (institutions, locations)"];
        A_InstitutionMgmt --> A_UpdateInstitutionStatus["Update Institution Status - Active, Maintenance (institutions.status)"];
        A_InstitutionMgmt --> A_ManageInstitutionContacts["Manage Institution Contacts & Phone Numbers (contacts, phone_numbers, institution_contacts)"];
        A_InstitutionMgmt --> A_ManageInstAttachments["Manage Institution Attachments (attachments, institution_attachments)"];
        A_InstitutionMgmt --> A_ManageInstBaseRescues["Manage Base Rescues - within Institution (base_rescues)"];
        A_InstitutionMgmt --> A_ManageInstMedicalCenters["Manage Medical Centers - within Institution (medical_centers)"];

    A_Dashboard --> A_ResourceCatalogMgmt["Manage Resource Catalog"];
        A_ResourceCatalogMgmt --> A_ManageResCategories["Manage Resource Categories (resource_categories)"];
        A_ResourceCatalogMgmt --> A_ManageResTypes["Manage Resource Types (resource_types)"];
        A_ResourceCatalogMgmt --> A_ManageSpecialtyTypes["Manage Specialty Types/Skills (specialty_types)"];

    A_Dashboard --> A_RolePermissionMgmt["Manage Roles & Permissions - within institutional scope"];
        A_RolePermissionMgmt --> A_DefineCapabilitiesForRoles["Define Capabilities for Roles (via Pundit policies, not direct DB)"];

    A_Dashboard --> A_ViewScopedAuditLogs["View Audit Logs - for managed scope (audit_logs)"];
        A_ViewScopedAuditLogs --> A_FilterAuditLogs["Filter Logs by User, Entity, Action"];
        A_ViewScopedAuditLogs --> A_ExportAuditLogs["Export Logs"];

    A_Dashboard --> A_AccessScopedSystemSettings["Access System Settings - scoped to institution"];
    A_Dashboard --> A_ViewAllInstOperationalData["View All Operational Data for Institution - Events, Resources"];
    A_Dashboard --> A_Logout["Logout"];

Loading

Key Data Interactions: users, invites, institutions, user_institutions, resources, resource_types, base_rescues, medical_centers, contacts, locations, audit_logs.

---

3. Manager Flow (Operational Supervisor / Institution Manager)

Primary Objectives: Managers oversee the day-to-day emergency response operations for their institution or team. They supervise personnel, manage active events, allocate resources effectively, and ensure that operational protocols are followed. They bridge the gap between administration and field operations.

Key Responsibilities:

• Supervision of Standard Users and operational teams.
• Monitoring and managing active events (events table).
• Strategic allocation and reallocation of resources (resources, event_resources).
• Generating operational reports and analyzing performance.
• Ensuring team readiness and managing schedules (calendar_entries).

User Flow Diagram:

graph TD
    M_Login["Login via Google OAuth2"] --> M_Dashboard{"Manager Dashboard"};

    M_Dashboard --> M_EventOversight["Monitor Active Events"];
        M_EventOversight --> M_ViewEventList["View List of Ongoing/Pending Events (events table)"];
        M_EventOversight --> M_AccessEventDetails["Access Detailed Event Info - Map, Status, Resources (events, locations, event_resources)"];
        M_EventOversight --> M_AdjustEventPriority["Adjust Event Priority Levels (events.priority_level)"];
        M_EventOversight --> M_ReviewEventComms["Review Event Notes & Communications (event_notes, notes)"];

    M_Dashboard --> M_ResourceMgmt["Resource Allocation & Management"];
        M_ResourceMgmt --> M_ViewResourcePoolStatus["View Available Resources - Personnel, Vehicles, Equipment (resources table)"];
        M_ResourceMgmt --> M_ApproveDenyResourceRequests["Approve/Deny Resource Assignments to Events (event_resources)"];
        M_ResourceMgmt --> M_StrategicReassignResources["Reassign Resources Based on Priority"];
        M_ResourceMgmt --> M_UpdateMultipleResourceStatus["Update Status for Multiple Resources - e.g. shift change (resources.status)"];
        M_ResourceMgmt --> M_ViewEditResourceDetails["View/Edit Resource Details - Units, Status (resources table)"];

    M_Dashboard --> M_TeamMgmt["Team Supervision"];
        M_TeamMgmt --> M_ViewTeamMemberStatusAndAssignments["View Team Member Availability & Assignments (users, user_institutions, event_resources)"];
        M_TeamMgmt --> M_ManageUserShiftsOrCallsigns["Manage User Shifts/Callsigns (user_callsigns, calendar_entries)"];
        M_TeamMgmt --> M_ReviewTeamPerformanceReports["Review Team Performance - via reports"];

    M_Dashboard --> M_ReportingAndAnalytics["Generate Reports & Analytics"];
        M_ReportingAndAnalytics --> M_GenerateIncidentSummaryReports["Generate Incident Summary Reports"];
        M_ReportingAndAnalytics --> M_AnalyzeResourceUtilization["Analyze Resource Utilization"];
        M_ReportingAndAnalytics --> M_TrackResponseTimes["Track Response Times"];
        M_ReportingAndAnalytics --> M_ExportOperationalReports["Export Reports - PDF, CSV"];

    M_Dashboard --> M_ManageInstCalendar["Manage Calendar Entries for Institution (calendar_entries, calendar_entries_institutions)"];
        M_ManageInstCalendar --> M_CreateTeamMeetingsOrTrainings["Create Team Meetings/Trainings"];
        M_ManageInstCalendar --> M_ViewInstitutionWideSchedule["View Institution-wide Schedule"];

    M_Dashboard --> M_ManageLocalTeamContacts["Manage Local/Team Contacts (contacts)"];
    M_Dashboard --> M_Logout["Logout"];

Loading

Key Data Interactions: events, resources, event_resources, users, user_institutions, notes, event_notes, calendar_entries, audit_logs.

---

4. Standard User Flow (Field Operator / Dispatcher)

Primary Objectives: Standard Users are the frontline personnel who directly interact with events and resources. This includes dispatchers creating and managing events, and field units responding to incidents and updating their status. Their actions are critical for real-time situational awareness and effective response.

Key Responsibilities:

• Creating, updating, and closing events (events table).
• Dispatching and assigning resources to events (event_resources).
• Updating their own status and the status of resources under their command (resources.status, events.status).
• Communicating critical information through notes and system channels (notes, event_notes).
• Maintaining their personal profile and readiness information (users, user_skills).

User Flow Diagram:

graph TD
    SU_Login["Login via Google OAuth2"] --> SU_Dashboard{"Operator Dashboard"};

    SU_Dashboard --> SU_EventMgmt["Manage Events"];
        SU_EventMgmt --> SU_CreateNewEvent["Create New Event - Emergency, Simulacrum, etc. (events table)"];
            SU_CreateNewEvent --> SU_EnterEventInfo["Enter Event Type, Location, Description, Priority (events, locations)"];
            SU_CreateNewEvent --> SU_SetEventInitialTriage["Set Initial Triage Status (events.triage_status)"];
        SU_EventMgmt --> SU_ViewMyAssignedEvents["View Events Assigned or Relevant to User/Team"];
        SU_EventMgmt --> SU_UpdateLiveEventStatus["Update Event Status - En Route, On Scene, Resolved (events.status)"];
        SU_EventMgmt --> SU_AddEventNotesOrUpdates["Add Notes/Updates to Event Log (event_notes, notes)"];
        SU_EventMgmt --> SU_AddEventAttachments["Add Attachments to Event - Images, Documents (attachments, event_attachments)"];
        SU_EventMgmt --> SU_CloseOrCancelEvent["Close/Cancel Event (events.status, events.ended_at)"];

    SU_Dashboard --> SU_ResourceDispatchAndTracking["Resource Dispatch & Tracking"];
        SU_ResourceDispatchAndTracking --> SU_ViewAvailableResourcesMapOrList["View Available Resources - Map or List (resources table)"];
        SU_ResourceDispatchAndTracking --> SU_AssignSpecificResourceToEvent["Assign Specific Resource to Event (event_resources)"];
        SU_ResourceDispatchAndTracking --> SU_UpdateResourceStatusForEvent["Update Resource Status for Event - e.g. Arrived (resources.status, event_resources)"];
        SU_ResourceDispatchAndTracking --> SU_TrackResourceGeoLocation["Track Resource Location - if GPS enabled (locations table for resource)"];

    SU_Dashboard --> SU_MyStatusAndAvailabilityMgmt["My Status & Availability"];
        SU_MyStatusAndAvailabilityMgmt --> SU_UpdateMyPersonalAvailability["Update Own Availability - On Duty, Off Duty, Available (user_institutions.status or dedicated table)"];
        SU_MyStatusAndAvailabilityMgmt --> SU_UpdateMyAssignedResourceStatus["Update Status of Directly Assigned Resources - e.g. vehicle maintenance (resources.status)"];

    SU_Dashboard --> SU_ViewMyNotifications["View Notifications & Alerts"];
    SU_Dashboard --> SU_AccessCommunicationChannels["Access Communication Channels"];
        SU_AccessCommunicationChannels --> SU_CreatePersonalOrSharedNote["Create Personal or Shared Note (notes, user_notes)"];
        SU_AccessCommunicationChannels --> SU_ViewTeamOrEventSharedNotes["View Notes Shared by Team/Event (event_notes, institution_notes)"];

    SU_Dashboard --> SU_ManageMyProfile["Manage My Profile"];
        SU_ManageMyProfile --> SU_UpdateMyContactDetails["Update Personal Contact Details (users, contacts, user_contacts)"];
        SU_ManageMyProfile --> SU_ViewMySkillsAndCerts["View My Skills & Certifications (user_skills, specialty_types)"];
        SU_ManageMyProfile --> SU_UploadMyProfileAvatar["Upload Profile Avatar (users.avatar_id, attachments)"];

    SU_Dashboard --> SU_ViewMyCalendar["View Personal/Team Calendar Entries (calendar_entries)"];
    SU_Dashboard --> SU_Logout["Logout"];

Loading

Key Data Interactions: events, resources, event_resources, locations, notes, event_notes, attachments, event_attachments, users, user_skills, calendar_entries.

---

5. Guest Flow

Primary Objectives: Guests have read-only access to a limited, predefined set of information. This role is intended for external observers, auditors, or public stakeholders who need a high-level overview without any operational capabilities.

Key Responsibilities:

• Viewing publicly shared information in a passive manner.

User Flow Diagram:

graph TD
    G_Login["Login via Shared Link, Guest Account, or Google OAuth2"] --> G_Dashboard{"Guest Dashboard - Read-Only"};

    G_Dashboard --> G_ViewPubliclyVisibleEvents["View Publicly Visible Events (events table with visibility filter)"];
        G_ViewPubliclyVisibleEvents --> G_ViewEventLocationsOnMap["View Event Locations on Map - Limited Details"];
        G_ViewPubliclyVisibleEvents --> G_ReadBasicEventSummaries["Read Basic Event Summaries - Status, Type"];

    G_Dashboard --> G_ViewPublicOrSharedReports["View Shared Reports (filtered reports based on visibility)"];
        G_ViewPublicOrSharedReports --> G_AccessPublicStatisticalOverviews["Access Public Statistical Overviews"];
        G_ViewPublicOrSharedReports --> G_DownloadPermittedReports["Download Permitted Reports - PDF"];

    G_Dashboard --> G_ViewPublicInstitutionInfo["View Public Information about Institutions - if shared (institutions.visibility)"];
    G_Dashboard --> G_ViewGeneralResourceOverview["View General Resource Availability - Aggregated, Non-Specific (resources with visibility filter)"];
    G_Dashboard --> G_Logout["Logout"];

Loading

Key Data Interactions: Read-only access to events, reports (conceptual), institutions, resources based on visibility flags.

---

6. Restricted User Flow

Primary Objectives: Restricted users have highly limited and specific access, often less than Guests. This role is for individuals who need to perform a very narrow set of actions or view a single piece of information, such as a volunteer checking in or acknowledging a message.

Key Responsibilities:

• Performing a predefined, minimal set of actions.
• Viewing only explicitly permitted, narrow data sets.

User Flow Diagram:

graph TD
    RU_Login["Login via Google OAuth2 or Special Credentials"] --> RU_LimitedDashboard{"Restricted Dashboard"};

    RU_LimitedDashboard --> RU_ViewHighlySpecificInformation["View Highly Specific Information"];
        RU_ViewHighlySpecificInformation --> RU_ViewMySingleAssignedTaskOrResource["View My Single Assigned Task or Resource"];
        RU_ViewHighlySpecificInformation --> RU_AccessASpecificDataFeed["Access a Specific Data Feed - e.g. weather alerts"];

    RU_LimitedDashboard --> RU_PerformOneSpecificAction["Perform One Specific Action - if any"];
        RU_PerformOneSpecificAction --> RU_UpdateMyPersonalAvailabilityLimited["Update My Personal Availability - e.g. volunteer check-in"];
        RU_PerformOneSpecificAction --> RU_AcknowledgeReceiptOfMessage["Acknowledge Receipt of a Message"];

    RU_LimitedDashboard --> RU_ViewGeneralAnnouncements["View General Announcements"];
    RU_LimitedDashboard --> RU_Logout["Logout"];

Loading

Key Data Interactions: Highly restricted read/write access to specific fields in tables like users (status field), messages (acknowledgment), or a custom task table.

---

Cross-Role Interactions & Collaboration Points

Effective emergency management relies on seamless collaboration:

• Admins & Managers: Admins set up institutions and user accounts that Managers then operate within. Managers might request new user roles or resource types from Admins.
• Managers & Standard Users: Managers oversee and direct Standard Users. Standard Users report event progress and resource status, which Managers monitor and use for decision-making. Resource requests from Standard Users (or automated systems) may require Manager approval.
• Standard Users (Dispatch & Field): Dispatchers (Standard Users) create events and assign field units (also Standard Users). Continuous communication and status updates flow between them.
• All Roles & Audit Logs: Actions by all users are recorded in audit_logs, which Superadmins and Admins can review for accountability and system analysis.
• Information Sharing (Notes & Attachments): notes, event_notes, and attachments serve as crucial tools for sharing information across roles involved in an event or managing an institution. Visibility settings (Visibility enum) control who sees what.

---

Summary Table of Potential Role Capabilities

Feature / Action Area	Superadmin	Admin	Manager	Standard User	Guest	Restricted
System Configuration	Full	Scope	No	No	No	No
Manage All Users	Full	Scope	Team	No	No	No
Manage Institutions	Full	Scope	View	No	No	No
Manage Resource Catalog	Full	Full	No	No	No	No
Manage Roles & Permissions	Full	Scope	No	No	No	No
Event Management
Create/Edit/Close Events	Full	Full	Full	Direct	No	Limited
View All Events	Full	Full	Full	Scoped	View	Specific
Resource Management
Assign/Dispatch Resources	Full	Full	Full	Direct	No	No
Update Resource Status	Full	Full	Full	Direct	No	Limited
View All Resources	Full	Full	Full	Scoped	View	Specific
Reporting & Analytics	Full	Full	Full	Limited	View	No
View Audit Logs	Full	Scope	Limited	No	No	No
Manage Personal Profile	Full	Full	Full	Full	View	View
View Calendar/Notifications	Full	Full	Full	Full	View	Limited

(Legend: Full = Full Control; Scope = Control within assigned scope/institution; Team = Control over own team; Direct = Direct operational control; Limited = Limited capability; View = Read-only; Specific = Very specific read-only; No = No Access)

---

Notes

• This document provides a conceptual overview. The exact implementation of permissions and flows will depend on the application's business logic, particularly how Pundit policies (or a similar authorization mechanism) are defined.
• The Role enum (superadmin, admin, manager, guest, restricted, standard) in user_institutions and invites is central to differentiating these flows.
• Real-time updates via ActionCable and Hotwire/Turbo will significantly enhance the user experience, especially for Managers and Standard Users monitoring live events and resource movements.
• The visibility attribute on entities like notes and attachments is crucial for controlling information sharing across different roles and institutions.

---

Related Pages

• System Architecture
• Architecture Diagram
• Database Schema Overview
• Roles & Permissions Detailed Definition
• Testing Guide