Rapid Response Portal

The Rapid Response Portal (/rapid-response) is the mission-critical command and control interface within Black Shark. It manages mobile security fleets, armed reaction units, alarm/panic response dispatches, sector patrols, and crew rostering.

By connecting incoming panic alerts and emergency callouts to live-tracked vehicle crews, the portal guarantees fast emergency response times, rigorous SLA tracking, and audit-ready operational records.

Overview & User Roles#

The Rapid Response Portal provides tailored tools for tactical dispatchers, field supervisors, drivers, and operations managers:

graph TD
    subgraph Rapid Response Roles
        OM[Operations / Fleet Manager] -->|Fleet Oversight & Approvals| RR[Rapid Response Portal]
        CRD[Control Room Dispatcher] -->|Emergency Callout & Dispatch| RR
        FS[Field Crew Supervisor] -->|Vehicle Check-In & On-Scene Log| RR
        DRV[Designated Driver] -->|Mobile Operations & Odometer| RR
    end
    
    RR --> CC[Command & Control Workspace]
    RR --> FL[Fleet, Crews & Sector Zones]
    RR --> RS[Vehicle Rostering Engine]
    RR --> AT[Attendance Desk & Response Slips]
    RR --> DE[Automated Dispatch Engine]

Who It Is For#

Operations & Fleet Managers: Supervise fleet readiness, authorize vehicle maintenance states, review SLA response times, and approve monthly vehicle rosters.
Control Room Dispatchers: Monitor sector deployment boards, triage incoming SOS panic alerts, recommend the closest available units, and issue official Response Slips.
Field Crew Supervisors & Officers: Oversee on-scene investigations, confirm premises security, capture suspect/police docket details, and verify shift attendance.
Designated Drivers: Record vehicle check-in/out, log fuel and start/end odometer mileage, and maintain mobile vehicle readiness.

Command & Control Center#

The Command & Control suite gives dispatchers instantaneous visibility into fleet availability, sector coverage, and active emergencies.

graph LR
    WS[Operational Workspace] -->|Triage & Launch Wizard| RP[Guided Roster Planner]
    WS -->|Instant Dispatch| RS[Response Slip Generation]
    DB[Deployment Board] -->|Live Poll Updates| CR[Control Room Dispatch]
    DH[Executive Dashboard] -->|Readiness KPIs| FL[Fleet Readiness %]

1. Rapid Response Operational Workspace#

Accessible via: Command & Control → Rapid Response Workspace (/rapid-response/rapid-response-workspace)

The primary command cockpit for managing daily rapid response operations:

Readiness Counters: Live tally of total fleet units categorized as:
- Available: In-zone units ready for immediate callouts.
- Dispatched: En route to an alarm or emergency scene.
- On Scene: Actively securing premises or conducting investigation.
- Standby: Reserved for high-priority escrow or strategic coverage.
- Vehicle Down: Units in maintenance or under repair.
- Unhandled Alerts: Open panic signals requiring dispatch action.
Sector Zone Filter: Filter all active vehicles and standing crews by geographic response zone (e.g. Harare Central Sector 1, Northern Suburbs Sector 2).
Direct Emergency Dispatch Action: Click Dispatch next to any unhandled panic alert to instantly launch the vehicle dispatch modal.

[!NOTE] Screenshot placeholder: The Rapid Response Workspace showing fleet readiness counters, live sector filters, and the unhandled panic alert queue.

2. Rapid Response Dashboard#

Accessible via: Command & Control → Dashboard (/rapid-response)

Provides high-level operational metrics and intelligence for fleet supervisors:

Fleet Readiness Gauge: Real-time percentage of serviceable vehicles vs. vehicles due for service or under repair.
Active Incidents & Response Slips: Total emergency callouts handled today with outcome breakdowns.
Recent Activity Feed: Real-time log of the latest dispatches, panic alert triggers, and completed response slips.

3. Live Fleet Deployment Board#

Accessible via: Command & Control → Live Deployment Board (/rapid-response/rapid-response-deployment-board)

A live-polled sector dispatch board designed for multi-screen control room environments:

