# Felisco-Sun Ops Console — Standard Operating Procedures & Staff Training Manual > **Confidential · Internal Operations Training Guide** > **System:** Felisco-Sun Port Trucking & Heavy Haulage Dispatch Console > **URL:** `/trucks/admin/index.html` > **Target Audience:** Port Dispatchers, Fleet Managers, Operations Supervisors, and Billing Officers --- ## Table of Contents 1. [System Overview & Architecture](#1-system-overview--architecture) 2. [Console Access & Security Gate](#2-console-access--security-gate) 3. [Topbar & Global Controls](#3-topbar--global-controls) 4. [Section 1: Operations Overview & Fleet Radar](#4-section-1-operations-overview--fleet-radar) 5. [Section 2: Drivers & Trucks Fleet Management](#5-section-2-drivers--trucks-fleet-management) 6. [Section 3: Booking Requests & Dispatch Control Workbench](#6-section-3-booking-requests--dispatch-control-workbench) 7. [Section 4: Live Trip Operations & Lifecycle Management](#7-section-4-live-trip-operations--lifecycle-management) 8. [Section 5 & 6: Payments, Invoices & Official Receipts](#8-section-5--6-payments-invoices--official-receipts) 9. [Section 7: Dispute Resolution Queue](#9-section-7-dispute-resolution-queue) 10. [Section 8: Dynamic Pricing Matrix & Port Surge Multiplier](#10-section-8-dynamic-pricing-matrix--port-surge-multiplier) 11. [Daily Dispatcher Checklist & Shift Handover](#11-daily-dispatcher-checklist--shift-handover) 12. [Troubleshooting & Emergency Procedures](#12-troubleshooting--emergency-procedures) --- ## 1. System Overview & Architecture The **Felisco-Sun Ops Console** is the centralized command center for port drayage, container haulage, and heavy freight operations covering **Tema Port (MPS Terminal 2 & Harbor Gates)**, **Takoradi Port**, and national delivery corridors across Ghana. ``` +-----------------------------------------------------------------------------------+ | FELISCO-SUN OPS PLATFORM | +-----------------------------------------------------------------------------------+ | [Customer Portal] [Driver Web App] [Transporter Portal] | | - Request Quotes - Accept/Decline Offers - Sub-fleet Monitoring | | - Live GPS Tracking - Trip Milestones & POD - Driver Roster | | - MoMo Invoices/Receipts - GPS Ping Publishing - Payout Reconciliations | +-----------------------------------------------------------------------------------+ │ ▼ ┌──────────────────────────────────────┐ │ CENTRAL OPS CONSOLE (/admin/) │ │ - Fleet Telemetry & Live Radar Map │ │ - Price Negotiation & SMS Engine │ │ - Wave Matching & Direct Dispatch │ │ - MoMo Payment Verification │ │ - Invoices & Official Receipts │ │ - Standby Breakdown Swaps │ └──────────────────────────────────────┘ ``` ### Core Staff Roles & Responsibilities - **Terminal Dispatcher:** Monitors incoming customer requests, negotiates rates, broadcasts job offers or assigns standby trucks, and monitors corridor progress. - **Fleet Manager:** Registers new trucks, verifies driver licenses and GPHA port security passes, calibrates hardware GPS units, and updates asset maintenance statuses. - **Billing & Settlement Officer:** Verifies inbound MTN Mobile Money transfers, issues official payment receipts, reconciles client invoices, and reviews claims. --- ## 2. Console Access & Security Gate ### 2.1 Accessing the Console Navigate to: ``` https://[your-domain]/trucks/admin/index.html ``` ### 2.2 Administrator Authentication Gate The console is protected by an undismissable security gate: 1. **Existing Dispatchers:** Enter your registered administrative email and password, then click **Sign In to Ops Console**. 2. **New Staff Onboarding:** - Click the **Create Admin Account** tab. - Enter your **Full Name / Dispatcher Name**, active **Mobile Phone** (e.g. `0244123456`), corporate email, and a secure password (minimum 6 characters). - Click **Create Admin Account**. The account is immediately provisioned with port dispatcher privileges. 3. **Password Reset:** - Click **Forgot password?**, enter your email, and follow the password reset link sent to your inbox. 4. **Session Persistence:** - The session remains active across tab reloads. To log off at the end of a shift, click **Sign Out** in the sidebar or top bar. --- ## 3. Topbar & Global Controls At the top of every screen: 1. **Live GMT Clock:** Shows synchronized Greenwich Mean Time for port gate logbooks and vessel offloading schedules. 2. **Port Corridor Indicator:** Confirms live connection to Tema and Takoradi port telemetry nodes. 3. **📲 Alert Phone Numbers (`adminphone`):** - Click the **Alert Phones: [Numbers] (Edit)** badge. - Any mobile number configured here receives **instant SMS alerts** whenever: - A customer creates a new freight booking request. - A customer declares or completes a payment. - **How to Add a Dispatcher Number:** Type a 10-digit Ghana mobile number (e.g. `0244123456`) and click **+ Add Number**. It is saved in Firestore (`pricing_rules/adminphone`) and immediately synced across all dispatchers. - **How to Remove a Number:** Click the red **Remove** button beside the number when a dispatcher rotates off duty. --- ## 4. Section 1: Operations Overview & Fleet Radar ### 4.1 Real-Time KPI Cards At the top of the Overview tab, monitor the core health indicators: - **Open Requests:** Pending bookings requiring rate quotation or dispatch. - **Available Trucks:** Standby trucks parked at port staging hubs ready for immediate loading. - **Active Trips:** Freight currently rolling between terminal berths and client drop-offs. - **Paid Volume (GHS):** Total reconciled revenue collected for the current period. - **Open Disputes:** Customer or driver exceptions requiring intervention. ### 4.2 Maintenance Buttons - **Run Stale Cleanup:** Automatically flags expired booking requests (older than the client validity window) as `expired` so your queue remains clean. - **Refresh Stats:** Forces an immediate re-query of all fleet aggregates. ### 4.3 Live Fleet Radar & GPS Telemetry Map - **Interactive Google Map:** Displays real-time positions of all connected vehicles with custom status-colored truck markers. - **Filter Chips:** - **All:** Full fleet footprint. - **Available (Green):** Standby trucks near MPS Berth, Tema Gate 1, or Kpone. - **On Trip (Blue):** Actively moving containers. - **Maintenance (Amber):** Depot/workshop repair status. - **Offline (Gray):** Drivers currently off-shift. - **Recenter Fleet (🎯):** Dynamically adjusts map bounds to fit all active vehicles. - **Corridor Legend:** Quickly identifies vehicles across key corridors: *Tema Port MPS 1 & 2*, *Accra Central*, *Prampram Hub*, and *Takoradi Port*. --- ## 5. Section 2: Drivers & Trucks Fleet Management Manage all physical vehicles (assets) and human operators (drivers) in this workbench. ### 5.1 Registration Studio (Left Column) The studio features 3 tab modes: #### Mode A: Add Truck (Asset Only) Use this when registering a new tractor-trailer, flatbed, or box truck: 1. **Plate Number:** Enter official DVLA registration (e.g., `GT 1234-24`). 2. **Truck Category:** Select category (`flatbed`, `container_40ft`, `container_20ft`, `box_truck`, `tipper`, `lowbed`). 3. **Make & Model:** Select or type (e.g., *Mack Anthem 64T*, *DAF XF 480*, *Sinotruk HOWO A7*, *Volvo FH16*). 4. **Payload Presets:** Click quick-fill buttons: - `40ft Container (28t)` - `20ft Container (18t)` - `Heavy Flatbed (32t)` - `Medium Box (8t)` 5. **Hardware GPS Tracker Telemetry:** - **Device IMEI / ID:** Enter tracker IMEI (e.g., `864294058291048`). - **Vendor:** Choose *Teltonika*, *Coban*, *Concox/Jimi*, or *CalAmp*. 6. **Port Staging Hub:** Select default staging yard (e.g. *Tema Port — MPS Terminal 2*, *Kpone Inland Depot*, *Ashaiman Heavy Yard*). Hub coordinates auto-fill. 7. **Assigned Operator:** Select an existing driver or leave unassigned as standby. 8. Click **Register Truck Asset**. #### Mode B: Add Driver (Operator Only) Use this when hiring or onboarding a new driver: 1. Enter **Full Name**, **Mobile Phone** (e.g., `0244123456`), and optional email. 2. Enter **Driver License No.** and select **License Class** (*Class F Articulated Multi-Axle*, *Class E Heavy Commercial*, etc.). 3. Enter **Port Security Pass No.** (e.g. `GPHA-PASS-2024-81`) required for terminal gate clearance. 4. Set **Verification Status** to `Verified & Cleared`. 5. Click **Register & Verify Driver**. #### Mode C: Quick Pair (Atomic Combined) Use this for rapid single-step setup: atomizes Driver + Truck + Hardware GPS IMEI into a single submission. --- ### 5.2 Fleet Workspace & Asset Controls (Right Column) Toggle between **Trucks (Assets)** and **Drivers (Operators)**. #### Essential Truck Actions: - **Status Selector:** Switch status between `Available`, `Offline`, and `Maintenance`. Click **Update**. > *Note: If a truck is actively `on_trip`, the console prevents manual status changes to avoid corrupting active delivery data.* - **Reassign Driver:** Change the active driver paired with a truck. - **Direct Contact:** Click 📞 to call the driver or 💬 to open an immediate WhatsApp conversation with pre-populated truck plate details. - **📡 GPS Calibration & Auto-Scheduler:** - Click the **📡 GPS** button to expand the hardware calibration drawer. - **Presets:** Quick-click corridor hubs (*Tema Port*, *Meridian Port*, *Accra Central*, *Kotoka Airport*, *Prampram Hub*). - **Manual Ping:** Enter exact coordinates + ops note (e.g., *"Cleared Gate 3, staging at Berth 7"*) and click **Push Ping**. Coordinates update in Firestore and the live radar map instantly. - **Auto-Schedule Simulator:** Set auto-ping frequency (*Every 15 min*, *Every 30 min*, *Every 1 Hour*) and click **Start** for automated demo/fleet simulation. --- ## 6. Section 3: Booking Requests & Dispatch Control Workbench This is the primary operational workstation where dispatchers handle customer requests and assign trucks. ``` +---------------------------------------------------------------------------------------+ | WORKFLOW: CUSTOMER REQUEST TO CONFIRMED DISPATCH | +---------------------------------------------------------------------------------------+ | 1. Customer Submits Request ──> Appears in "Open Booking Requests" list | | | | 2. Dispatcher Selects Request──> Inspects Cargo, Terminal Pickup & Drop-off | | | | 3. Negotiate Freight Cost ──> Calls customer ──> Types GHS Rate | | ──> Clicks "Save Cost & SMS Customer Payment Link" | | | | 4. Customer Receives SMS ──> Customer pays via MTN MoMo or opens checkout link | | | | 5. Choose Dispatch Method ──> OPTION A: Broadcast to Nearest 3 Trucks (30s wave) | | ──> OPTION B: Manual Direct Dispatch (Standby Truck) | | | | 6. Driver Accepts / Assigned ──> Trip Created ──> Customer gets driver phone & plate | +---------------------------------------------------------------------------------------+ ``` ### 6.1 Inspecting an Open Booking Request 1. Review the **Open Booking Requests** list on the left. 2. Click any request to load its details into the **Dispatch Control Workbench**: - Customer Name, Contact Number, Company. - Cargo Type, Container Size, Weight/Volume. - Pickup Corridor (e.g. MPS Berth 2) and Drop-off Destination. - Distance (km) and initial estimated tariff. ### 6.2 Negotiating the Rate & Sending the MoMo Link 1. Click **📞 Call Customer to Negotiate** to finalize the rate over the phone. 2. In the **💰 Negotiated Freight Price (GHS)** box, type the agreed price (e.g., `2500`). 3. Click **📲 Save Cost & SMS Customer Payment Link**: - The price is recorded on the booking record. - An automated SMS is instantly sent to the customer's phone containing the agreed rate and a direct mobile link to pay. 4. To preview the formal Proforma Invoice before payment, click **📄 View Formal Invoice / Receipt**. ### 6.3 Handling Pre-Payment MoMo Submissions - When a customer sends a MoMo transfer and enters their reference in the customer portal, an alert banner turns yellow: `💰 MoMo Payment Notice Submitted! (Ref: [MOMO-REF])`. - Verify that the funds have reached the Felisco-Sun MoMo account (`0557941830`). - Click **✅ Confirm MoMo & Issue Receipt**: - The payment is validated. - An Official Payment Receipt is generated. - An SMS containing the official receipt link is sent to the customer. --- ### 6.4 Dispatch Strategy A: Proximity Broadcast Matching Use this when you have multiple independent drivers waiting in the staging yard: 1. Review **Nearby Candidate Trucks (Ranked Proximity)**. The console automatically calculates driving distance to the pickup terminal and displays the top 3 candidates. 2. Click **Broadcast to Nearest 3 (30s)**: - A 30-second offer timer begins. - An alert appears on the candidate drivers' mobile apps. - The first driver to tap **Accept** wins the job. 3. If no driver accepts within 30 seconds: - Click **Next Tier Wave** to expand the broadcast radius to the next 3 available trucks. - Click **Sweep Expired** to clear timed-out offer cards. ### 6.5 Dispatch Strategy B: Manual Direct Dispatch (Bypass Match) Use this when a dedicated transporter, company truck, or standby fleet asset is pre-assigned: 1. In the **Manual Direct Dispatch** card, select the truck from the dropdown. 2. Check **Require upfront payment before rolling out (Nudge customer)**. 3. Select the payment hold window (*30 mins*, *45 mins*, *60 mins*). 4. Click **Assign Truck**: - The trip is instantly created. - The selected truck's status transitions to `on_trip`. - The customer receives an instant SMS with the driver's name, phone number, vehicle plate, and live tracking link. - The console navigates automatically to **Section 4: Trips**. --- ## 7. Section 4: Live Trip Operations & Lifecycle Management Track active trips from loading through delivery sign-off. ### 7.1 Searching and Loading a Trip - Enter the **Trip ID** in the search bar and click **Open Trip**, or click **Open Trip** directly from an accepted broadcast offer. ### 7.2 Managing the `awaiting_payment` State If upfront payment was required and the customer has not yet paid: 1. The **Awaiting Customer Payment** banner displays: - **MoMo Recipient:** `0557941830` · MTN MoMo · Philomena Sena Tsikudo Zip Up. - **Exact Trip Amount:** (e.g. `GHS 2,800.00`). - **Unique Trip Reference:** (e.g. `FS-TRIP-8A2F`). - **Hold Window Timer:** Counts down the remaining minutes before the truck must be released. 2. **Nudge Tools:** - **Copy Reference:** Copies the exact payment reference to your clipboard. - **WhatsApp MoMo Instructions:** Generates a pre-formatted WhatsApp payment reminder with all account details, ready to send with one click. 3. **Clearing Dispatch:** - Once MoMo funds are verified, click **Confirm Payment & Dispatch Driver**. - The trip advances to `assigned`, the invoice converts to an Official Receipt, and the driver is cleared to enter the terminal gates. --- ### 7.3 Emergency Standby Reassignment (Breakdown / Permit Swap) > **CRITICAL FEATURE FOR PORT DISPATCHERS** > If an assigned truck suffers a mechanical failure, tire blowout, or terminal gate permit rejection while en route: 1. Locate the **Standby Truck Reassignment** card. 2. Select a replacement truck from the **Select available standby truck…** dropdown. 3. Click **Swap Truck**: - The original truck is released. - The new truck is assigned to the trip. - **All customer payments, billing invoices, cargo details, and delivery milestones are 100% preserved.** - The driver and customer apps seamlessly update to show the new vehicle plate. --- ### 7.4 Trip State Progression Machine Dispatchers can advance or assist driver trip milestones using the action buttons under **Advance Trip State**: ``` [assigned] ──> [en_route_pickup] ──> [arrived_pickup] ──> [loading] │ ▼ [in_transit] ──> [arrived_dropoff] ──> [unloading] ──> [delivered] ──> [completed] ``` | Milestone | Real-World Operational Event | |---|---| | `assigned` | Driver notified; preparing vehicle. | | `en_route_pickup` | Truck rolling toward MPS Terminal 2 or designated port gate. | | `arrived_pickup` | Truck checked in at terminal gate queue / waiting area. | | `loading` | Container or breakbulk cargo being mounted onto trailer chassis. | | `in_transit` | Container locked with GPHA customs seal; moving along highway. | | `arrived_dropoff` | Truck reached consignee warehouse / factory gates. | | `unloading` | Cargo being destuffed or container grounded. | | `delivered` | Cargo safely received; consignee signs physical waybill. | | `completed` | Proof of Delivery verified; trip closed in ledger. | ### 7.5 Proof of Delivery (POD) Verification - In the **Proof of Delivery (POD)** box: - If a driver uploaded a delivery photo via the driver web app, a preview link **View Photo ↗** appears. - Inspect the photo to confirm container seal integrity, signature, and undamaged cargo before clicking **Mark: completed**. --- ## 8. Section 5 & 6: Payments, Invoices & Official Receipts ### 8.1 Invoices vs. Receipts Paradigm The Felisco-Sun platform uses a single normalized billing entity: - **Status = `unpaid`:** Represents a **Commercial Freight Invoice** (Proforma Billing Document). - **Status = `paid`:** Automatically converts into an **Official Payment Receipt** (Paid in Full). ### 8.2 Invoices & Receipts Ledger Table - **Ledger KPIs:** - **Total Billed Volume:** Gross cumulative value of all freight bookings. - **Paid Receipts:** Verified revenue collected in full. - **Unpaid Invoices:** Outstanding accounts receivable awaiting payment. - **Filters & Search:** - Filter by **All Records**, **🟠 Unpaid Invoices**, or **🟢 Paid Receipts**. - Search by Client Name, Phone Number, Document ID, or MoMo Reference. - **Actions:** - **👁️ View / Print:** Opens the high-resolution, print-ready document modal. Supports browser printing (A4 format) and PDF generation. - **✓ Paid:** Reconciles an invoice manually when cash or direct bank wire has been confirmed, converting the document to an Official Receipt and triggering customer SMS confirmation. --- ## 9. Section 7: Dispute Resolution Queue Handle customer and driver claims (delays, container demurrage charges, seal discrepancies, routing deviations): 1. Select filter: **Open Only** or **All Disputes**. 2. Review the dispute details: Trip ID, filing party (Customer/Driver), and detailed grievance reason. 3. Investigate the trip timeline in Section 4. 4. Type resolution notes (e.g., *"Demurrage waiver granted by terminal manager; 10% credit applied"*). 5. Click **Resolve Dispute** to log the resolution note and close the ticket. --- ## 10. Section 8: Dynamic Pricing Matrix & Port Surge Multiplier Control base freight tariffs and port congestion multipliers across all vehicle classes. ### 10.1 Real-Time Port Demand Ratio The console continuously evaluates: $$\text{Demand Ratio} = \frac{\text{Open Booking Requests}}{\text{Available Standby Trucks}}$$ - **Ratio > 3.0:** Severe shortage $\rightarrow$ Suggested Surge: **$\times 1.5$** - **Ratio > 1.5:** Heavy demand $\rightarrow$ Suggested Surge: **$\times 1.25$** - **Ratio > 0.75:** Normal volume $\rightarrow$ Suggested Surge: **$\times 1.1$** - **Ratio $\le$ 0.75:** Balanced supply $\rightarrow$ Suggested Surge: **$\times 1.0$** To apply this suggestion across all active vehicle classes with one click, click **Apply Suggested Surge**. ### 10.2 Truck Pricing Matrix Table For each vehicle tier (`container_40ft`, `container_20ft`, `flatbed`, `box_truck`, `tipper`, `lowbed`): - **Base Fare (GHS):** Terminal mobilization fee. - **Rate / km:** Distance tariff based on road distance to drop-off. - **Rate / kg:** Excess weight fee. - **Min Fare:** Floor price below which no job may be booked. - **Surge Multiplier:** Custom multiplier applied during peak container vessel discharge windows. - **Active Toggle:** Enable or disable quoting for a specific truck category. - Click **Save** on any modified row to immediately update pricing rules in Firestore. - To restore standard factory rates, click **Seed Default Rules**. --- ## 11. Daily Dispatcher Checklist & Shift Handover ### 🌅 Morning Shift Checklist (06:00 - 08:00) - [ ] Log in and verify that your mobile number is active in the **Alert Phones** topbar badge. - [ ] Run **Run Stale Cleanup** in Section 1 to clear overnight expired requests. - [ ] Check Section 1 Radar Map: verify that standby trucks at Tema MPS 2 and Gate 1 are online with active GPS telemetry. - [ ] Inspect Section 3: review pending requests submitted outside business hours; call clients to negotiate rates. - [ ] Review Section 8: check the Port Demand Ratio and adjust surge multipliers if container vessel berthing has spiked terminal congestion. ### 🔄 Active Shift Operations (Continuous) - [ ] Keep phone available for inbound SMS notifications on bookings and payments. - [ ] Never clear a truck past terminal gates until payment status is confirmed as `paid`. - [ ] Provide clients with their MoMo Reference (`FS-TRIP-XXXX`) and instruct them to include MoMo charges. - [ ] If a driver reports a mechanical breakdown, immediately use **Standby Truck Reassignment** in Section 4 to maintain delivery schedule. ### 🌙 Evening Shift Handover (18:00 - 20:00) - [ ] Filter Section 6 for **Unpaid Invoices**: follow up on outstanding balances for deliveries scheduled for tomorrow morning. - [ ] Review Section 7: confirm all open disputes have resolution notes or are escalated to the Fleet Supervisor. - [ ] Audit completed trips: verify that Proof of Delivery (POD) photos are attached for all delivered containers. - [ ] If leaving the console workstation, click **Sign Out** to secure the terminal. --- ## 12. Troubleshooting & Emergency Procedures | Issue / Scenario | Root Cause | Immediate Action | |---|---|---| | **Driver cannot accept broadcast offer** | Offer window timed out (30s limit reached). | Click **Next Tier Wave** or use **Manual Direct Dispatch** to assign the driver directly. | | **Customer says they sent MoMo, but trip is still "awaiting_payment"** | Payment was transferred externally without automated capture. | Ask customer for MoMo transaction ID, check `0557941830` statement, and click **Confirm Payment & Dispatch Driver** in Section 4. | | **Truck marker not updating on live map** | GPS hardware power off or poor GSM reception at terminal berth. | Expand **📡 GPS** in Section 2, select a preset hub (e.g. *Tema Port*), and push a manual ping with an operational note. | | **Assigned truck broke down on highway** | Mechanical or tire failure during transit. | Open trip in Section 4, select a replacement standby vehicle from the dropdown, and click **Swap Truck**. | | **Customer needs formal receipt for corporate tax filing** | Client requires an official VAT/GRA receipt. | Open Section 6, search for the client name, click **👁️ View / Print**, and print or export as PDF. Ensure status displays `🟢 Receipt (Paid)`. | --- *Document Version: 2.4 · Approved by Felisco-Sun Operations Directorate · Tema Heavy Industrial Area, Ghana*