RoundTrip Operations Manual
Welcome to the RoundTrip Operations Manual — the single source of truth for everything related to building, running, maintaining, and growing the RoundTrip platform.
This manual is maintained by the Traxs Group LLC team and is intended for all team members who work on or with RoundTrip in any capacity — whether you are writing code, managing infrastructure, designing the product, marketing to customers, or running the business.
:::info Keeping This Manual Current This manual is a living document. If you discover something is out of date, incorrect, or missing — update it. Every team member is responsible for keeping this documentation accurate. See the Contributing section below. :::
What is RoundTrip?
RoundTrip is a multi-tenant field service management SaaS platform built for the trades industry. It connects dispatchers, technicians, and business owners in a single platform — managing everything from job dispatch to invoicing, inventory, and reporting.
- Production: roundtrips.app
- Development: dev.roundtrips.app
- Public Docs: docs.roundtrips.app
Who This Manual Is For
This manual serves everyone on the RoundTrip team. Use the table below to find your role and the sections most relevant to you.
| Role | Description | Start Here |
|---|---|---|
| New Team Member | Just joined the team and getting oriented | Onboarding Path |
| Developer | Writing or reviewing code across the API or frontend | Development |
| DevOps / Infrastructure | Managing deployments, Azure resources, pipelines | Infrastructure & Operations |
| Designer | Working on the UI, brand, or design system | Design |
| Marketing | Managing brand, content, campaigns, and growth | Marketing |
| Leadership | Business operations, compliance, and strategy | Business |
| On-Call / Incident Response | Something is broken and you need answers fast | Runbooks |
What's in This Manual
🚀 Getting Started
Orientation for new team members, environment setup, and how to get up and running with RoundTrip quickly.
💻 Development
Everything developers need — frontend and backend architecture, coding standards, UI patterns, the Cyrus mediator pattern, and Azure CLI reference. This is the primary reference for day-to-day engineering work.
🧪 Testing
Testing strategy, tooling, and Playwright end-to-end testing guides. All tickets require tests before closing.
🎨 Design
The RoundTrip design system, component library, brand guidelines, and visual identity standards. All UI work should reference this section before implementation.
🏗 Infrastructure & Operations
Deployment architecture, Azure resource reference, Key Vault configuration, Cloudflare Pages setup, and pipeline documentation. If something is running in production, it's documented here.
⚙️ Services
Third-party service configuration and integration guides — SendGrid, Twilio, Stripe, and more.
📣 Marketing
Brand voice, content guidelines, social media, customer communications, and campaign documentation.
💼 Business
Business setup, legal structure, compliance, and operational processes for running Traxs Group LLC.
📝 Notes
Architecture reviews, decision records, and working notes that capture important decisions and their context.
New Team Member Onboarding
If you just joined the team, work through these steps in order:
Week 1 — Orientation
- Read this introduction in full
- Review the Design System and Brand Guidelines to understand the visual language
- Read the Development Introduction for an overview of the stack
- Set up your local development environment (see Development → Frontend / Backend coding guides)
- Get access to all required tools — ask your manager for Bitwarden vault access, Azure portal access, Linear, and ADO
Week 2 — Going Deeper
- Read the Frontend Structure and UI Patterns guides
- Read the Backend Coding guide — pay particular attention to the Mediator pattern and domain event architecture
- Review Infrastructure & Operations to understand how production is structured
- Make your first contribution — pick up a ticket in Linear, follow the branch/commit conventions, and open a PR
Tool Access Checklist
- Bitwarden (team vault access)
- Azure Portal (Traxs Group LLC account)
- Azure DevOps (pipelines and repos)
- Linear (issue tracking)
- Cloudflare (DNS and Pages)
- SendGrid
- Stripe Dashboard
- ops.roundtrips.app (this site — Cloudflare Access)
On-Call Quick Reference
If something is broken in production, start here:
| Symptom | Go To |
|---|---|
| Site won't start / SiteStartupCancelled | App Service Runbook |
| Emails not sending | Check SendGrid__ApiKey App Service setting and Key Vault reference |
| User invitations failing | Check GraphApi__ClientSecret App Service setting — may need Key Vault stop/start |
| Hangfire jobs failing | Check Hangfire dashboard — requeue failed jobs after fixing root cause |
| Dev site serving stale content | Check Cloudflare Pages branch mapping for roundtrip-dev project |
| Key Vault secret not resolving | Full stop → start App Service (not restart) after updating secrets |
Contributing
This manual only stays useful if it stays current. Every team member is expected to update documentation when they discover something is wrong or missing.
To update a page:
- Clone the
roundtrip-internalrepository - Create a branch:
docs/description-of-change - Make your changes in the relevant markdown file
- Open a PR against
main— no approval required for documentation changes - Merge and the ops site auto-deploys via ADO pipeline
Guidelines:
- Write for someone who doesn't have your context — assume the reader is new
- Prefer short sentences and tables over long paragraphs
- Add runbook entries any time you solve a production incident
- Never commit secrets, passwords, or API keys to this repo — those live in Bitwarden
Technology at a Glance
| Layer | Technology |
|---|---|
| API | .NET 10, FastEndpoints, EF Core, Dapper, Hangfire, SignalR |
| Frontend | React 19, Vite, TypeScript, Tailwind v4, TanStack Query, MSAL |
| Auth | Microsoft Entra External ID CIAM |
| Database | Azure SQL Server |
| Infrastructure | Azure App Service, Azure Key Vault, Azure Blob Storage |
| Frontend Hosting | Cloudflare Pages |
| CI/CD | Azure DevOps, self-hosted agent |
| Issue Tracking | Linear |
| Secrets Management | Bitwarden + Azure Key Vault |
RoundTrip is a product of Traxs Group LLC. This manual is confidential and intended for internal use only.