Real-Time Polling: Continuously refreshes vehicle locations, assigned drivers, and crew members.
State Updates: Change vehicle states directly on the board with a single click (Available → Dispatched → On Scene → Standby).

Fleet, Standing Crews & Response Zones#

Before vehicles can be rostered or dispatched, the operational fleet structure must be defined.

graph TD
    Zone[Response Zone: Harare North] --> Vehicle[Vehicle: RR-01 ALPHA-1]
    Vehicle --> Crew[Standing Crew: Alpha North Primary]
    Crew --> Driver[Driver: John Moyo - Licensed]
    Crew --> Sup[Supervisor: Peter Ndlovu]
    Crew --> Officer[Response Officer: David Zulu]
    Crew --> Relief[Standing Relief: Sarah Chim]

1. Vehicle Fleet Management#

Accessible via: Fleet & Zones → Vehicles (/rapid-response/vehicles)

Each response vehicle record contains critical operational telemetry:

Tactical Call Sign: Radio identifier used in control room communications (e.g. ALPHA-1, DELTA-04, RR-01).
Registration Number: Official vehicle license plate.
Assigned Response Zone: The default patrol sector for the vehicle.
Maintenance Status:
- Serviceable: Fully operational and available for active patrol.
- Due for Service: Operational but flagged for scheduled maintenance.
- Under Repair: Mechanically down (automatically blocks rostering and dispatch).
- Decommissioned: Permanently retired from the response fleet.
Telemetry: Live fuel level percentage (%), odometer reading (KM), and tracker device ID.

2. Response Zones & Sectors#

Accessible via: Fleet & Zones → Response Zones (/rapid-response/response-zones)

Response zones partition client territories into defined tactical sectors:

Zone Name & Code: Sector name (e.g. Harare Central Sector 1, ZONE-HRE-01).
Risk Classification: Low, Medium, High, or Critical Risk.
Target SLA Response Time: Maximum target dispatch-to-arrival time in minutes (e.g. 10 minutes).
GeoFence Integration: Link the zone to a polygon boundary for automated geofencing and nearest-unit proximity calculations.
Dispatch Access Notes: Special access codes, high-risk waypoints, or hospital/police rendezvous points.

3. Standing Vehicle Crews#

Accessible via: Rostering & Schedules → Standing Vehicle Crews (/rapid-response/rapid-response-crews)

Standing Crews assemble dedicated, recurring teams assigned to a specific patrol vehicle:

