Transit Times Frontend Guide

This document covers all frontend forms, pages, and UI components related to Transit Times management in the iDrv5-MyFR8 platform.

Table of Contents

1. Overview
2. Transit Time Profiles Page
3. Rate Card Details - Transit Times Tab
4. Service Levels Page
5. API Endpoints Reference
6. Data Flow

---

Overview

The Transit Times system allows users to configure how long freight takes to travel between zones. The system supports four modes:

Mode	Description
Inherit	Uses the system default transit time profile
Profile	Uses a specific named transit time profile
Custom	Rate card maintains its own transit time entries
None	Transit times not applicable for this rate card

Key Concepts

• Transit Time Profile: A reusable collection of transit time configurations
• Transit Time Entry: A single origin-destination pair with base transit hours
• Service Level Multiplier: Adjusts base transit time based on service level (Express, Standard, Economy, etc.)
• Base Transit Hours: The standard transit time for a route (typically for “Standard” service level)

Transit Time Calculation Formula

Final Transit Time = (Base Transit Hours × Service Level Multiplier) + Adjustment Hours

Example:

• Base Transit: 24 hours (Sydney to Melbourne)
• Express Multiplier: 0.5x
• Adjustment: 0 hours
• Result: 24 × 0.5 + 0 = 12 hours

---

Transit Time Profiles Page

URL: /operations/rate/transit-time-profiles

Template: templates/portals/operations/transit_time_profiles.html

Purpose: Manage reusable transit time profiles that can be shared across multiple rate cards.

Page Layout

┌─────────────────────────────────────────────────────────────────┐
│  Transit Time Profiles                    [+ Create Profile]    │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ Total        │  │ Total        │  │ Linked       │          │
│  │ Profiles: 3  │  │ Entries: 45  │  │ Rate Cards: 8│          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────┐  ┌─────────────────────┐              │
│  │ Standard Australian │  │ Express Network     │              │
│  │ Network      [DEFAULT]│  │                     │              │
│  │ 25 entries          │  │ 12 entries          │              │
│  │ 5 rate cards        │  │ 2 rate cards        │              │
│  │ [View] [Edit] [Del] │  │ [View] [Edit] [Del] │              │
│  └─────────────────────┘  └─────────────────────┘              │
└─────────────────────────────────────────────────────────────────┘

Stats Cards

Card	Description
Total Profiles	Number of transit time profiles in the system
Total Entries	Sum of all zone-to-zone transit time entries
Linked Rate Cards	Number of rate cards using profile mode

Profile Card Actions

Button	Action
View	Opens profile details modal with tabs
Edit	Opens edit modal to modify profile settings
Delete	Deletes profile (disabled for default profile)

---

Create/Edit Profile Modal

Modal ID: profileModal

Purpose: Create new profiles or edit existing ones.

Form Fields

Field	Type	Required	Description
Profile Name	Text	Yes	Unique name for the profile
Description	Textarea	No	Description of when to use this profile
Set as Default	Checkbox	No	Makes this the system default profile

Service Level Multipliers Section

Input Mode Selector

Users can switch between three input modes for entering service level multipliers:

┌─────────────────────────────────────────────────────────────────┐
│  Input Mode: [Multiplier] [Hours] [Days]                        │
│                                                                 │
│  Base Hours Reference: [24] hours  (shown for Hours/Days modes) │
│  ℹ️ Standard service base time                                   │
└─────────────────────────────────────────────────────────────────┘

Mode	Input Type	Example	Description
Multiplier	Decimal (0.1 - 5.0)	0.5x	Direct multiplier value
Hours	Integer (1 - 720)	12 hrs	Actual transit hours, auto-calculates multiplier
Days	Decimal (0.1 - 30)	0.5 days	Actual transit days, auto-calculates multiplier

How It Works:

• When using Hours or Days mode, a “Base Hours Reference” field appears
• The base hours represent the Standard service level time (default: 24 hours)
• The system automatically calculates the multiplier: multiplier = entered_time / base_hours
• Switching modes preserves the underlying multiplier value and converts the display

