Waypoint — Product Requirements Document

Version: 1.0
Date: July 2026
Author: Pete Carroll, Founder — Traxs Group LLC
Status: Draft
Product: Waypoint — Business Operating System
URL: traxswaypoint.app

1. Overview

This document defines the product requirements for Waypoint v1 — the detailed specification of how each feature works, what the user sees, and how the system behaves. It is the primary reference for design and development decisions.

Read the BRD first for business context and objectives.

2. User Personas

Persona 1 — The Owner-Operator (Primary)

Name: Mike
Role: Owner, HVAC company, 6 employees
Uses RoundTrip: Yes — has been a customer for 3 months
Technical comfort: Moderate — uses smartphone daily, comfortable with web apps
Pain: Spends Sunday evenings in QuickBooks trying to understand where the money went. Has no idea which technician is most productive. Employee certifications are tracked in a spreadsheet that is 2 years out of date.
Goal: Open one screen every morning and know how the business is doing.

Persona 2 — The Office Manager (Secondary)

Name: Sarah
Role: Office manager / dispatcher, same HVAC company
Uses RoundTrip: Yes — manages dispatch daily
Technical comfort: High — power user of RoundTrip
Pain: Manages HR manually. Leave requests come in via text. Has no system for tracking who has what certifications.
Goal: A proper system for team and HR management that doesn't require buying another subscription.

Persona 3 — The Standalone SMB Owner (Tertiary)

Name: Lisa
Role: Owner, commercial cleaning company, 12 employees
Uses RoundTrip: No
Technical comfort: Low-moderate
Pain: Business data is in four different places. Has no idea if the business is profitable month to month without asking her accountant.
Goal: See revenue, expenses, and team in one place without switching tools.

3. Information Architecture

traxswaypoint.app/
  /dashboard              ← Executive Dashboard (default landing page)
  /financials
    /overview             ← P&L snapshot
    /revenue              ← Revenue detail
    /expenses             ← Expense management
    /ar                   ← Accounts receivable aging
  /team
    /roster               ← Team roster
    /schedule             ← Weekly schedule view
  /hr
    /employees            ← Employee list
    /employees/:id        ← Employee profile
    /leave                ← Leave calendar and requests
    /certifications       ← Certification tracker
  /documents
    /library              ← Document library
    /knowledge            ← Knowledge base articles
  /settings
    /workspace            ← Company settings
    /integrations         ← RoundTrip connection
    /billing              ← Subscription management
    /team                 ← User management

The global nav is persistent on all screens:

Left sidebar (desktop) — product logo, nav items, collapse toggle
Bottom tab bar (mobile) — Dashboard, Financials, Team, HR, Documents
Top bar — workspace switcher (Traxs suite nav), notifications bell, user avatar

A suite switcher in the top bar allows users to switch between RoundTrip and Waypoint without logging in again. Shows only products the tenant has an active subscription to.

4. Module Specifications

Module 1 — Executive Dashboard

Route: /dashboard
Default landing page after login

4.1.1 Layout

The dashboard is a responsive widget grid. On desktop: 3-column layout. On tablet: 2-column. On mobile: single column, widgets stacked.

All data refreshes on page load. A manual refresh button is available. Timestamp shows "Last updated X minutes ago."

4.1.2 Widgets — v1 Fixed Set

Revenue MTD

Large number display: $12,480
Sub-label: "Revenue this month"
Trend indicator: ↑ 12% vs last month (green) or ↓ 8% vs last month (red)
Source: RoundTrip paid invoices (if connected) or manual revenue entries

Revenue YTD

Large number: $84,320
Sub-label: "Revenue this year"
Progress bar: % of annual target (if target set in settings)

Accounts Receivable

Total outstanding: $4,200
Sub-label: "Outstanding invoices"
Breakdown: 2 invoices · oldest 34 days
Click through to /financials/ar

Open Tickets (RoundTrip only)

Count: 8 open tickets
Value: $3,600 estimated
Status breakdown: 3 assigned · 2 in progress · 3 unassigned
Click through to RoundTrip dispatch board (opens in new tab)
Hidden if RoundTrip not connected

Team Today

4 of 6 technicians active today
Mini roster: avatar + name + status for each
1 on leave · 1 off schedule
Click through to /team/schedule

Upcoming Leave

Next 14 days
Sarah H. — PTO — July 10-12
Derek O. — Sick — July 8
Click through to /hr/leave

Expiring Certifications

Certs expiring in next 60 days
Mike C. — HVAC License — expires Aug 15
Red if < 30 days, amber if 30-60 days
Click through to /hr/certifications

Recent Invoices (RoundTrip only)

Last 5 invoices: client name, amount, status (Sent/Paid/Overdue)
Hidden if RoundTrip not connected