Assigned Vehicle: Links the crew to the vehicle (the response zone is inherited automatically).
Designated Driver: Primary driver (must possess a valid driver's license on file).
Shift Supervisor: Crew commander responsible for on-scene reporting.
Response Officer: Armed reaction or tactical backup officer.
Standing Relief Officer: Designated backup officer automatically prioritized during relief replacements.

The Guided Roster Planner Wizard#

Accessible via: Rapid Response Workspace → Action: Plan Month/Week Roster

The Guided Roster Planner allows operations managers to bulk-generate entire monthly or weekly vehicle schedules across multiple fleets in four simple steps:

graph LR
    S1[1. Select Period & Mode] --> S2[2. Select Vehicles]
    S2 --> S3[3. Configure Shift & Pattern]
    S3 --> S4[4. Generate & Review]

Step-by-Step Wizard Workflow#

Step 1: Period & Scope:
- Choose between Monthly View (full calendar month) or Weekly View (specific week number).
- Select the target Year and Month.
Step 2: Vehicle Fleet Selection:
- Select all or specific vehicles assigned to the active sector.
- View standing crew assignments for each vehicle before scheduling.
Step 3: Rotation Pattern & Shift Settings:
- Rotation Pattern:
  - Fixed Daily: Schedules shifts every day throughout the period.
  - 5 on / 2 off: 5 consecutive work days followed by 2 rest days.
  - 20 on / 10 off: 20 consecutive work days followed by 10 rest days.
- Shift Type:
  - Day Shift (06:00 – 18:00, 12 hours).
  - Night Shift (18:00 – 06:00, 12 hours).
  - Continuous 24h: Automatically splits each day into paired Day and Night shift blocks.
  - Custom Hours: User-defined start and end times.
- Deployment Mode: Set as Active Patrol or Standby Coverage.
Step 4: Execute Generation:
- Click Generate Vehicle Rosters.
- The system generates all shift entries, links standing crew members, checks for conflicts, and displays a summary of created shifts and conflict warnings.

The Monthly Vehicle Roster Board#

Accessible via: Rostering & Schedules → Roster Board (/rapid-response/rapid-response-roster-board)

The Roster Board provides a comprehensive scheduling grid displaying vehicle crews along the rows and days along the columns.

graph TD
    Draft[Draft Schedule] --> Conflict[Conflict Detection Engine]
    Conflict --> SupRev[Submit for Supervisor Review]
    SupRev --> MgrAppr[Manager Approval]
    MgrAppr --> Pub[Published Fleet Roster]
    Pub --> Sync[Auto-Populates Attendance Desk]

[!NOTE] Screenshot placeholder: The Rapid Response Roster Board showing vehicle crew groupings, shift pills (D, N, TO, L), date mode selector, and the conflict audit drawer.

Date Modes: Calendar vs. Payroll Cycle#

The Roster Board supports two distinct date projection modes:

Calendar Mode (1st – 31st): Standard operational view for monthly scheduling and client coverage reporting.
Payroll Cycle Mode (21st – 20th): Custom mid-month cut-off period matching security industry payroll cycles.

Grid Shift Codes#

Code	Meaning	Description
`D`	Day Shift	Vehicle crew scheduled for daytime patrol (06:00 – 18:00).
`N`	Night Shift	Vehicle crew scheduled for night response (18:00 – 06:00).
`TO`	Time Off	Scheduled rest day as per the vehicle rotation cycle.
`L`	Approved Leave	Personnel on approved leave (automatically blocks allocation).

Key Rostering Workflows#

1. Direct Cell Editing

Click any cell on the grid to change an assignment to D, N, TO, or L.
When changing to D or N, the system creates the vehicle shift and links the crew members automatically.

2. Drag-and-Drop Shift Swapping

Drag a shift cell from one guard/crew member to another on the same or a different date.
The system performs an atomic database swap to ensure no double-booking occurs.

3. Reliever Replacement Modal

Click the Replace icon on any scheduled shift cell.
The Reliever Modal displays available replacement guards, automatically checking:
- Active employment status.
- Valid driver's license (if replacing a designated driver).
- Absence of schedule conflicts and approved leave.
- Month shift count weighting to prevent overtime imbalance.
Select the replacement guard, add optional handover notes, and confirm. The system records the handover in the permanent RosterOverride audit trail.

4. Quick Standing Relief Assignment

Click Use Standing Relief to instantly assign the crew's pre-configured standing relief officer without opening the manual search modal.

5. Bulk Shift Fill

Click Bulk Fill to assign a shift pattern (e.g. D or N) across a range of days (e.g. Day 1 to Day 15) for a selected crew member in one action.

6. Automated Conflict Detection Engine

The system scans all shifts and flags:

Vehicle Down (Blocking): Shifts scheduled on a vehicle marked as Under Repair.
Missing Driver (Blocking): Shifts missing a designated driver.
Unlicensed Driver (Blocking): Assigned driver has no driver's license number recorded.
Approved Leave Conflict (Blocking): Crew member scheduled during an approved leave period.
Static Post Double-Booking (Blocking): Crew member simultaneously assigned to a static site guarding post in the main Operations module.
Missing Supervisor (Warning): Vehicle operating without an on-duty supervisor.

7. Approval & Publishing Pipeline

Submit for Supervisor Review: Moves draft shifts to supervisor_review.
Manager Approve: Operations Manager verifies conflict-free shifts and marks them as approved.
Publish Rosters: Locks the roster, activates live fleet deployment, and populates the Vehicle Attendance Desk.

8. Multi-Format Exports

Export Excel Roster: Formatted schedule spreadsheet for site dispatchers.
Export Payroll Excel: Dedicated shift count breakdown aligned with the selected date cycle (Calendar or 21st–20th).
Export Client Coverage Certificate: Generates an official, verifiable HTML/PDF coverage certificate confirming total vehicle hours and shifts monitored.

Emergency Callouts, Panic Alerts & Response Slips#

graph TD
    SOS[1. SOS Panic Alert / Alarm Activation] --> DE[2. Rapid Response Dispatch Engine]
    DE --> Rec[3. Recommend Closest Available Vehicle]
    Rec --> Disp[4. Dispatch Vehicle & Update State to Dispatched]
    Disp --> RS[5. Generate Official Response Slip]
    RS --> Scene[6. Arrive on Scene & Secure Premises]
    Scene --> Clear[7. Complete Response Slip with Outcome & Clear]

1. Automated Dispatch Engine & Proximity Calculation#

When an emergency occurs:

The dispatch engine calculates the Haversine GPS distance between the incident coordinates and all live vehicles in the sector.
It ranks available units by proximity (in kilometers) and deployment readiness.
Upon clicking Dispatch:
- The vehicle state updates to Dispatched.
- The linked Panic Alert status updates to Dispatched.
- An official Response Slip is generated.

2. Managing Response Slips#

Accessible via: Attendance & Response Slips → Response Slips (/rapid-response/response-slips)

Each callout generates a formal audit document with:

Slip Number: Unique sequential identifier (e.g. RR-SLIP-20260826-0042).
Vehicle & Crew: Assigned tactical vehicle, driver, and supervisor.
Callout Reason: Alarm Activation, Panic Button Trigger, Sector Patrol Check, VIP Escort, Client Request, Routine Standby.
Timestamps: Dispatch Time, Arrival Time, and Clear Time (calculates SLA response compliance).
Odometer Tracking: Starting KM and Ending KM (tracks mileage per callout).
Response Outcome:
- All Clear / Premises Secured: False trigger or minor alarm resolved.
- False Alarm: Verified user error or environmental trigger.
- Suspect Apprehended: Intruder intercepted on site.
- Escalated to Police: Formal handover to law enforcement with police docket details.
- In Progress: Vehicle currently on scene.

Vehicle Attendance Desk & Timesheet Synchronization#

Accessible via: Attendance & Response Slips → Vehicle Attendance Desk (/rapid-response/rapid-response-attendance-desk)

graph LR
    Desk[Vehicle Attendance Desk] -->|Check-In| Act[Status: Checked In]
    Act -->|Check-Out| Sync[RapidResponseAttendanceSync Service]
    Sync -->|Calculates Normal Hours| TS[Core HR / Finance Timesheet]
    Sync -->|Creates Line| TSL[TimesheetLine Record]

Daily Attendance Workflow#

Check-In:
- When crew members report for vehicle duty, the dispatcher or supervisor clicks Check In on the Attendance Desk.
- Sets check_in_time to current timestamp and status to checked_in.
Check-Out:
- At shift end, click Check Out.
- Sets check_out_time, records supervisor confirmation ID, and sets status to completed.
Automated Timesheet Synchronization:
- The background sync service (RapidResponseAttendanceSync) automatically computes total shift hours.
- It creates or updates the guard's monthly Timesheet and adds a TimesheetLine for the shift date, ensuring accurate payroll processing without manual re-entry.

System Configuration & Technical Architecture#

Target Audience: System Administrators & Developers

Database Models & Relationships#

Vehicle: Core asset model with call sign, registration, fuel %, maintenance status, and foreign key to response_zone_id.
ResponseZone: Sector model with risk level, target SLA response time, and optional geo_fence_id.
RapidResponseCrew: Standing crew linking vehicle_id, driver_guard_id, supervisor_guard_id, response_officer_guard_id, and relief_guard_id.
RapidResponseRoster: Vehicle shift record containing date, shift start/end, standby mode, status, and linked RapidResponseRosterMember entries.
RapidResponseDeployment: Live deployment state model tracking current lat/lng coordinates, odometer start, and deployment state (available, dispatched, on_scene, standby).
ResponseSlip: Formal callout log linking vehicle, driver, client, incident, panic alert, timestamps, and outcome.
RapidResponseAttendance: Shift check-in/out stamps synchronized to core HR Timesheet records.

Permissions & Access Control#

Access to the panel is restricted via AccessControl::canAccessRapidResponse($user):

Roles: super_admin, rapid_response_officer, control_room_operator, supervisor.
All queries enforce tenant isolation with administrative bypass for enterprise managers.