Example - Setting Express to 12 hours when base is 24 hours:

• In Hours mode: Enter 12 → System calculates 12 / 24 = 0.5x multiplier
• In Days mode: Enter 0.5 → System calculates (0.5 × 24) / 24 = 0.5x multiplier
• In Multiplier mode: Enter 0.5 directly

Multipliers Table

Column	Description
Service Level	Name and description from service_levels table
Value	Multiplier, Hours, or Days (based on selected input mode)
Adjustment (Hours)	Fixed hours added/subtracted (-48 to +48)
Effect	Visual badge + calculated hours display

Effect Column Display:

┌──────────────┐
│  50% Faster  │  ← Speed effect badge
│  12h (0.5d)  │  ← Calculated hours based on base reference
└──────────────┘

Effect Badges:

• 🟢 X% Faster - Multiplier < 1.0 (green badge)
• 🔵 Normal - Multiplier = 1.0 (blue badge)
• 🟡 X% Slower - Multiplier > 1.0 (yellow badge)

Smart Defaults

When creating a new profile, multipliers are auto-assigned based on service level name:

Name Pattern	Default Multiplier
Express, Hot Shot, Urgent, Priority	0.5x
Standard (or unmatched)	1.0x
Economy, Saver, Budget	1.5x

Input Mode Conversion Examples

Given a Base Hours Reference of 24 hours (1 day for Standard service):

Service Level	Multiplier Mode	Hours Mode	Days Mode	Effect
Express	0.50x	12 hrs	0.5 days	50% Faster
Hot Shot	0.50x	12 hrs	0.5 days	50% Faster
Standard	1.00x	24 hrs	1.0 days	Normal
Economy	1.50x	36 hrs	1.5 days	50% Slower
Budget	2.00x	48 hrs	2.0 days	100% Slower

Note: Regardless of input mode, the system always saves the actual multiplier value to the database. The Hours and Days modes are purely for user convenience during data entry.

---

Profile Details Modal

Modal ID: profileDetailsModal

Purpose: View detailed information about a profile.

Tabs

1. Transit Entries Tab

Displays zone-to-zone base transit times.

Column	Description
Origin Zone	Starting zone name
Destination Zone	Ending zone name
Base Time	Hours and day equivalent (e.g., “24h (1 day)“)
Distance	Optional distance in kilometers
Actions	Delete button

Actions:

• Export CSV - Download entries as CSV file
• Add Entry - Opens add entry modal

2. Service Multipliers Tab

Visual card display of all service level multipliers.

┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│   Express   │  │  Hot Shot   │  │  Standard   │  │   Economy   │
│    0.5x     │  │    0.5x     │  │    1.0x     │  │    1.7x     │
│  50% Faster │  │  50% Faster │  │   Normal    │  │  70% Slower │
└─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘

Warning Indicator: Service levels without configured multipliers show a yellow warning badge.

3. Linked Rate Cards Tab

Shows count and list of rate cards using this profile.

Footer Actions

Button	Action
Copy Profile	Creates a duplicate with new name
Edit Profile	Opens edit modal
Close	Closes the modal

---

Add Entry Modal

Modal ID: addEntryModal

Purpose: Add a new zone-to-zone transit time entry.

Form Fields

Field	Type	Required	Description
Origin Zone	Dropdown	Yes	Select from available zones
Destination Zone	Dropdown	Yes	Select from available zones
Base Transit Time	Number + “hours”	Yes	Base time in hours
Distance	Number + “km”	No	Optional distance
Notes	Text	No	Optional notes

---

Rate Card Details - Transit Times Tab

URL: /operations/rate-cards/<id>

Template: templates/portals/operations/rate_card_details.html

Purpose: Configure transit time settings for a specific rate card.

Transit Time Mode Section

Located in the rate card info panel and expanded in the Transit Times tab.