4.1.3 Empty States

Each widget has a helpful empty state when no data exists:

Revenue MTD with no data: "No revenue recorded yet. Add your first entry in Financials."
Open Tickets with no RoundTrip: "Connect RoundTrip to see your open tickets here. [Connect RoundTrip →]"

Module 2 — Financial Overview

Routes: /financials/*

4.2.1 Revenue

Revenue list view (/financials/revenue)

Table: Date | Source | Client | Description | Amount | Type
Type: RoundTrip Job (auto) or Manual Entry
Filter: by month, by source, by client
Sort: by date (default), amount, client
Add manual revenue entry button (top right)

Add Manual Revenue (modal/drawer)

Fields: Date, Description, Client (optional), Amount, Category (Service, Materials, Other), Recurring (toggle)
Recurring: Monthly/Weekly — creates future entries automatically

4.2.2 Expenses

Expense list view (/financials/expenses)

Table: Date | Category | Description | Amount | Recurring
Filter: by month, by category
Add expense button (top right)

Expense categories: Payroll, Rent/Mortgage, Utilities, Insurance, Vehicle/Fleet, Materials/Parts, Marketing, Software/Subscriptions, Professional Services, Other

Add Expense (modal/drawer)

Fields: Date, Category, Description, Amount, Receipt (file upload, optional), Recurring (toggle)
Recurring: Daily/Weekly/Monthly/Annual — creates future entries

4.2.3 P&L Overview

P&L view (/financials/overview)

Month selector (default: current month)
Revenue section: total + breakdown by source
Expenses section: total + breakdown by category
Gross Profit = Revenue - Expenses
Gross Margin % = Gross Profit / Revenue
Simple bar chart: Revenue vs Expenses by month (last 12 months)
Export to CSV button

4.2.4 Accounts Receivable

AR view (/financials/ar)

Pulled from RoundTrip invoices with status Sent or Overdue
Table: Invoice # | Client | Date Sent | Amount | Days Outstanding | Status
Aging buckets: Current (0-30) | Late (31-60) | Overdue (61-90) | Seriously Overdue (90+)
Color coding: green → amber → red → dark red by age
Total outstanding shown at top
If RoundTrip not connected: prompt to connect or enter manually

Module 3 — Team Management

Routes: /team/*

4.3.1 Team Roster

Roster view (/team/roster)

Card grid or table toggle
Each employee: avatar, name, role, employment type, status (Active/Inactive)
Filter: by role, by status
Click employee → profile in HR module
Add team member button → creates employee record in HR module

Sync with RoundTrip:

If RoundTrip connected, Waypoint technicians/dispatchers appear automatically
Owner can add non-RoundTrip employees (admin staff, office manager)
Sync is one-way: RoundTrip → Waypoint (not the reverse)

4.3.2 Weekly Schedule View

Schedule view (/team/schedule)

Week view: employees as rows, days as columns
Cells show: working / on leave / off
Current week default, navigate forward/backward
Leave entries pulled from HR module
Working days pulled from employee record (work schedule)
Color coding: blue = working, amber = partial day, grey = off, red = leave

Module 4 — HR Lite

Routes: /hr/*

4.4.1 Employee List

Employee list (/hr/employees)

Table: Name | Role | Employment Type | Start Date | PTO Balance | Status
Filter: by role, by employment type, by status
Add employee button

4.4.2 Employee Profile

Profile page (/hr/employees/:id)

Tabs:

Overview — contact info, emergency contact, role, employment type, start date, work schedule
Certifications — list of certs: name, issuing body, issue date, expiry date, status (Valid/Expiring/Expired), file attachment
Skills — tag list of skills/competencies (editable)
Leave — PTO balance, leave history, pending requests
Performance — review history, current goals
Documents — employment contract, I-9, W-4, other attachments
Notes — internal notes (owner/admin only)

Add Employee form:

Personal: First name, last name, email, phone, address, emergency contact name + phone
Employment: Role, employment type (Full-time/Part-time/Contractor), start date, work schedule (Mon-Fri default, configurable)
HR: Initial PTO balance

4.4.3 Leave Management

Leave calendar (/hr/leave)

Month calendar view showing all employee leave
Color coded by employee
Toggle: calendar view / list view
Filter: by employee, by leave type

Leave request flow:

Manager creates leave request on behalf of employee (v1 — no employee self-service portal)
Sets: employee, leave type, start date, end date, notes
Status: Approved (default) / Pending / Denied
Leave deducted from PTO balance automatically (for PTO type)
Leave appears on Team Schedule and Dashboard widget

Leave types: PTO, Sick, Personal, Unpaid, Holiday

PTO Management:

PTO balance per employee: accrued, used, remaining
Manual adjustment (add/subtract with note)
Accrual rules: manual entry in v1 (automatic accrual in v2)

4.4.4 Certification Tracker

Certifications view (/hr/certifications)

All certifications across all employees in one view
Table: Employee | Certification | Expiry Date | Status | Days Until Expiry
Filter: by status (Valid/Expiring/Expired), by employee
Sort: by expiry date (default)
Export to CSV

Expiry alerts:

Dashboard widget shows certs expiring in 60 days
In-app notification at 90, 60, 30, 14, 7 days before expiry
Email notification to WaypointAdmin at 30 days before expiry

Module 5 — Document & Knowledge Management

Routes: /documents/*

4.5.1 Document Library

Library view (/documents/library)

Left panel: folder tree (owner-defined hierarchy)
Right panel: document list for selected folder
Document list: Name | Type | Size | Last Modified | Modified By
Upload button (top right) — drag and drop supported
Create folder button

Default folder structure (created on signup):

📁 Company
  📁 Policies
  📁 SOPs
  📁 Templates
📁 HR
  📁 Employee Documents
  📁 Job Descriptions
📁 Financial
  📁 Contracts
  📁 Insurance
📁 Legal

Document actions (right-click or context menu):

Preview (PDF, images)
Download
Rename
Move to folder
Upload new version
View version history
Delete (soft delete — recoverable for 30 days)

Version history:

Each upload of a file with the same name creates a new version
Previous versions accessible via version history drawer
Shows: version number, upload date, uploaded by, file size

Access control:

WaypointAdmin: full access to all folders
WaypointViewer: read-only access to designated folders (configurable per folder)

Storage limits:

Starter: 5GB
Standard: 20GB
Professional: 100GB

4.5.2 Knowledge Base

Knowledge base (/documents/knowledge)

Article list view: title, category, last updated, author
Categories: owner-defined tags
Search: full-text search across all articles
Create article button

Article editor:

Rich text editor (headings, bold, italic, lists, code blocks, images, links)
Auto-save every 30 seconds
Published / Draft status
Version history (last 10 versions)

Article features:

Table of contents auto-generated from headings
Related articles (manual linking)
Last reviewed date + reviewer

5. Authentication & Authorization

User navigates to traxswaypoint.app
Redirected to Entra External ID CIAM login
Enters email + password (or clicks "Sign in with Microsoft" if enabled)
Entra issues JWT with Waypoint app roles
Waypoint API validates JWT — reads WaypointAdmin or WaypointViewer role
TenantScopingBehavior resolves TenantId from JWT oid claim
User lands on /dashboard

5.2 Roles

Role	Permissions
`WaypointAdmin`	Full access — create, read, update, delete across all modules
`WaypointViewer`	Read-only access — cannot create, edit, or delete anything

5.3 New User Invitation

WaypointAdmin invites new users from Settings → Team
Same GraphUserService provisioning flow as RoundTrip
New user receives welcome email via SendGrid
Assigned WaypointAdmin or WaypointViewer role

6. RoundTrip Integration Specification

6.1 Connection Setup

WaypointAdmin goes to Settings → Integrations → RoundTrip
Clicks "Connect RoundTrip"
Authenticates with their RoundTrip credentials (same Entra account — auto-connected if same tenant)
Waypoint stores the TenantId linkage in its database
Integration status shows "Connected" with last sync timestamp

6.2 Data Endpoints (Command Center API)

All RoundTrip data is accessed via the Command Center API — Waypoint never calls RoundTrip API directly.

Waypoint Widget	Command Center Endpoint	Cache TTL
Revenue MTD	`GET /v1/roundtrip/revenue?period=mtd`	15 min
Revenue YTD	`GET /v1/roundtrip/revenue?period=ytd`	15 min
Open Tickets	`GET /v1/roundtrip/tickets/open`	5 min
Recent Invoices	`GET /v1/roundtrip/invoices/recent`	15 min
Technician List	`GET /v1/roundtrip/team`	60 min
AR Aging	`GET /v1/roundtrip/ar/aging`	15 min

6.3 Disconnected State

If RoundTrip is not connected or the API call fails:

Widgets that require RoundTrip data show a "Connect RoundTrip" prompt
All other widgets continue to function normally
No error states — graceful degradation

7. Notifications

7.1 In-App Notifications

Notification bell in top bar shows unread count. Notification types:

Trigger	Message	Priority
Certification expiring in 30 days	`{Name}`'s `{Cert}` expires in 30 days	High
Certification expiring in 7 days	`{Name}`'s `{Cert}` expires in 7 days	Critical
Certification expired	`{Name}`'s `{Cert}` has expired	Critical
Leave request pending approval	`{Name}` has requested leave `{dates}`	Normal
Document review date reached	`{Document}` is due for review	Normal

7.2 Email Notifications

Sent via SendGrid to WaypointAdmin:

Trigger	Frequency
Certification expiring	30 days, 7 days before expiry
Weekly team summary	Every Monday morning (opt-in)

8. Onboarding Flow

First-time user experience after registration:

Step 1 — Welcome screen "Welcome to Waypoint. Let's get your business set up."

Step 2 — Company details

Company name (pre-filled from registration)
Industry (dropdown)
Number of employees
Financial year start month

Step 3 — Connect RoundTrip (optional, skippable) "Connect your RoundTrip account to see your job revenue automatically."

Connect button or "Skip for now"

Step 4 — Add your first employee (optional, skippable) "Add your team to track leave, certifications, and performance."

Quick add form or "Skip for now"

Step 5 — Dashboard Land on the dashboard with a "Getting started" checklist widget:

Connect RoundTrip
Add your first expense
Upload a company document
Add an employee

Checklist widget disappears after all items are completed or dismissed.

9. Settings

9.1 Workspace Settings (`/settings/workspace`)

Company name
Industry
Logo upload
Financial year start
Default currency (USD only in v1)
Time zone

9.2 Integrations (`/settings/integrations`)

RoundTrip connection status + connect/disconnect
Future: QuickBooks, Xero (v2)

9.3 Billing (`/settings/billing`)

Current plan and price
Upgrade/downgrade
Payment method (Stripe Customer Portal link)
Invoice history
Cancel subscription

9.4 Team (`/settings/team`)

List of Waypoint users
Invite new user (email + role)
Remove user
Change user role

10. Technical Constraints

Constraint	Detail
Framework	React 19, Vite, TypeScript, Tailwind v4
State management	TanStack Query (server state) + Zustand (UI state)
Auth	MSAL — same pattern as RoundTrip
API client	Same `apiClient` pattern as RoundTrip
Component patterns	Same `features/` folder structure as RoundTrip
Rich text editor	TipTap (for Knowledge Base articles)
File uploads	Azure Blob Storage via signed URLs
Charts	Recharts (same as RoundTrip)
Design system	RoundTrip brand colors, DM Sans, Inter, JetBrains Mono

11. Design Principles

Waypoint follows the same design language as RoundTrip with one distinction:

RoundTrip — command center, high density, operational urgency
Waypoint — executive clarity, slightly more whitespace, data visualization emphasis

Both use the same brand colors and typography. Waypoint's tone is "calm confidence" — an owner looking at Waypoint should feel informed and in control, not rushed.

Key UI principles:

Every number on the dashboard should be instantly scannable — large, clear, no clutter
Empty states are helpful, not apologetic — they tell the user what to do next
Errors are specific — "Unable to load revenue data from RoundTrip — check your connection" not "Something went wrong"
Loading states are fast — skeleton screens, not spinners where possible

12. Document History

Version	Date	Author	Changes
1.0	July 2026	Pete Carroll	Initial draft

1. Overview​

2. User Personas​

Persona 1 — The Owner-Operator (Primary)​

Persona 2 — The Office Manager (Secondary)​

Persona 3 — The Standalone SMB Owner (Tertiary)​

3. Information Architecture​

3.1 Navigation Structure​

3.2 Global Navigation​

3.3 Traxs Suite Navigation​

4. Module Specifications​

Module 1 — Executive Dashboard​

4.1.1 Layout​

4.1.2 Widgets — v1 Fixed Set​

4.1.3 Empty States​

Module 2 — Financial Overview​

4.2.1 Revenue​

4.2.2 Expenses​

4.2.3 P&L Overview​

4.2.4 Accounts Receivable​

Module 3 — Team Management​

4.3.1 Team Roster​

4.3.2 Weekly Schedule View​

Module 4 — HR Lite​

4.4.1 Employee List​

4.4.2 Employee Profile​

4.4.3 Leave Management​

4.4.4 Certification Tracker​

Module 5 — Document & Knowledge Management​

4.5.1 Document Library​

4.5.2 Knowledge Base​

5. Authentication & Authorization​

5.1 Login Flow​

5.2 Roles​

5.3 New User Invitation​

6. RoundTrip Integration Specification​

6.1 Connection Setup​

6.2 Data Endpoints (Command Center API)​

6.3 Disconnected State​

7. Notifications​

7.1 In-App Notifications​

7.2 Email Notifications​

8. Onboarding Flow​

9. Settings​

9.1 Workspace Settings (/settings/workspace)​

9.2 Integrations (/settings/integrations)​

9.3 Billing (/settings/billing)​

9.4 Team (/settings/team)​

10. Technical Constraints​

11. Design Principles​

12. Document History​