PRODUCT REQUIREMENTS DOCUMENT
Roundtrip · A Traxs Company Product · Version 1.1 · August 2026
Complete feature definitions, user stories, and acceptance criteria for the Roundtrip field service management platform.
| Attribute | Value |
|---|---|
| Document Title | Roundtrip Product Requirements Document (PRD) |
| Version | 1.1 — Initial Release |
| Status | Draft — In Review |
| Product | Roundtrip — Field Service Management SaaS |
| Company | Traxs Company |
| Author | Product Team |
| Date | August 2026 |
| Related Docs | SAD v1.1, Tech Stack Analysis v1.0, Requirements Outline v1.0 |
HOW TO READ THIS DOCUMENT
Document Guide
MoSCoW Priority
| Priority | Meaning | Release Target |
|---|---|---|
| Must Have | Non-negotiable. Product is not shippable without this. | MVP (v1.0) |
| Should Have | Important but not critical for launch. Workaround exists. | v1.1 or MVP if time allows |
| Could Have | Nice to have. Minimal impact if omitted from first release. | v2.0 |
| Won't Have | Explicitly excluded from this release cycle. | Future roadmap |
Complexity Sizing
| Size | Meaning | Approximate Dev Days |
|---|---|---|
| S | Small — well understood, few edge cases, low risk | 1–3 days |
| M | Medium — moderate complexity, some unknowns | 3–7 days |
| L | Large — significant complexity, multiple components involved | 7–14 days |
| XL | Extra Large — high complexity, spikes likely required first | 14+ days |
01 — PRODUCT OVERVIEW
Product Overview
Vision
Roundtrip is the field service management platform that makes running a service business feel effortless — from the moment a call comes in to the moment an invoice is paid. Designed for tradespeople and service contractors who want to run a professional, efficient business without enterprise software complexity.
Target Users
| User Role | Who They Are | Primary Goals | Primary Device |
|---|---|---|---|
| TenantAdmin | Business owner or operations manager | Oversee the entire business, manage users, settings, billing, and reports | Desktop |
| Dispatcher | Office coordinator or scheduling staff | Create and assign tickets, monitor technician progress, manage the day | Desktop |
| Technician | Field service technician or engineer | View assigned jobs, navigate to sites, record work, capture parts | Mobile PWA |
| BillingStaff | Accounts or admin staff | Generate invoices, send to clients, track payment status | Desktop |
| ReadOnly | Managers or franchise overseers | Monitor operations without modifying data | Desktop |
MVP Scope Summary
MVP (v1.0) — Must Have Features Only
F-01: Authentication, tenant registration, user invitation, and role management
F-02: Full service ticket lifecycle — create, assign, update status, notes, attachments, part usage photos
F-03: Client management with service history
F-04: Inventory catalogue and part consumption recording
F-05: AI-powered daily route optimization (n8n + Ollama)
F-06: Invoice generation, PDF export, and email/SMS delivery
F-07: Live dispatch board with map and real-time technician locations
F-08: Client on-my-way notifications and technician assignment notifications
F-11: Technician PWA with offline capability
Out of Scope (v1.0)
- Payment processing / payment gateway integration (invoices link to external payment URL)
- Native mobile apps (iOS App Store / Google Play) — PWA covers mobile needs for MVP
- Accounting software integration (QuickBooks, Xero) — planned v2.0
- Customer self-service portal (client login to view their own tickets and invoices)
- Asset/equipment tracking (serial numbers, warranty expiry) — planned v2.0
- AI Tenant Assistant (F-10) — Should Have, deferred from MVP if timeline is tight
F-01 — Authentication & Tenant Onboarding
FEATURE REQUIREMENTS
Covers all user authentication, tenant registration, realm provisioning, user management, and role assignment capabilities.
US-001 As a new business owner, I want to register my company as a new tenant, so that I can start using Roundtrip for my business without manual setup by Traxs staff
Acceptance Criteria
Priority | Must Have | Complexity | L
-
AC01 Registration form captures: company name, owner name, email, phone, industry type, and subdomain preference
-
AC02 System validates subdomain uniqueness and format (lowercase alphanumeric, hyphens allowed, 3–30 characters)
-
AC03 On submit, a Keycloak realm is automatically provisioned with naming convention roundtrip-{slug}
-
AC04 A default TenantAdmin user account is created with a temporary password emailed to the owner
-
AC05 A welcome email is sent within 60 seconds of registration with login link and getting-started guide
-
AC06 Registration page is publicly accessible at roundtrip.app/register without authentication
-
AC07 Tenant is assigned the Standard plan by default; plan can be upgraded from the Admin portal
-
AC08 Failed provisioning triggers an alert to the Traxs ops team and a user-facing error with retry option
US-002 As a TenantAdmin, I want to_ invite team members and assign them roles, so that my dispatchers, technicians, and billing staff can each access only what they need.
Priority | Must Have | Complexity | M
Acceptance Criteria
- AC01 Admin can invite users by email address; invited users receive an email with a time-limited activation link (72 hours)
- AC02 Admin selects one of the following roles on invitation: Dispatcher, Technician, BillingStaff, ReadOnly
- AC03 Admin can assign multiple roles to the same user
- AC04 Invited users who activate set their own password; they are prompted to enable MFA (optional unless enforced by admin)
- AC05 Admin can view a list of all active and pending invitations with their status
- AC06 Admin can revoke pending invitations before they are accepted
- AC07 Admin can deactivate existing user accounts; deactivated users cannot log in but their data is retained
- AC08 Admin can re-activate previously deactivated users
- AC09 All role changes take effect on the user's next login (or next token refresh)
US-003 As a user, I want to_ log in securely and have my session persist appropriately, so that I can work throughout the day without being interrupted by frequent re-authentication
Priority | Must Have | Complexity | M
Acceptance Criteria
- AC01 Login page is served at {tenant}.roundtrip.app/login or roundtrip.app/login?tenant={slug}
- AC02 Successful authentication issues an access token (15 minute TTL) and refresh token (8 hour TTL)
- AC03 The app silently refreshes the access token before expiry; the user is not prompted to re-login during active sessions
- AC04 After 8 hours of inactivity, the user is redirected to the login page with a session-expired message
- AC05 Failed login attempts are rate-limited: 5 failures trigger a 15-minute lockout with email notification to the user
- AC06 Login page is responsive and usable on mobile (for technician use)
- AC07 Single Sign-On (SSO) can be configured by TenantAdmin via the settings portal (SAML 2.0 or OIDC)
- AC08 Users can initiate a password reset from the login page; reset emails expire after 1 hour
US-004 As a TenantAdmin, I want to configure tenant-wide settings, so that Roundtrip behaves according to my business rules and branding preferences
Priority | Should Have | Complexity | M
Acceptance Criteria
- AC01 Admin can set: company name, logo (uploaded image), primary contact email, billing contact email, business phone
- AC02 Admin can configure: default timezone, date format (MM/DD/YYYY or DD/MM/YYYY), currency, and distance unit (miles/km)
- AC03 Admin can set business hours (used for SLA calculations and scheduling constraints)
- AC04 Admin can configure notification preferences: which events trigger email vs. SMS vs. in-app notifications
- AC05 Admin can enforce MFA for all users in the tenant
- AC06 Settings changes take effect immediately (no restart required)
- AC07 All settings changes are logged in the audit trail with the admin's user ID and timestamp
F-02 — Service Ticket Management
FEATURE REQUIREMENTS
The core workflow of Roundtrip — creating, assigning, updating, and completing service tickets. All ticket data is scoped to the tenant.
US-010 As a Dispatcher, I want to create a new service ticket for a client, so that the job is recorded, assigned a ticket number, and dispatched to a technician
Priority | Must Have | Complexity | M
Acceptance Criteria
- AC01 Ticket creation form captures: client (search existing or create new inline), service address, requested service description, priority (Low/Normal/High/Urgent), and preferred date/time window
- AC02 System auto-generates a unique ticket number in format RT-{year}-{sequence} (e.g., RT-2026-00142)
- AC03 New tickets default to Open status
- AC04 Dispatcher can optionally assign a technician at creation time; if not assigned, ticket remains in the unassigned queue
- AC05 Ticket is linked to the client's full service history automatically upon creation
- AC06 Dispatcher receives a validation error if service address cannot be geocoded; manual coordinate entry is offered as fallback
- AC07 Ticket creation triggers a real-time push to the dispatcher dashboard via SignalR
- AC08 All required fields (client, address, description) must be completed before the ticket can be saved
US-011 As a Dispatcher, I want to assign a ticket to a technician and see their current workload, so that I can balance jobs across the team and ensure no technician is overloaded
Priority | Must Have | Complexity | M
Acceptance Criteria
- AC01 Assignment panel shows all active technicians with: name, current status (available/en-route/on-site), number of open tickets today, and skill tags
- AC02 Dispatcher can assign ticket by selecting a technician from the panel or dragging the ticket to a technician on the dispatch board
- AC03 Assignment triggers a real-time push notification to the technician's PWA via SignalR
- AC04 Assigned ticket status changes from Open to Assigned automatically
- AC05 Dispatcher can reassign a ticket from one technician to another; the original technician receives a notification that the ticket was reassigned
- AC06 System warns (but does not block) if assigning a ticket to a technician whose skills don't include the required service type
- AC07 Dispatcher can add notes to the assignment (e.g., 'customer requests afternoon only')
US-012 As a Technician, I want to view my assigned tickets for the day in priority order, so that I know exactly what jobs I need to complete and in what order
Priority | Must Have | Complexity | S
Acceptance Criteria
- AC01 Technician's home screen shows today's assigned tickets sorted by: route order (if optimized) or by scheduled time
- AC02 Each ticket card shows: ticket number, client name, service address, service type, priority badge, and estimated arrival time
- AC03 Technician can see the count of remaining tickets for the day
- AC04 Tickets scheduled for future dates are shown in a separate 'Upcoming' section
- AC05 Technician can filter their ticket list by status (All, Assigned, In Progress, On Hold)
- AC06 Ticket list is available offline (PWA cache); last-synced timestamp is displayed when offline
US-013 As a Technician, I want to update the status of a ticket as I progress through a job, so that the dispatcher has real-time visibility and the service record is accurate
Priority | Must Have | Complexity | S
Acceptance Criteria
- AC01 Technician can advance ticket through: Assigned → In Progress → Completed (or On Hold)
- AC02 Setting status to In Progress records the start timestamp automatically
- AC03 Setting status to Completed requires a completion note (minimum 10 characters describing work done)
- AC04 Setting status to On Hold requires a reason from a dropdown: Awaiting Parts, Customer Not Home, Rescheduled, Awaiting Customer Approval
- AC05 Each status change is logged with timestamp and user ID in the ticket history
- AC06 Status changes push real-time notifications to dispatchers via SignalR
- AC07 Technician cannot set status to Completed if there are unresolved checklist items on the ticket
- AC08 Cancelled status can only be set by Dispatcher or TenantAdmin, not by Technician
US-014 As a Dispatcher, I want to search and filter the ticket list, so that I can quickly find specific tickets without scrolling through the entire list
Priority | Must Have | Complexity | S
Acceptance Criteria
- AC01 Search bar supports full-text search across: ticket number, client name, client address, and service description
- AC02 Filter controls include: status, assigned technician, date range, priority, and service type
- AC03 Search results update in real-time as the user types (debounced, 300ms delay)
- AC04 Active filters are displayed as removable tags below the search bar
- AC05 Search result count is displayed (e.g., '42 tickets match')
- AC06 Dispatcher can save a filter combination as a named view (e.g., 'My Urgent Open Tickets')
- AC07 Saved views appear in the left navigation sidebar for quick access
US-015* As a Dispatcher, I want to add internal notes and attachments to a ticket, so that important context is preserved for the technician and for future service visits
Priority | Must Have | Complexity | S
Acceptance Criteria
- AC01 Notes section supports rich text entry (bold, italic, bullet lists, no code required)
- AC02 Notes are timestamped and attributed to the author
- AC03 Notes can be marked as 'Technician Visible' (shown in the PWA) or 'Internal Only' (dispatcher/admin only)
- AC04 Attachments: photos, PDFs, and documents up to 10MB per file, 50MB total per ticket
- AC05 Image attachments display as thumbnails in the ticket; clicking opens a full-screen viewer
- AC06 Notes and attachments are included in the ticket PDF export
- AC07 Notes support @mention of other users within the tenant
US-016 As a Technician, I want to capture photos of parts used and attach them to the ticket, so that part usage is documented with visual evidence for billing accuracy and warranty purposes
Priority | Must Have | Complexity | M
Acceptance Criteria
- AC01 Technician can take a photo directly within the PWA (camera access) or upload from device gallery
- AC02 Photo upload is optimised for mobile — images are compressed to max 2MB before upload without visible quality loss
- AC03 Technician selects the inventory item associated with the photo from a searchable dropdown
- AC04 Technician enters the quantity used
- AC05 Photo, item, and quantity are saved as a PartUsage record linked to the ticket
- AC06 Part usage records are used to automatically calculate the parts cost line item on the invoice
- AC07 Technician can add multiple part usage entries per ticket
- AC08 Part usage uploads work offline and sync when connectivity is restored
F-03 — Client Management
FEATURE REQUIREMENTS
Managing the tenant's client database, service history, and contact information.
US-020 As a Dispatcher, I want to create and manage client records, so that we have a complete, accurate database of all customers and their service history
Priority | Must Have | Complexity | S
Acceptance Criteria
- AC01 Client record captures: company name (optional), first name, last name, primary phone, secondary phone, email, billing address, and multiple service addresses
- AC02 Each service address can be named (e.g., 'Main Office', 'Warehouse Unit 3')
- AC03 Duplicate detection: system warns if an email or phone number matches an existing client record in the tenant
- AC04 Client record displays a chronological service history showing all past tickets with status and date
- AC05 Dispatcher can add notes to a client record (persistent, separate from ticket notes)
- AC06 Client records support a 'Preferred Technician' field — this populates as the default assignment on new tickets for that client
- AC07 Client records can be soft-deleted (archived); archived clients' historical data is retained
US-021 As a Dispatcher, I want to view a client's complete service history in one place, so that I can provide informed service and identify recurring issues
Priority | Must Have | Complexity | S
Acceptance Criteria
- AC01 Client profile page shows all tickets (open and closed) in reverse chronological order
- AC02 Each history entry shows: ticket number, date, service type, technician, status, and total cost
- AC03 Clicking a history entry opens the full ticket detail
- AC04 Service history is exportable as a PDF or CSV for the client
- AC05 History includes a summary panel: total tickets, total spent, average completion time, last service date
- AC06 Dispatcher can filter history by date range, service type, or technician
F-04 — Inventory Management
FEATURE REQUIREMENTS
Tracking parts, consumables, and equipment across the tenant's stock. Linked to ticket part usage for accurate job costing.
US-030 As a TenantAdmin, I want to set up and manage the inventory catalogue, so that technicians can accurately record parts used and we can track our stock levels
Priority | Must Have | Complexity | M
Acceptance Criteria
- AC01 Inventory item record captures: SKU, part name, description, unit of measure, unit cost, reorder threshold, current quantity, and storage location
- AC02 Items can be organized into categories (e.g., Filters, Refrigerant, Electrical, Tools)
- AC03 Admin can bulk-import items via CSV upload; import preview shows first 10 rows and validation errors before confirming
- AC04 Items can have multiple locations (e.g., 'Van - Truck 03', 'Main Warehouse', 'Remote Depot')
- AC05 Each item has a photo field for visual identification by technicians in the field
- AC06 Barcode/QR code field for scanner-based lookup
- AC07 Item records are never hard-deleted — they are archived to preserve historical ticket data
US-031 As a Dispatcher, I want to see which items are low or out of stock, so that I can reorder before jobs are delayed due to missing parts
Priority | Must Have | Complexity | S
Acceptance Criteria
- AC01 A 'Low Stock' dashboard panel prominently displays all items at or below their reorder threshold
- AC02 Low stock items display: item name, current quantity, reorder threshold, and last used date
- AC03 Items at zero stock are shown separately with a 'Critical' badge
- AC04 Dispatcher can click a low stock item to view which upcoming tickets require that item
- AC05 A daily background job checks stock levels and sends an email digest of low stock items to the TenantAdmin and designated recipients
- AC06 Dispatcher can mark an item as 'On Order' with a note; this suppresses the low stock alert until resolved
US-032 As a Technician, I want to record the parts I used during a service call directly from my phone, so that stock levels are updated in real time and billing is accurate
Priority | Must Have | Complexity | M
Acceptance Criteria
- AC01 Technician can search for parts by name, SKU, or barcode scan
- AC02 Barcode scanner uses the device camera (PWA Web API); SKU can also be typed manually
- AC03 Technician enters the quantity used; quantity cannot exceed the current stock level (warning shown)
- AC04 Part consumption is recorded and stock quantity is decremented immediately upon save
- AC05 Technician can attach a photo of the packaging/label to the part usage record
- AC06 If the required part is not in the inventory catalogue, technician can enter a free-text part note; this flags for admin review to add to catalogue
- AC07 Part usage records sync offline and reconcile when connectivity is restored
US-033 As a TenantAdmin, I want to adjust inventory quantities and view the stock movement history, so that I can correct discrepancies and understand how our stock is being consumed
Priority | Should Have | Complexity | S
Acceptance Criteria
- AC01 Admin can perform a manual stock adjustment: increase, decrease, or set to an exact quantity
- AC02 All adjustments require a reason (dropdown: Received Shipment, Damaged, Theft/Loss, Audit Correction, Initial Setup)
- AC03 Every stock change is recorded in the movement history with: date, user, type, quantity change, and reason
- AC04 Admin can view a full audit log of stock movements per item or across all items for a date range
- AC05 Movement history is exportable as CSV for external accounting reconciliation
F-05 — AI-Powered Route Optimization
FEATURE REQUIREMENTS
Daily route planning for technicians using n8n workflow automation and Ollama local LLM inference.
US-040 As a Dispatcher, I want to have the system automatically generate an optimized route for each technician at the start of the day, so that technicians spend less time driving and complete more jobs per day
Priority | Must Have | Complexity | XL
Acceptance Criteria
- AC01 Route optimization runs automatically via a scheduled Hangfire job at a configurable time (default: 5:00 AM in tenant's timezone)
- AC02 Optimization considers: ticket addresses, technician start location, appointment time windows, technician skills matching ticket requirements, and estimated job durations
- AC03 Optimization uses OpenRouteService for driving distance matrix and Ollama for stop-order reasoning
- AC04 Optimized route is stored per technician per day and is visible on the dispatcher map and technician PWA
- AC05 Each stop on the route shows: estimated arrival time, estimated job duration, and driving time from previous stop
- AC06 Route optimization completes within 60 seconds for up to 20 stops per technician
- AC07 If optimization fails (Ollama unavailable), system falls back to chronological scheduling by appointment time and alerts the dispatcher
- AC08 Dispatcher receives a push notification when routes are ready each morning
US-041 As a Dispatcher, I want to manually trigger a route re-optimization after last-minute ticket changes, so that routes stay optimal even when jobs are added, cancelled, or rescheduled during the day
Priority | Must Have | Complexity | L
Acceptance Criteria
- AC01 Dispatcher can click 'Re-Optimize Routes' from the dispatch board at any time
- AC02 Re-optimization can be scoped to all technicians or a specific technician
- AC03 Re-optimization respects jobs already In Progress (they are pinned at the current stop; only remaining stops are reordered)
- AC04 Optimized routes push to affected technicians via SignalR within 90 seconds of triggering
- AC05 Route history is maintained — previous route versions are retained for audit purposes
- AC06 Dispatcher is shown a diff of what changed: stops added, removed, or reordered
US-042 As a Technician, I want to see my daily route on a map with turn-by-turn navigation, so that I can navigate efficiently without switching between apps
Priority | Should Have | Complexity | L
Acceptance Criteria
- AC01 Route is displayed on a Leaflet map with numbered pins for each stop in optimized order
- AC02 Technician can tap any stop to see the ticket details (client name, address, service description)
- AC03 Map shows polyline route between stops with estimated driving time per leg
- AC04 Tapping 'Navigate' on a stop launches the device's native maps app (Google Maps or Apple Maps) with the destination pre-filled
- AC05 Map updates in real time as tickets are completed (completed stops turn grey)
- AC06 Map works in offline mode with cached tiles; routing polylines are cached at the time of optimization
F-06 — Billing, Invoices & Quotes
FEATURE REQUIREMENTS
Generating and delivering financial documents — invoices, quotes, and service reports — with multi-channel delivery.
US-050 As a BillingStaff, I want to generate an invoice from a completed service ticket, so that the client is billed accurately for parts used and labour performed
Priority | Must Have | Complexity | L
Acceptance Criteria
- AC01 Invoice is generated from a completed ticket with one click; line items are pre-populated from part usage records
- AC02 Invoice includes: tenant business name and logo, client details, ticket number, service date, itemized parts (description, quantity, unit cost, total), labour line item (configurable rate × hours), subtotal, tax (configurable rate), and total
- AC03 BillingStaff can add, edit, or remove line items before finalizing the invoice
- AC04 Labour hours default to the ticket's In Progress duration; BillingStaff can override
- AC05 Invoice number is auto-generated in format INV-{year}-{sequence} (e.g., INV-2026-00089)
- AC06 Invoice status lifecycle: Draft → Sent → Viewed → Paid → Overdue (auto-set after configurable days past due)
- AC07 Finalized invoices are locked from editing; a credit note must be issued to make corrections
- AC08 Invoice generates as a branded PDF via QuestPDF with tenant logo and brand colours
US-051 As a BillingStaff, I want to send an invoice to a client by email or SMS, so that the client receives their invoice promptly without manual PDF attachment
Priority | Must Have | Complexity | M
Acceptance Criteria
- AC01 Send Invoice button triggers a Hangfire background job that emails the PDF via SendGrid
- AC02 Email recipient defaults to the client's email on file; BillingStaff can override or add CC addresses
- AC03 SMS option sends a short message with a secure link to view the invoice online (link expires in 30 days)
- AC04 Invoice email template is customizable per tenant (subject line, body message, brand footer)
- AC05 Sent timestamp is recorded on the invoice record; invoice status changes to Sent
- AC06 Client can view the invoice online via a public (no login required) URL; the online view shows a read-only invoice
- AC07 Online invoice view includes a 'Pay Now' button (payment gateway integration is a future feature; button links to a configurable external payment URL for now)
- AC08 BillingStaff receives a confirmation notification when the invoice email is successfully delivered
US-052 As a Dispatcher, I want to generate a quote before a job begins, so that clients can approve estimated costs before we commit technician time
Priority | Should Have | Complexity | M
Acceptance Criteria
- AC01 Quote can be created standalone or from an Open ticket
- AC02 Quote captures: line items (description, quantity, unit cost), expiry date, and optional terms and conditions
- AC03 Quote generates as a PDF with the same branding as invoices
- AC04 Quote is sent via email or SMS; client can view and approve online
- AC05 Client approval online records a timestamp and the client's name as the approver
- AC06 Approved quote can be converted to a ticket and/or invoice with one click
- AC07 Expired quotes (past the expiry date) are automatically flagged; client receives a reminder email 48 hours before expiry
US-053 As a TenantAdmin, I want to view a billing dashboard with revenue and outstanding balance summaries, so that I have financial visibility into the business without needing to run manual reports
Priority | Should Have | Complexity | M
Acceptance Criteria
- AC01 Billing dashboard shows: total invoiced this month, total collected this month, total outstanding, number of overdue invoices
- AC02 Charts show: monthly revenue trend (last 12 months), revenue by service type, and top 10 clients by spend
- AC03 Overdue invoices table shows: invoice number, client, amount, days overdue, and a quick-send reminder button
- AC04 All figures are scoped to the current tenant automatically
- AC05 Dashboard data refreshes every 15 minutes (Redis-cached aggregation)
F-07 — Dispatch Board & Live Map
FEATURE REQUIREMENTS
The real-time operations center for dispatchers — a live map of all technicians and jobs, with drag-and-drop assignment.
US-060 As a Dispatcher, I want to see all technicians and open jobs on a live map, so that I can make fast, informed dispatch decisions based on geographic context
Priority | Must Have | Complexity | L
Acceptance Criteria
- AC01 Dispatch board displays a Leaflet map with: technician location pins (updated every 60 seconds), open job pins (colour-coded by priority), and completed job pins (greyed out)
- AC02 Technician pins show: technician name, current status, and number of remaining jobs in tooltip
- AC03 Job pins show: ticket number, client name, priority, and current status in tooltip
- AC04 Dispatcher can click any pin to open the relevant technician profile or ticket detail in a side panel
- AC05 Map has cluster behaviour: pins within the same area group at lower zoom levels to reduce visual clutter
- AC06 Live updates: technician location and ticket status changes push via SignalR without requiring a page refresh
- AC07 Map state (zoom level, centre) persists across navigation (stored in Zustand client state)
US-061 As a Dispatcher, I want to use the dispatch board's ticket list alongside the map, so that I can manage the full day's workload from a single screen
Priority | Must Have | Complexity | M
Acceptance Criteria
- AC01 Dispatch board has a split-panel layout: map on the left (60% width), ticket list on the right (40% width)
- AC02 Ticket list is filterable and sortable independently of the map
- AC03 Hovering a ticket in the list highlights the corresponding pin on the map
- AC04 Dragging a ticket from the list to a technician pin on the map assigns the ticket
- AC05 Layout is collapsible — dispatcher can expand either panel to full width
- AC06 Dispatcher can switch between map view and a pure Gantt/timeline view of the day's schedule
F-08 — Notifications
FEATURE REQUIREMENTS
Multi-channel notifications keeping clients, technicians, and dispatchers informed throughout the service lifecycle.
US-070 As a client, I want to receive an automated notification when a technician is on their way, so that I know when to expect service and can plan my day accordingly
Priority | Must Have | Complexity | M
Acceptance Criteria
- AC01 When a technician sets ticket status to In Progress and departs for the next job, an on-my-way notification is triggered
- AC02 Notification is sent via the client's preferred channel: SMS (Twilio) or email (SendGrid), based on client settings
- AC03 SMS message includes: technician first name, estimated arrival time, and a link to a live tracking page
- AC04 Email notification includes: technician name, photo (if set), estimated arrival time, and a map showing the technician's current location (auto-refreshing)
- AC05 Notification is sent only if the client has not opted out of notifications (opt-out managed per client record)
- AC06 If the ETA changes by more than 15 minutes, an updated notification is automatically sent
US-071 As a Technician, I want to receive real-time in-app notifications for new assignments and updates, so that I am immediately aware of changes to my schedule without checking the app manually
Priority | Must Have | Complexity | S
Acceptance Criteria
- AC01 New ticket assignment pushes a notification to the technician's PWA via SignalR within 5 seconds
- AC02 Route changes trigger a notification with a summary of what changed
- AC03 Notifications appear as a badge count on the app icon (PWA push notification API)
- AC04 Technician can view a notification history list
- AC05 Tapping a notification navigates directly to the relevant ticket or route
- AC06 Notifications are delivered even if the PWA is not currently in the foreground (via Web Push API)
F-09 — Reports & Analytics
FEATURE REQUIREMENTS
Business intelligence for tenant administrators — performance metrics, revenue analysis, and operational insights.
US-080 As a TenantAdmin, I want to view a comprehensive operations dashboard, so that I can monitor business performance and identify areas for improvement at a glance
Priority | Should Have | Complexity | L
Acceptance Criteria
- AC01 Dashboard shows KPI cards: tickets completed today, tickets completed this month vs. last month, average completion time, first-time fix rate, technician utilization rate
- AC02 First-time fix rate = tickets completed without returning to On Hold status / total tickets completed
- AC03 Charts include: ticket volume by week (last 13 weeks), tickets by status (donut chart), jobs by service type, technician performance comparison (bar chart)
- AC04 All charts use Recharts with Roundtrip brand colours
- AC05 Dashboard has a date range selector: Today, This Week, This Month, Last Month, Custom Range
- AC06 KPIs update within 15 minutes of new data (Redis-cached aggregation via background job)
- AC07 Dashboard is accessible to Dispatchers (read-only) and TenantAdmins
US-081 As a TenantAdmin, I want to export reports to PDF or CSV, so that I can share performance data with stakeholders who don't have Roundtrip access
Priority | Should Have | Complexity | M
Acceptance Criteria
- AC01 Available reports: Ticket Summary, Revenue by Period, Technician Performance, Inventory Usage, Client Service History
- AC02 Each report has configurable date range and filter parameters
- AC03 PDF export generates a branded report via QuestPDF with tenant logo and report title
- AC04 CSV export includes all raw data without aggregation (suitable for Excel analysis)
- AC05 Report generation runs as a Hangfire background job for large datasets; user receives a notification when ready
- AC06 Large reports (>1000 rows) are emailed as an attachment rather than served inline
F-10 — AI Tenant Assistant
FEATURE REQUIREMENTS
An in-app conversational AI assistant that answers questions about the tenant's own data using local Ollama inference.
US-090 As a Dispatcher, I want to ask the AI assistant natural language questions about my service data, so that I can get instant answers without running manual reports or searching through records
Priority | Should Have | Complexity | XL
Acceptance Criteria
- AC01 AI assistant is accessible via a chat panel in the sidebar (collapsible, does not block the main UI)
- AC02 Dispatcher can ask questions such as: 'What jobs does Maria have today?', 'What parts are low stock for HVAC?', 'Show me all overdue invoices from last month'
- AC03 Assistant answers are generated using RAG — retrieving relevant data from the tenant's database before passing context to Ollama
- AC04 All retrieved data is strictly scoped to the current tenant; the assistant cannot access or reference any other tenant's data
- AC05 Responses stream to the chat panel in real time (token-by-token via SignalR streaming)
- AC06 Assistant indicates when it is not confident in an answer and suggests the dispatcher verify manually
- AC07 Chat history is retained for the current session only; cleared on logout
- AC08 Assistant response time target: under 10 seconds for typical queries
US-091 As a Technician, I want to ask the AI for guidance on a service job while in the field, so that I can resolve issues faster without calling the office for information
Priority | Could Have | Complexity | XL
Acceptance Criteria
- AC01 Technician can access the AI assistant from the ticket detail screen in the PWA
- AC02 Technician can ask questions about the specific ticket: 'What parts were used last time this unit was serviced?' or 'What is the error code E32 on a Carrier AC unit?'
- AC03 Assistant uses RAG on the current tenant's service history for context-specific answers
- AC04 Technician can upload a photo of a part or error code; LLaVA model provides visual identification and guidance
- AC05 Photo-based queries require connectivity; text queries can use a cached lightweight model for offline operation
F-11 — Technician PWA (Mobile Experience)
FEATURE REQUIREMENTS
The Progressive Web App experience optimised for technicians in the field on mobile devices.
US-100 As a Technician, I want to install Roundtrip as an app on my phone without going to an app store, so that I have a native-like experience without the friction of app store installation
Priority | Must Have | Complexity | M
Acceptance Criteria
- AC01 Roundtrip is a PWA that displays an 'Add to Home Screen' prompt on first visit on mobile (iOS Safari and Android Chrome)
- AC02 Once installed, the app opens full-screen without browser chrome
- AC03 App icon uses Roundtrip logo; splash screen shows brand colours on launch
- AC04 Service Worker caches the core app shell, enabling immediate load even on slow connections
- AC05 App version updates are applied automatically in the background; user is prompted to refresh when a new version is available
US-101 As a Technician, I want to use the app when I have no mobile signal, so that I can still access ticket information and record work even in basements or rural areas
Priority | Must Have | Complexity | L
Acceptance Criteria
- AC01 Today's tickets and all their details are cached when the technician opens the app with connectivity
- AC02 In offline mode, technician can: view ticket details, update ticket status, add notes, and record part usage
- AC03 All changes made offline are queued locally and synced automatically when connectivity is restored
- AC04 Sync conflicts (e.g., ticket reassigned while offline) are flagged to the technician on reconnect with a clear resolution UI
- AC05 Offline indicator is clearly visible in the app header when the device has no connection
- AC06 Photos taken offline are queued for upload on reconnect
12 — NON-FUNCTIONAL REQUIREMENTS
Non-Functional Requirements
Performance
| Requirement | Target | Measurement Method |
|---|---|---|
| API read endpoint response time | P95 < 200ms | Application Insights / OTel trace percentiles |
| API write endpoint response time | P95 < 500ms | Application Insights / OTel trace percentiles |
| Dispatch board initial load | < 3 seconds on 4G connection | Lighthouse performance score > 80 |
| Route optimization completion | < 60 seconds for up to 20 stops | Hangfire job duration monitoring |
| Real-time notification latency | < 5 seconds from event to client | SignalR delivery timestamps |
| PWA offline cache load time | < 2 seconds on cached assets | Service Worker cache timing |
| Invoice PDF generation | < 5 seconds for standard invoice | QuestPDF generation time logged |
Scalability
| Requirement | Target |
|---|---|
| Concurrent tenants | 500+ tenants sharing Standard/Professional tier without performance degradation |
| Concurrent active users per tenant | 100 concurrent users per tenant (Dispatcher, Technician, Admin) |
| Tickets per tenant per year | 50,000+ tickets per tenant without pagination performance degradation |
| Inventory items per tenant | 10,000+ items per tenant |
| Horizontal API scaling | API instances are stateless — can scale horizontally behind a load balancer without code changes |
Security
| Requirement | Target |
|---|---|
| Authentication | All API endpoints require a valid Keycloak JWT. No unauthenticated access except tenant registration and invoice public view link. |
| Data isolation | Zero tolerance for cross-tenant data exposure. Verified by automated tests that attempt cross-tenant queries. |
| Input validation | All user inputs validated by FluentValidation before processing. No raw SQL string concatenation anywhere. |
| Sensitive data logging | PII (addresses, phone numbers, email addresses) must not appear in application logs. Serilog destructuring policies enforce this. |
| Secrets management | Database connection strings, API keys, and JWT signing keys stored in Azure Key Vault or equivalent secrets manager. Never in source code or config files. |
| HTTPS enforcement | All traffic over HTTPS. HTTP redirects to HTTPS. HSTS header with 1-year max-age. |
Accessibility
| Requirement | Target |
|---|---|
| WCAG compliance | WCAG 2.1 Level AA for all web UI screens |
| Keyboard navigation | All interactive elements reachable and operable via keyboard alone |
| Screen reader compatibility | Semantic HTML, ARIA labels on all icons and interactive elements |
| Colour contrast | Minimum 4.5:1 contrast ratio for normal text, 3:1 for large text |
| Mobile accessibility | Touch targets minimum 44×44px on mobile UI (WCAG 2.5.5) |
Browser & Device Support
| Platform | Minimum Version | Notes |
|---|---|---|
| Chrome (Desktop) | Last 2 major versions | Primary target for dispatcher UI |
| Edge (Desktop) | Last 2 major versions | Common in enterprise environments |
| Firefox (Desktop) | Last 2 major versions | Full support required |
| Safari (Desktop) | Last 2 major versions | macOS users |
| Chrome (Android) | Last 2 major versions | Primary technician PWA target |
| Safari (iOS) | iOS 16+ | PWA installation via Safari on iPhone; full PWA support requires iOS 16.4+ |
| Screen resolution | Minimum 1280×800 desktop, 375×667 mobile |
Roundtrip · Product Requirements Document v1.0 · A Traxs Company Product · March 2026