┌─────────────────────────────────────────────────────────────────┐
│  TRANSIT TIME CONFIGURATION                                     │
├─────────────────────────────────────────────────────────────────┤
│  Transit Time Mode: [Dropdown: Inherit ▼]                       │
│                                                                 │
│  ○ Inherit - Use system default profile                        │
│  ○ Profile - Use specific profile: [Profile Dropdown ▼]        │
│  ○ Custom - Manage transit times for this rate card only       │
│  ○ None - Transit times not applicable                         │
│                                                     [Save Mode] │
└─────────────────────────────────────────────────────────────────┘

Mode Behaviors

Inherit Mode

• Uses the system default transit time profile
• Transit times table shows entries from default profile (read-only)
• No profile selector shown

Profile Mode

• Shows profile selector dropdown
• Transit times table shows entries from selected profile (read-only)
• Changing profile updates displayed times

Custom Mode

• Shows full transit times management interface
• Add Manual Entry button enabled
• Can create rate-card-specific transit time entries
• Entries stored in rate_card_transit_overrides table

None Mode

• Transit times section hidden or shows “Not applicable”
• Used for rate cards where transit time doesn’t apply

Transit Times Table (Tab Content)

Column	Description
Origin	Origin zone name with search
Destination	Destination zone name with search
Express	Transit time for Express service
Standard	Transit time for Standard service
Economy	Transit time for Economy service
Actions	Edit/Delete (custom mode only)

Add Manual Entry Modal

Available in Custom mode only.

Field	Type	Description
Origin Zone	Searchable dropdown	Origin zone selection
Destination Zone	Searchable dropdown	Destination zone selection
Service Type	Dropdown	Express/Standard/Economy
Transit Time	Number	Time value
Unit	Toggle	Hours or Days

Note: Days are converted to hours (×24) before saving to API.

---

Service Levels Page

URL: /operations/rate/service-levels

Template: templates/portals/operations/service_levels/service_levels_list.html

Purpose: Manage service levels that affect transit time calculations.

Service Level Fields

Field	Description
Name	Service level name (Express, Standard, etc.)
Description	Description of the service
Priority	Display order (lower = higher priority)
Is Active	Whether the service level is available
Base Cost Multiplier	Affects pricing calculations
Transit Time Multiplier	Default multiplier for transit calculations

Relationship to Transit Time Profiles

• Service levels are loaded dynamically in Transit Time Profile forms
• Each profile can configure multipliers for each active service level
• New service levels automatically appear in profile edit forms
• Service levels without configured multipliers default to 1.0x

---

API Endpoints Reference

Transit Time Profiles API

Base URL: /api/transit-profiles

Method	Endpoint	Description
GET	/	List all profiles
POST	/	Create new profile
GET	/<id>	Get profile with entries and multipliers
PUT	/<id>	Update profile
DELETE	/<id>	Delete profile
GET	/default	Get default profile
POST	/<id>/copy	Copy profile

Profile Entries

Method	Endpoint	Description
GET	/<id>/entries	List profile entries
POST	/<id>/entries	Add entry
PUT	/<id>/entries/<entry_id>	Update entry
DELETE	/<id>/entries/<entry_id>	Delete entry

Service Level Multipliers

Method	Endpoint	Description
GET	/<id>/multipliers	List multipliers
POST	/<id>/multipliers	Create/update multiplier (upsert)
DELETE	/<id>/multipliers/<sl_id>	Delete multiplier

Rate Card Transit Times

Method	Endpoint	Description
GET	/rate-card/<id>/transit-times	Get all transit times for rate card
GET	/rate-card/<id>/transit-time	Get single transit time (with query params)
GET	/rate-card/<id>/overrides	List custom overrides
POST	/rate-card/<id>/overrides	Add override
DELETE	/rate-card/<id>/overrides/<id>	Delete override

Service Levels API

Base URL: /api/service-levels

Method	Endpoint	Description
GET	/	List all service levels
POST	/	Create service level
GET	/<id>	Get service level
PUT	/<id>	Update service level
DELETE	/<id>	Delete service level

Rate Cards API (Transit-Related)

Method	Endpoint	Description
GET	/api/rate-cards/<id>	Includes transit_time_mode and transit_time_profile_id
PUT	/api/rate-cards/<id>	Can update transit time mode and profile

---

Data Flow

Creating a Transit Time Profile

User Action                    API Call                      Database
───────────────────────────────────────────────────────────────────────
1. Click "Create Profile"      -                             -
2. Fill form, click Save       POST /api/transit-profiles/   INSERT transit_time_profiles
3. Multipliers saved           POST /<id>/multipliers        INSERT service_level_transit_multipliers
4. Reload profiles             GET /api/transit-profiles/    SELECT all profiles

Assigning Profile to Rate Card

User Action                    API Call                      Database
───────────────────────────────────────────────────────────────────────
1. Open Rate Card Details      GET /api/rate-cards/<id>      SELECT rate_card
2. Change mode to "Profile"    -                             -
3. Select profile              -                             -
4. Click Save Mode             PUT /api/rate-cards/<id>      UPDATE rate_cards SET
                                                             transit_time_mode='profile',
                                                             transit_time_profile_id=<id>
5. Load transit times          GET /transit-profiles/<id>    SELECT entries, multipliers

Calculating Transit Time

Input                          Processing                    Output
───────────────────────────────────────────────────────────────────────
Rate Card ID: 5                1. Get rate card mode
Origin Zone: Sydney            2. If profile mode:
Destination Zone: Melbourne       - Get profile entries
Service Level: Express            - Get multiplier (0.5x)
                               3. Find base time (24h)
                               4. Calculate:                 Final: 12 hours
                                  24 × 0.5 + 0 = 12

---

Database Schema (Simplified)

-- Transit Time Profiles
transit_time_profiles (
    id, name, description, is_default, is_active, created_at, updated_at
)

-- Transit Time Entries (zone-to-zone base times)
transit_time_entries (
    id, profile_id, origin_zone_id, destination_zone_id,
    base_transit_hours, distance_km, notes
)

-- Service Level Multipliers
service_level_transit_multipliers (
    id, profile_id, service_level_id,
    transit_multiplier, adjustment_hours, display_priority
)

-- Rate Card Overrides (for custom mode)
rate_card_transit_overrides (
    id, rate_card_id, origin_zone_id, destination_zone_id,
    service_level_id, transit_hours
)

-- Rate Cards (transit-related columns)
rate_cards (
    ...,
    transit_time_mode VARCHAR(20) DEFAULT 'inherit',
    transit_time_profile_id INTEGER REFERENCES transit_time_profiles(id)
)

---

File References

File	Purpose
templates/portals/operations/transit_time_profiles.html	Transit Time Profiles management page
templates/portals/operations/rate_card_details.html	Rate Card details with transit times tab
templates/portals/operations/service_levels/service_levels_list.html	Service levels management
api/transit_time_profiles_api.py	Backend API for transit profiles
api/rate_cards_api.py	Rate cards API (transit mode endpoints)
api/service_levels_api.py	Service levels API
models/transit_time_profiles.py	SQLAlchemy models
migrations/create_transit_time_profiles.sql	Database migration

---

Troubleshooting

Service levels not showing in form

• Check /api/service-levels returns data
• Ensure service levels have is_active = true
• Check browser console for JavaScript errors

Transit times not calculating correctly

• Verify profile has entries for the zone pair
• Check multipliers are configured for service level
• Confirm rate card is using correct mode and profile

Profile changes not reflecting

• Clear browser cache
• Verify API response shows updated data
• Check rate card’s transit_time_profile_id is set

---

Last Updated: December 2024

---

Changelog

December 2025

• Added Input Mode Selector for service level multipliers (Multiplier/Hours/Days)
• Added Base Hours Reference field for Hours and Days input modes
• Enhanced Effect column to show calculated hours alongside speed badges
• Improved UX for users who prefer entering actual transit times instead of multipliers