TECH STACK BENEFITS ANALYSIS
Roundtrip · A Traxs Company Product · Version 1.0 · March 2026
Technology selection, justification, and trade-off analysis for the Roundtrip multi-tenant SaaS platform.
EXECUTIVE SUMMARY
Overview
This document provides a comprehensive analysis of the technology stack selected for Roundtrip, Traxs Company's multi-tenant field service management SaaS platform. Each technology decision is justified against Roundtrip's specific requirements: multi-tenancy, field service workflows, real-time dispatching, AI-powered route optimization, and offline-capable technician mobile experiences.
The stack builds on Pete's established .NET and React expertise while introducing several additions critical for production-grade SaaS: Keycloak for identity management (replacing the costly Duende IdentityServer), Redis for distributed caching, SignalR for real-time dispatch notifications, Hangfire for background job processing, and QuestPDF for invoice/report generation. Items from the original requirements that are redundant or superseded have been removed with justification.
Key Decision: Keycloak over Duende IdentityServer
Duende IdentityServer requires a commercial license starting at $1,500/year for production SaaS use. For a startup, this cost is avoidable. Keycloak (Apache 2.0, free, open source) provides equivalent or superior functionality including multi-tenant realm support, built-in admin UI, SSO, MFA, and social login — all critical for Roundtrip. Keycloak is containerized and slots directly into the Docker Compose development workflow.
Key Addition: Dapper (supplemental to EF Core)
EF Core is recommended for standard CRUD operations with tenant isolation via Global Query Filters. However, Roundtrip's reporting and analytics queries (ticket volume by week, technician utilization rates, revenue per service type) benefit from raw SQL via Dapper. Both coexist in the codebase — EF Core for transactional writes and simple reads, Dapper for complex reporting queries.
Key Addition: NetArchTest
A long-lived SaaS product is at risk of architectural drift — developers accidentally bypassing Clean Architecture boundaries as the codebase grows. NetArchTest enforces these boundaries automatically in CI, catching violations early. This is a low-cost, high-value addition for a project of this scope.
COMPLETE STACK AT A GLANCE
Full Technology Inventory
| Category | Technology | Version | Decision |
|---|---|---|---|
| Backend Framework | ASP.NET Core 9.0+ | 9.0+ | ✓ Recommended |
| API Style | FastEndpoints | 5.x+ | ✓ Recommended |
| Identity & Auth (Server) | Keycloak | 25+ | ✓ Recommended |
| Identity (Application) | ASP.NET Core Identity | 9.0+ | ✓ Recommended |
| Frontend Framework | React | 19+ | ✓ Recommended |
| UI Component Library | Material UI (MUI) | v7 | ✓ Recommended |
| Language (Backend) | C# 13 | 13 | ✓ Recommended |
| Language (Frontend) | TypeScript | 5.x+ | ✓ Recommended |
| ORM | Entity Framework Core | 9.0+ | ✓ Recommended |
| Database | SQL Server | 2022+ | ✓ Recommended |
| Query Performance | Dapper | 2.x+ | ✓ Recommended (supplemental) |
| Caching | Redis (via StackExchange.Redis) | 7.x+ | ✓ Recommended |
| CQRS / Mediator | MediatR | 12.x+ | ✓ Recommended |
| Specification Pattern | Ardalis.Specification | 8.x+ | ✓ Recommended |
| Validation | FluentValidation | 11.x+ | ✓ Recommended |
| Real-Time Notifications | SignalR | 9.0+ (included in ASP.NET Core) | ✓ Recommended |
| Background Jobs | Hangfire | 1.8.x+ | ✓ Recommended |
| Email Delivery | SendGrid (via Twilio) | API v3 | ✓ Recommended |
| SMS Notifications | Twilio SMS | API v2010 | ✓ Recommended |
| Mapping (Frontend) | Leaflet.js + React Leaflet | 1.9.x + 4.x | ✓ Recommended |
| Geocoding | Nominatim / OpenRouteService | API v1 | ✓ Recommended |
| AI / Route Optimization | n8n + Ollama | n8n 1.x / Ollama 0.x | ✓ Recommended |
| AI / Tenant Assistant | Ollama (qwen2.5-coder:14b / LLaVA:13b) | Models: latest stable | ✓ Recommended |
| Containerization | Docker + Docker Compose | Docker 25+ | ✓ Recommended |
| API Documentation | Scalar (via FastEndpoints integration) | Latest | ✓ Recommended |
| Logging | Serilog | 4.x+ | ✓ Recommended |
| Observability | OpenTelemetry + Seq (dev) / Application Insights (prod) | OTel 1.x | ✓ Recommended |
| Unit / Integration Testing | xUnit + FluentAssertions + Testcontainers | Latest stable | ✓ Recommended |
| Architecture Testing | NetArchTest | Latest | ✓ Recommended (new addition) |
| State Management | TanStack Query (React Query) | 5.x+ | ✓ Recommended |
| Client-Side State | Zustand | 4.x+ | ✓ Recommended (new addition) |
| HTTP Client | Axios | 1.x+ | ✓ Recommended |
| Charts / Analytics | Recharts | 2.x+ | ✓ Recommended |
| PDF Generation | QuestPDF | 2024.x+ | ✓ Recommended (new addition) |
| CI/CD | GitHub Actions | N/A (SaaS) | ✓ Recommended |
| Swagger UI | (Replaced by Scalar) | — | ✗ Removed |
01 — CORE BACKEND
Core Backend
Backend Framework
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| ASP.NET Core 9.0+ | Microsoft's flagship web framework — cross-platform, high-performance, and ideally suited for multi-tenant SaaS. | 9.0+ | ✓ Recommended |
Microsoft's flagship web framework — cross-platform, high-performance, and ideally suited for multi-tenant SaaS. ASP.NET Core 9 introduces improved minimal API features, enhanced OpenAPI support, and better AOT compilation performance. Its dependency injection, middleware pipeline, and tenant-aware scoping make it the natural backbone for Roundtrip.
| Advantages | Disadvantages |
|---|---|
| ✓ Industry-leading throughput (top 5 TechEmpower plaintext benchmarks) ✓ Rich multi-tenancy support via scoped services and DI ✓ Excellent tooling: Visual Studio, Rider, VS Code ✓ Microsoft LTS support ensures long-term stability ✓ Strong community, extensive ecosystem of packages | ✗ Windows-centric ecosystem historically (though now fully cross-platform) ✗ More verbose than some alternatives like FastAPI |
Alternatives considered: Express.js (Node) — faster prototyping but weaker typing. Django — more opinionated. Spring Boot — Java ecosystem, similar capability.
API Style
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| FastEndpoints | FastEndpoints implements the REPR (Request-Endpoint-Response) pattern, replacing traditional MVC controllers with focused, single-purpose endpoint classes. | 5.x+ | ✓ Recommended |
FastEndpoints implements the REPR (Request-Endpoint-Response) pattern, replacing traditional MVC controllers with focused, single-purpose endpoint classes. This aligns perfectly with Clean Architecture and DDD, keeping each API surface small and testable. Benchmarks consistently show FastEndpoints outperforming MVC controllers by 30–40% throughput.
| Advantages | Disadvantages |
|---|---|
| ✓ REPR pattern enforces single responsibility ✓ Significantly faster than MVC controllers (benchmarked) ✓ Integrated validation pipeline with FluentValidation ✓ Built-in OpenAPI/Swagger support ✓ Cleaner separation of concerns than controller-based APIs | ✗ Less familiar to developers from MVC backgrounds ✗ Smaller community than traditional MVC ✗ Some advanced MVC features require workarounds |
Alternatives considered: ASP.NET MVC Controllers — more familiar, widely documented, but bulkier. Minimal APIs — built-in, lightweight, but lacks FastEndpoints' conventions and tooling.
Identity & Auth (Server)
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Keycloak | Keycloak is the recommended identity provider for Roundtrip, replacing Duende IdentityServer (which now requires a commercial license starting at $1,500+/year for production). | 25+ | ✓ Recommended |
Keycloak is the recommended identity provider for Roundtrip, replacing Duende IdentityServer (which now requires a commercial license starting at $1,500+/year for production). As a multi-tenant SaaS, Roundtrip requires robust OAuth 2.0/OIDC, per-tenant user realms, SSO, and social login — all of which Keycloak provides out of the box with zero licensing cost. Deploying via Docker fits the containerized architecture.
| Advantages | Disadvantages |
|---|---|
| ✓ Fully open source (Apache 2.0) — no licensing fees ✓ Built-in admin UI for tenant realm management ✓ OAuth 2.0, OIDC, SAML 2.0 support out of the box ✓ SSO, MFA, social login included ✓ Battle-tested at enterprise scale ✓ Runs in Docker — fits containerized deployment | ✗ Java-based — separate runtime from .NET stack ✗ Steeper initial configuration vs. embedded solutions ✗ Admin UI less developer-friendly than code-first options |
Alternatives considered: Duende IdentityServer — deeply .NET-integrated, code-first, but $1,500–$5,000+/year license. OpenIddict — free, .NET-native, code-first, less admin tooling. Auth0 — SaaS identity, easier setup but ongoing per-user cost.
Identity (Application)
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| ASP.NET Core Identity | Used alongside Keycloak for application-level user management — roles, claims, tenant membership, and authorization policies within the ASP. | 9.0+ | ✓ Recommended |
Used alongside Keycloak for application-level user management — roles, claims, tenant membership, and authorization policies within the ASP.NET Core app itself. Keycloak handles token issuance; ASP.NET Identity handles the application-layer user model and permission enforcement.
| Advantages | Disadvantages |
|---|---|
| ✓ Tight integration with EF Core and SQL Server ✓ Role-based and policy-based authorization built in ✓ Standard .NET DI integration ✓ Pairs naturally with Keycloak via JWT validation | ✗ Not a full IdP on its own — requires Keycloak for token issuance ✗ Requires careful design for multi-tenant row-level isolation |
Alternatives considered: Pure Keycloak-only (no ASP.NET Identity) — simpler but loses fine-grained in-app authorization flexibility.
02 — FRONTEND
Frontend
Frontend Framework
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| React | React 19 introduces the Actions API, use() hook, and improved server component integration — all relevant for a data-heavy field service dashboard. | 19+ | ✓ Recommended |
React 19 introduces the Actions API, use() hook, and improved server component integration — all relevant for a data-heavy field service dashboard. React's component model, massive ecosystem, and established patterns for complex UIs make it the right choice for Roundtrip's office and dispatcher interfaces.
| Advantages | Disadvantages |
|---|---|
| ✓ Largest frontend ecosystem — libraries for mapping, charts, tables, etc. ✓ React 19 Actions API simplifies async state mutations ✓ Component reusability across web and potential future React Native mobile app ✓ Enormous hiring pool and community resources ✓ React Query 5+ handles complex server-state perfectly for this domain | ✗ Not a full framework — requires assembling additional tools (router, state, etc.) ✗ React 19 features still maturing in ecosystem |
Alternatives considered: Next.js — adds SSR/SSG, good option if SEO matters for marketing pages. Vue 3 — gentler learning curve but smaller ecosystem. Angular — opinionated, good for large teams.
UI Component Library
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Material UI (MUI) | MUI v7 provides a comprehensive, accessible, and highly customizable component library. | v7 | ✓ Recommended |
MUI v7 provides a comprehensive, accessible, and highly customizable component library. Its theming system allows full alignment with Roundtrip's brand (blues, navies, custom typography). MUI's DataGrid component is particularly valuable for Roundtrip's ticket lists and inventory views, offering server-side pagination and filtering out of the box.
| Advantages | Disadvantages |
|---|---|
| ✓ Comprehensive component set covering 90%+ of UI needs ✓ Excellent accessibility (WCAG 2.1 compliant) ✓ Theming system maps cleanly to Roundtrip brand palette ✓ MUI X DataGrid is best-in-class for complex tabular data ✓ Active development, strong community | ✗ MUI X components (DataGrid Pro) require commercial license for advanced features ✗ Bundle size can be large without tree-shaking discipline ✗ Material Design aesthetic requires customization to feel truly branded |
Alternatives considered: Ant Design — feature-rich but heavier, Chinese-market focused. Shadcn/ui — composable, Tailwind-based, newer. Mantine — modern, good DX, smaller community.
Language (Backend)
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| C# 13 | C# 13 continues. | 13 | ✓ Recommended |
C# 13 continues .NET's trajectory toward expressiveness and performance. Features like primary constructors, collection expressions, and pattern matching improvements reduce boilerplate in domain model definitions. Strong static typing catches multi-tenant data isolation bugs at compile time rather than runtime.
| Advantages | Disadvantages |
|---|---|
| ✓ Strongest static typing in the web backend space ✓ Records, primary constructors reduce domain model boilerplate ✓ Rich LINQ makes complex queries expressive ✓ Nullable reference types eliminate entire classes of null-ref bugs ✓ Excellent IDE tooling in Rider and Visual Studio | ✗ Steeper learning curve than JavaScript/Python ✗ Verbose compared to some modern languages |
Alternatives considered: F# — functional-first, excellent for domain modeling but smaller community. Go — excellent performance but weaker ORM/EF story.
Language (Frontend)
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| TypeScript | TypeScript provides compile-time type safety for the React frontend, enabling shared type contracts with the backend API (via OpenAPI-generated clients). | 5.x+ | ✓ Recommended |
TypeScript provides compile-time type safety for the React frontend, enabling shared type contracts with the backend API (via OpenAPI-generated clients). For a multi-tenant SaaS where tenant context must be consistently applied, catching missing tenantId properties at build time rather than runtime is a material risk reduction.
| Advantages | Disadvantages |
|---|---|
| ✓ Catches API contract mismatches at build time ✓ OpenAPI → TypeScript type generation keeps frontend/backend in sync ✓ React ecosystem is predominantly TypeScript-first ✓ Excellent IDE support in VS Code and WebStorm | ✗ Build step required ✗ Configuration complexity (tsconfig) ✗ Some JavaScript libraries still lack first-class TypeScript support |
Alternatives considered: Plain JavaScript — faster to start but poor maintainability at scale.
03 — DATA & CACHING
Data & Caching
ORM
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Entity Framework Core | EF Core 9 is the natural ORM for. | 9.0+ | ✓ Recommended |
EF Core 9 is the natural ORM for .NET SaaS applications. Its Global Query Filters are the definitive mechanism for multi-tenant row-level isolation — defining a TenantId filter once on the DbContext ensures all queries are automatically scoped, preventing accidental cross-tenant data leakage. Migrations make schema evolution manageable.
| Advantages | Disadvantages |
|---|---|
| ✓ Global Query Filters enable transparent tenant isolation ✓ Code-first migrations for controlled schema evolution ✓ Excellent LINQ integration for expressive queries ✓ Ardalis.Specification pattern keeps repository logic clean and reusable ✓ Strong community and Microsoft backing | ✗ Can generate suboptimal SQL for complex queries — requires Dapper fallback for hot paths ✗ N+1 problems require discipline (use .Include() or split queries) ✗ Lazy loading is a footgun — should be disabled by default |
Alternatives considered: Dapper — raw SQL, excellent performance, less abstraction. Used alongside EF Core for reporting queries. NHibernate — mature but largely superseded by EF Core in .NET ecosystem.
Database
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| SQL Server | SQL Server 2022 provides the ACID compliance, row-level security, and JSON support required for Roundtrip's multi-tenant data model. | 2022+ | ✓ Recommended |
SQL Server 2022 provides the ACID compliance, row-level security, and JSON support required for Roundtrip's multi-tenant data model. Its integration with EF Core is best-in-class. The hybrid tenancy strategy (shared schema for small tenants, dedicated database for enterprise clients) is straightforward to implement with SQL Server's flexible connection string routing.
| Advantages | Disadvantages |
|---|---|
| ✓ Best-in-class EF Core integration ✓ Row-Level Security (RLS) as defense-in-depth for tenant isolation ✓ JSON column support for flexible metadata storage ✓ Temporal tables for audit trails (service history) ✓ Excellent tooling: SSMS, Azure Data Studio, Rider | ✗ Commercial licensing for production (though Developer edition is full featured) ✗ Heavier resource footprint than PostgreSQL ✗ Windows heritage (runs on Linux but Windows-optimized historically) |
Alternatives considered: PostgreSQL — free, open source, excellent performance, strong JSON support. Viable alternative if licensing cost is a concern. Azure SQL — managed SQL Server, removes infrastructure burden.
Query Performance
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Dapper | Dapper is recommended as a supplemental data access library for Roundtrip's reporting, dashboard aggregations, and any complex queries where EF Core generates suboptimal SQL. | 2.x+ | ✓ Recommended (supplemental) |
Dapper is recommended as a supplemental data access library for Roundtrip's reporting, dashboard aggregations, and any complex queries where EF Core generates suboptimal SQL. Using both gives the best of both worlds: EF Core for standard CRUD with tenant isolation, Dapper for performance-critical read paths.
| Advantages | Disadvantages |
|---|---|
| ✓ Near-raw SQL performance ✓ Simple, predictable SQL output — no ORM surprises ✓ Maps results to strongly typed objects ✓ Lightweight — no configuration overhead | ✗ No built-in tenant isolation — must manually include TenantId in every query ✗ No migrations, no schema management ✗ More boilerplate for complex mappings |
Alternatives considered: EF Core's raw SQL (FromSqlRaw) — acceptable for simple cases. Not recommended as a full Dapper replacement.
Caching
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Redis (via StackExchange.Redis) | Redis is essential for Roundtrip's multi-tenant architecture for three reasons: distributed session caching (tenant context across load-balanced instances), route calculation caching (Ollama/n8n route results are expensive to compute), and real-time rate limiting per tenant. | 7.x+ | ✓ Recommended |
Redis is essential for Roundtrip's multi-tenant architecture for three reasons: distributed session caching (tenant context across load-balanced instances), route calculation caching (Ollama/n8n route results are expensive to compute), and real-time rate limiting per tenant. IMemoryCache alone is insufficient for horizontally scaled deployments.
| Advantages | Disadvantages |
|---|---|
| ✓ Sub-millisecond latency for cached lookups ✓ Distributed — works across multiple API server instances ✓ Supports pub/sub (can supplement SignalR backplane) ✓ Rate limiting and sliding expiration built in ✓ ASP.NET Core IDistributedCache interface — swappable | ✗ Additional infrastructure component to manage ✗ SSPL licensing for Redis 7.4+ is not fully open source (consider Valkey/Garnet as alternatives) ✗ Memory is finite — requires eviction policy planning |
Alternatives considered: Valkey — open source Redis fork, Apache 2.0 licensed. Microsoft Garnet — high-performance Redis-compatible, MIT licensed, .NET-native.
04 — ARCHITECTURE PATTERNS
Architecture Patterns
CQRS / Mediator
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| MediatR | MediatR implements the Mediator pattern, enabling clean CQRS (Command Query Responsibility Segregation) separation. | 12.x+ | ✓ Recommended |
MediatR implements the Mediator pattern, enabling clean CQRS (Command Query Responsibility Segregation) separation. Commands mutate state (CreateTicketCommand), Queries read data (GetTechnicianRouteQuery). This decouples FastEndpoints from business logic, makes handlers individually testable, and enables pipeline behaviors for cross-cutting concerns like validation, logging, and tenant context injection.
| Advantages | Disadvantages |
|---|---|
| ✓ Clean separation of commands from queries ✓ Pipeline behaviors for validation, logging, caching ✓ Each handler is independently unit-testable ✓ Eliminates service layer fat interfaces ✓ Well-established pattern in .NET DDD communities | ✗ Adds indirection — can be confusing for developers unfamiliar with the pattern ✗ Performance overhead vs. direct service calls (negligible in practice) ✗ Overuse can lead to too many small handler files |
Alternatives considered: Direct service injection — simpler but harder to test and more tightly coupled. Wolverine — newer, higher-performance mediator alternative.
Specification Pattern
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Ardalis.Specification | The Specification pattern encapsulates query logic into reusable, composable specification classes. | 8.x+ | ✓ Recommended |
The Specification pattern encapsulates query logic into reusable, composable specification classes. For Roundtrip, this means OpenTicketsForTenantSpec, OverdueInventorySpec, and TechniciansByRegionSpec are defined once and reused across handlers. This prevents query logic from leaking into handlers and keeps EF Core queries composable and testable.
| Advantages | Disadvantages |
|---|---|
| ✓ Reusable, composable query logic ✓ Specifications are unit-testable in isolation ✓ Prevents EF Core query logic from spreading across handlers ✓ Steve Smith (Ardalis) is a Microsoft MVP — well-maintained | ✗ Additional abstraction layer ✗ Minor learning curve for the pattern |
Alternatives considered: Repository pattern without specifications — simpler but leads to query duplication. Raw LINQ in handlers — flexible but untestable.
Validation
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| FluentValidation | FluentValidation provides expressive, testable validation rules as C# classes, integrated with FastEndpoints' validation pipeline. | 11.x+ | ✓ Recommended |
FluentValidation provides expressive, testable validation rules as C# classes, integrated with FastEndpoints' validation pipeline. Field service workflows require complex validation — a service ticket must have a valid address, an assigned technician must exist in the tenant, inventory items must have sufficient quantity. FluentValidation handles all of this cleanly.
| Advantages | Disadvantages |
|---|---|
| ✓ Validation rules are separate classes — independently testable ✓ Integrates natively with FastEndpoints and MediatR pipeline ✓ Fluent, readable syntax for complex rules ✓ Async validation supported (DB lookups) ✓ Well-established in .NET community | ✗ Separate classes can feel verbose for simple validations ✗ DataAnnotations simpler for trivial cases |
Alternatives considered: DataAnnotations — built-in, simpler, but not testable in isolation. Behavioral approach inside handlers — pragmatic but harder to reuse.
05 — REAL-TIME, BACKGROUND & NOTIFICATIONS
Real-Time, Background & Notifications
Real-Time Notifications
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| SignalR | Roundtrip requires real-time dispatcher dashboards — technician location updates, ticket status changes, and route modifications must push to browsers instantly. | 9.0+ (included in ASP.NET Core) | ✓ Recommended |
Roundtrip requires real-time dispatcher dashboards — technician location updates, ticket status changes, and route modifications must push to browsers instantly. SignalR provides WebSocket-based real-time communication with graceful fallback to Server-Sent Events and long-polling. It integrates directly with ASP.NET Core and supports tenant-aware hub connections.
| Advantages | Disadvantages |
|---|---|
| ✓ Built into ASP.NET Core — no additional server ✓ WebSocket first, with automatic fallback ✓ Group-based messaging maps naturally to tenant isolation ✓ Works with Redis backplane for multi-instance deployments ✓ Client libraries for React (signalr-js) | ✗ Stateful connections add server complexity at scale ✗ Requires Redis backplane for load-balanced deployments ✗ Not ideal for high-frequency telemetry (use dedicated IoT protocols for that) |
Alternatives considered: Server-Sent Events (SSE) — simpler, one-way. WebSockets raw — more control, more work. Ably / Pusher — managed real-time, removes infrastructure burden at cost.
Background Jobs
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Hangfire | Roundtrip requires reliable background processing for: invoice generation, SMS/email notifications, route optimization calls to n8n/Ollama, inventory reorder alerts, and nightly reconciliation jobs. | 1.8.x+ | ✓ Recommended |
Roundtrip requires reliable background processing for: invoice generation, SMS/email notifications, route optimization calls to n8n/Ollama, inventory reorder alerts, and nightly reconciliation jobs. Hangfire provides persistent job storage in SQL Server (reusing existing infrastructure), automatic retries, and a built-in dashboard for operations monitoring — critical for a multi-tenant SaaS where jobs must be observable.
| Advantages | Disadvantages |
|---|---|
| ✓ Built-in web dashboard for job monitoring and retries ✓ Persistent storage in SQL Server — no extra database ✓ Fire-and-forget, delayed, recurring, and continuation jobs ✓ Automatic retry with exponential backoff ✓ Integrates with ASP.NET Core DI — tenant context injectable | ✗ LGPL license — commercial use has restrictions for Hangfire Pro features ✗ SQL Server polling adds some latency vs. message queue approach ✗ Requires careful job design for idempotency in multi-tenant context |
Alternatives considered: Quartz.NET — more complex scheduling, no built-in dashboard. Azure Service Bus — better for high-volume distributed scenarios. Mass Transit — full message bus, overkill for initial implementation.
Email Delivery
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| SendGrid (via Twilio) | Roundtrip sends transactional emails (invoices, quotes, appointment confirmations, technician notifications). | API v3 | ✓ Recommended |
Roundtrip sends transactional emails (invoices, quotes, appointment confirmations, technician notifications). SendGrid's reliable delivery infrastructure, bounce handling, and per-tenant template support makes it the right choice. The SendGrid .NET SDK integrates well with Hangfire background jobs for fire-and-forget email delivery.
| Advantages | Disadvantages |
|---|---|
| ✓ 99.9%+ email deliverability SLA ✓ Per-tenant email templates and from-address configuration ✓ Detailed delivery analytics and bounce management ✓ Official .NET SDK ✓ Generous free tier (100 emails/day) | ✗ Commercial — cost scales with volume ✗ Dependency on third-party SaaS ✗ Twilio acquisition has raised some community concerns about pricing direction |
Alternatives considered: Mailgun — strong alternative, developer-friendly. MailKit (self-hosted SMTP) — free but delivery reputation management is complex. Postal — self-hosted, full control.
SMS Notifications
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Twilio SMS | Field service technicians and customers both benefit from SMS notifications — on-my-way alerts, appointment reminders, and invoice delivery via text. | API v2010 | ✓ Recommended |
Field service technicians and customers both benefit from SMS notifications — on-my-way alerts, appointment reminders, and invoice delivery via text. Twilio is the industry standard for programmatic SMS, with a reliable .NET SDK and per-country coverage that matters for multi-region tenants.
| Advantages | Disadvantages |
|---|---|
| ✓ Industry-standard reliability for SMS delivery ✓ Official .NET SDK ✓ Two-way messaging (customers can reply) ✓ MMS support for sending photos/invoices ✓ Per-number or per-tenant sending configuration | ✗ Per-message pricing adds up at scale ✗ Number provisioning overhead per tenant ✗ Regulatory compliance (TCPA/opt-out) requires implementation discipline |
Alternatives considered: AWS SNS — cheaper at scale but less developer-friendly. Vonage (Nexmo) — competitive alternative. Plivo — lower cost, good coverage.
06 — MAPPING & GEOLOCATION
Mapping & Geolocation
Mapping (Frontend)
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Leaflet.js + React Leaflet | Roundtrip's map view is a hero feature — technicians see their daily route, dispatchers see all active jobs. | 1.9.x + 4.x | ✓ Recommended |
Roundtrip's map view is a hero feature — technicians see their daily route; dispatchers see all active jobs. Leaflet is the leading open-source mapping library, and React Leaflet provides idiomatic React component wrappers. Using OpenStreetMap tiles keeps mapping completely free, with no Google Maps billing surprises as the tenant base grows.
| Advantages | Disadvantages |
|---|---|
| ✓ Fully open source — no per-tile or per-request billing ✓ React Leaflet provides clean component abstractions ✓ Supports custom markers (technician avatars, ticket status pins) ✓ Polyline routing for route visualization ✓ Works offline with cached tiles (relevant for PWA technician apps) | ✗ OpenStreetMap data quality varies by region ✗ Less polished out-of-the-box than Google Maps ✗ Geocoding requires separate service (Nominatim or Photon) |
Alternatives considered: Google Maps JS API — more polished, but per-request billing scales poorly. Mapbox GL JS — excellent, generous free tier, MIT SDK. Azure Maps — good fit if Azure-hosted.
Geocoding
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Nominatim / OpenRouteService | Address geocoding (converting client addresses to lat/lng for map pins) and route optimization are core to Roundtrip. | API v1 | ✓ Recommended |
Address geocoding (converting client addresses to lat/lng for map pins) and route optimization are core to Roundtrip. Nominatim provides free OSM-based geocoding. OpenRouteService provides free routing and isochrone APIs. Both can be self-hosted for data sovereignty, and both have generous free API tiers.
| Advantages | Disadvantages |
|---|---|
| ✓ Free and open source — no per-request charges ✓ Can be self-hosted for complete data control ✓ OpenRouteService provides driving distance matrices for multi-stop route optimization ✓ Integrates with Leaflet naturally | ✗ Nominatim quality lower than Google Maps for some regions ✗ Self-hosting requires operational overhead ✗ Rate limits on public APIs require self-hosting at scale |
Alternatives considered: Google Maps Geocoding API — best quality, per-request billing. HERE Geocoding — commercial, strong quality. Mapbox Geocoding — free tier, good quality.
07 — AI & AUTOMATION
AI & Automation
AI / Route Optimization
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| n8n + Ollama | Per the Requirements document, Roundtrip uses n8n and Ollama to automatically generate the most efficient technician route for each day. | n8n 1.x / Ollama 0.x | ✓ Recommended |
Per the Requirements document, Roundtrip uses n8n and Ollama to automatically generate the most efficient technician route for each day. n8n provides the workflow automation layer (trigger on schedule, call Ollama, write result back to Roundtrip API). Ollama enables local LLM inference — no per-token cloud API costs, full data sovereignty, and no tenant data leaving the infrastructure. This is a key competitive differentiator.
| Advantages | Disadvantages |
|---|---|
| ✓ Zero per-query cost — runs locally on your infrastructure ✓ Complete data sovereignty — no tenant data to third-party AI APIs ✓ n8n workflow editor enables non-developer route logic adjustment ✓ Ollama supports multiple models — can swap/upgrade without code changes ✓ Aligns with existing Traxs tooling decisions | ✗ Requires GPU-capable hardware for best performance ✗ Model quality lower than GPT-4 / Claude for complex reasoning ✗ n8n requires its own infrastructure and maintenance ✗ Workflow reliability at scale requires monitoring |
Alternatives considered: OpenAI API — superior model quality but per-token cost and data leaves infrastructure. AWS Bedrock — managed, compliance-friendly, but cloud-only and per-token cost. Direct algorithmic routing (Google OR-Tools) — deterministic, no AI, lower infrastructure cost.
AI / Tenant Assistant
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Ollama (qwen2.5-coder:14b / LLaVA:13b) | The Requirements document specifies an in-app AI assistant that answers tenant-specific questions ('What was installed at 142 Riverside Dr last year?', 'What parts are low stock for HVAC work?'). | Models: latest stable | ✓ Recommended |
The Requirements document specifies an in-app AI assistant that answers tenant-specific questions ('What was installed at 142 Riverside Dr last year?', 'What parts are low stock for HVAC work?'). Ollama with a fine-tuned or RAG-augmented local model keeps these queries private and free. LLaVA handles multimodal queries (part photos from technicians). This also aligns with Traxs Company's approved model catalog.
| Advantages | Disadvantages |
|---|---|
| ✓ Tenant data never leaves local infrastructure ✓ No per-query cost ✓ LLaVA enables photo-based part identification from technician uploads ✓ Approved models already evaluated by Traxs (Qwen2.5-Coder:14b, LLaVA:13b) ✓ RAG (Retrieval-Augmented Generation) via embeddings enables tenant-specific Q&A | ✗ Local model quality below GPT-4 for complex reasoning ✗ Requires vector database for RAG (e.g., pgvector or Qdrant) ✗ Context window limits require chunking strategy for large service histories |
Alternatives considered: Claude API (Anthropic) — superior reasoning, but per-token cost and data leaves infra. OpenAI GPT-4o — strongest quality, same concerns. Azure OpenAI — managed, compliance options, but still external.
08 — INFRASTRUCTURE & DEVOPS
Infrastructure & DevOps
Containerization
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Docker + Docker Compose | Docker containers ensure consistent environments from development through production. | Docker 25+ | ✓ Recommended |
Docker containers ensure consistent environments from development through production. Docker Compose orchestrates the full Roundtrip stack locally: ASP.NET Core API, React dev server, SQL Server, Redis, Keycloak, Hangfire, n8n, and Ollama. This directly aligns with Pete's existing OrbStack-based development workflow.
| Advantages | Disadvantages |
|---|---|
| ✓ Consistent dev/staging/prod environments ✓ docker compose up spins the entire stack ✓ Aligns with existing OrbStack/Mac development workflow ✓ Container images are portable across cloud providers ✓ Simplifies Keycloak and n8n deployment | ✗ Container orchestration complexity grows with scale ✗ Local GPU access for Ollama requires specific Docker configuration ✗ Kubernetes needed for production-scale orchestration |
Alternatives considered: Kubernetes — production-grade orchestration, overkill for initial launch. Podman — rootless, daemonless alternative to Docker.
API Documentation
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Scalar (via FastEndpoints integration) | Scalar is a modern replacement for Swagger UI, providing a beautiful, interactive API reference UI from OpenAPI 3. | Latest | ✓ Recommended |
Scalar is a modern replacement for Swagger UI, providing a beautiful, interactive API reference UI from OpenAPI 3.0 specs. FastEndpoints generates the OpenAPI spec automatically. Scalar's UI is significantly more polished than traditional Swagger UI and provides better developer experience for the Roundtrip API — relevant when third-party integrations (accounting software, CRM) use the API.
| Advantages | Disadvantages |
|---|---|
| ✓ Beautiful, modern API reference UI ✓ Generated automatically from FastEndpoints OpenAPI output ✓ Better developer experience than Swagger UI ✓ Client SDK generation (TypeScript, C#) from OpenAPI spec ✓ MIT licensed | ✗ Newer project — less community history than Swagger UI ✗ Some teams prefer Swagger UI familiarity |
Alternatives considered: Swagger UI — classic, widely recognized but dated UX. Redoc — clean, read-only, good for published API docs.
Logging
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Serilog | Structured logging with tenant context enrichment is a must-have for multi-tenant SaaS operations. | 4.x+ | ✓ Recommended |
Structured logging with tenant context enrichment is a must-have for multi-tenant SaaS operations. Serilog's sink ecosystem allows routing logs to SQL Server, Seq (local development), and cloud log aggregators. Enriching every log event with TenantId, TicketId, and TechnicianId enables rapid root-cause analysis for per-tenant issues.
| Advantages | Disadvantages |
|---|---|
| ✓ Structured logging — every event is queryable JSON ✓ Sink ecosystem covers SQL Server, Seq, Application Insights, Datadog, etc. ✓ Enrichers add TenantId to every log automatically ✓ Integrates with ASP.NET Core logging infrastructure ✓ Seq provides beautiful local log viewing during development | ✗ Configuration can be verbose for complex multi-sink setups ✗ Performance overhead vs. raw Microsoft. Extensions. Logging for high-throughput paths |
Alternatives considered: NLog — similar capability, strong community. Microsoft. Extensions. Logging — built-in, basic. OpenTelemetry — emerging standard, pairs well with Serilog.
Observability
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| OpenTelemetry + Seq (dev) / Application Insights (prod) | Multi-tenant SaaS requires observability beyond logs — distributed traces and metrics enable identifying which tenant is causing performance issues, which background jobs are slow, and where bottlenecks appear. | OTel 1.x | ✓ Recommended |
Multi-tenant SaaS requires observability beyond logs — distributed traces and metrics enable identifying which tenant is causing performance issues, which background jobs are slow, and where bottlenecks appear. OpenTelemetry provides vendor-neutral instrumentation; Seq for local development, Application Insights or Datadog for production.
| Advantages | Disadvantages |
|---|---|
| ✓ OpenTelemetry is the emerging industry standard ✓ Vendor-neutral — switch backends without code changes ✓ ASP.NET Core has built-in OTel instrumentation ✓ Distributed traces span across API, Hangfire, and n8n calls ✓ Seq provides excellent local trace/log UI | ✗ Additional complexity to set up properly ✗ Application Insights has per-GB ingestion cost ✗ OTel ecosystem still maturing |
Alternatives considered: Datadog — excellent SaaS observability, higher cost. Jaeger — open-source tracing, self-hosted. Grafana + Loki + Tempo — full open-source stack.
CI/CD
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| GitHub Actions | GitHub Actions provides workflow automation for Roundtrip's build, test, and deployment pipelines. | N/A (SaaS) | ✓ Recommended |
GitHub Actions provides workflow automation for Roundtrip's build, test, and deployment pipelines. Workflows trigger on PR and main branch pushes, running xUnit tests (with Testcontainers for real SQL Server/Redis), architecture tests (NetArchTest), and producing Docker images for deployment. GitHub is the target VCS per the Requirements document.
| Advantages | Disadvantages |
|---|---|
| ✓ Native GitHub integration — no separate CI server ✓ Generous free tier for private repos ✓ Docker-in-Docker supported for Testcontainers ✓ Rich marketplace of reusable actions (Docker build, Azure deploy, etc.) ✓ Matrix builds for multiple .NET versions | ✗ Vendor lock-in to GitHub ✗ Complex workflows can be difficult to debug locally ✗ Concurrency limits on free tier |
Alternatives considered: Azure DevOps — strong .NET integration, enterprise features. GitLab CI — full DevOps platform. Jenkins — self-hosted, more control, more overhead.
09 — TESTING
Testing
Unit / Integration Testing
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| xUnit + FluentAssertions + Testcontainers | xUnit is the . | Latest stable | ✓ Recommended |
xUnit is the .NET testing framework of choice for modern applications, with excellent parallel test execution. FluentAssertions makes test assertions read like natural language, reducing test maintenance burden. Testcontainers spins up real SQL Server and Redis instances in Docker during integration tests — ensuring tests run against actual infrastructure, not mocks.
| Advantages | Disadvantages |
|---|---|
| ✓ Testcontainers eliminates need to mock database — tests against real SQL Server ✓ FluentAssertions produce readable failure messages ✓ xUnit's parallel execution speeds CI pipelines ✓ Integration tests can verify tenant isolation at the database level ✓ Plays well with GitHub Actions / Azure DevOps CI | ✗ Testcontainers requires Docker in CI environment ✗ Integration tests are slower than unit tests ✗ Team discipline required to maintain test coverage |
Alternatives considered: NUnit — mature, similar capability. MSTest — Microsoft's framework, less idiomatic. Bogus — pairs with xUnit for fake data generation (recommended addition).
Architecture Testing
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| NetArchTest | NetArchTest enables automated enforcement of Clean Architecture rules — ensuring domain layer never references infrastructure, that entities don't depend on EF Core directly, and that API endpoints don't bypass the CQRS layer. | Latest | ✓ Recommended (new addition) |
NetArchTest enables automated enforcement of Clean Architecture rules — ensuring domain layer never references infrastructure, that entities don't depend on EF Core directly, and that API endpoints don't bypass the CQRS layer. For a long-running SaaS product, architecture drift is a major risk; automated tests catch it early.
| Advantages | Disadvantages |
|---|---|
| ✓ Enforces architectural boundaries automatically in CI ✓ Catches architecture violations before code review ✓ Readable rule definitions in C# ✓ Prevents accidental Clean Architecture violations as team grows | ✗ Adds to test maintenance burden ✗ Requires team understanding of Clean Architecture rules to write good tests |
Alternatives considered: ArchUnitNET — similar capability, more complex. Manual code review — doesn't scale.
10 — FRONTEND TOOLING
Frontend Tooling
State Management
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| TanStack Query (React Query) | TanStack Query v5 handles server state in React — fetching, caching, synchronizing, and updating data from the Roundtrip API. | 5.x+ | ✓ Recommended |
TanStack Query v5 handles server state in React — fetching, caching, synchronizing, and updating data from the Roundtrip API. For a field service dashboard where ticket statuses, technician locations, and inventory levels change frequently, Query's stale-while-revalidate strategy and background refetching keep the UI current without manual refresh flows.
| Advantages | Disadvantages |
|---|---|
| ✓ Eliminates most manual useEffect data-fetching boilerplate ✓ Automatic background refetching for live data ✓ Optimistic updates for fast UI response ✓ Mutation invalidation keeps related queries fresh ✓ DevTools extension for debugging cache state | ✗ Server state only — need Zustand/Context for UI/local state ✗ v5 has breaking changes from v4 — migration cost for existing code |
Alternatives considered: SWR (Vercel) — similar, slightly simpler API. RTK Query — if using Redux. Apollo Client — if switching to GraphQL.
Client-Side State
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Zustand | For UI state that doesn't come from the server (sidebar open/closed, active tenant context in the UI, map view state, selected technician filters), Zustand provides a lightweight and ergonomic state management solution. | 4.x+ | ✓ Recommended (new addition) |
For UI state that doesn't come from the server (sidebar open/closed, active tenant context in the UI, map view state, selected technician filters), Zustand provides a lightweight and ergonomic state management solution. TanStack Query handles server state; Zustand handles client-side UI state. This separation prevents the complexity of Redux for what is ultimately a relatively simple client state requirement.
| Advantages | Disadvantages |
|---|---|
| ✓ Minimal boilerplate — far simpler than Redux ✓ No provider wrapping required ✓ Integrates naturally with React Query ✓ Tiny bundle size (~3KB) ✓ TypeScript-first | ✗ Less tooling than Redux DevTools (though Zustand has its own DevTools) ✗ No built-in async handling — use with React Query for that |
Alternatives considered: Redux Toolkit — more powerful, much more complex. Jotai — atomic model, similar simplicity. React Context — built-in but causes unnecessary re-renders at scale.
HTTP Client
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Axios | Axios handles all HTTP communication from the React frontend to the Roundtrip API. | 1.x+ | ✓ Recommended |
Axios handles all HTTP communication from the React frontend to the Roundtrip API. Its interceptor system is critical for multi-tenant SaaS: a request interceptor automatically attaches the JWT Bearer token and tenant context headers to every API call, ensuring no request accidentally runs without tenant scope.
| Advantages | Disadvantages |
|---|---|
| ✓ Request/response interceptors for auth and tenant header injection ✓ Automatic JSON serialization/deserialization ✓ Request cancellation (important for map/search queries) ✓ Works well with TanStack Query's fetcher pattern ✓ TypeScript support | ✗ Fetch API (native) now covers most use cases in modern browsers ✗ Bundle size (though small) ✗ Error handling requires care |
Alternatives considered: Native Fetch — built-in, no bundle cost, but no interceptors natively. ky — fetch-based, lightweight alternative to Axios.
Charts / Analytics
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| Recharts | Roundtrip's management dashboard requires charts for ticket volume trends, technician utilization, revenue by service type, and inventory turnover. | 2.x+ | ✓ Recommended |
Roundtrip's management dashboard requires charts for ticket volume trends, technician utilization, revenue by service type, and inventory turnover. Recharts is built on D3 and React, providing composable chart components that align with the component-first architecture. Its responsive container system handles the variety of screen sizes from desktop dispatchers to tablet technicians.
| Advantages | Disadvantages |
|---|---|
| ✓ React-native — no DOM manipulation, clean component model ✓ Composable — build custom charts from primitives ✓ Responsive containers for multi-device support ✓ Good TypeScript support ✓ Active maintenance | ✗ Less performant than canvas-based alternatives for very large datasets (10k+ points) ✗ Custom chart types require significant effort |
Alternatives considered: Victory Charts — similar React-first approach. Apache ECharts (via echarts-for-react) — more chart types, heavier bundle. Tremor — pre-built analytics components, faster to ship.
PDF Generation
| Technology | Justification Summary | Version | License |
|---|---|---|---|
| QuestPDF | Roundtrip generates invoices, quotes, and service reports as PDFs for email delivery or print. | 2024.x+ | ✓ Recommended (new addition) |
Roundtrip generates invoices, quotes, and service reports as PDFs for email delivery or print. QuestPDF is the leading .NET PDF generation library — fluent API, pixel-perfect layout, excellent performance. Invoices and service reports are triggered as Hangfire background jobs, making QuestPDF the right fit for non-blocking PDF generation.
| Advantages | Disadvantages |
|---|---|
| ✓ Fluent, code-first layout API — no RDLC/templates to maintain ✓ Excellent performance — generates PDFs in milliseconds ✓ Custom branding and layout — Roundtrip brand colors and logo ✓ MIT licensed for community use ✓ Active development with strong community | ✗ Commercial license required for enterprise use (invoicing generation at scale) ✗ Code-first can be verbose for complex multi-page documents |
Alternatives considered: iText7 — mature, AGPL or commercial. FastReport — visual designer, commercial. Telerik Reporting — commercial, visual.
11 — REMOVED ITEMS
Removed Items
REMOVED: Swagger UI
Swagger UI was in the original stack but is superseded by Scalar, which FastEndpoints integrates with natively and provides a significantly better developer experience. The OpenAPI spec generation is the same — only the UI layer changes.
12 — MULTI-TENANCY STRATEGY
Multi-Tenancy Implementation
Roundtrip is a multi-tenant SaaS platform. Every architectural decision must account for tenant isolation, data security, and per-tenant customization. The following strategy governs the implementation.
Data Isolation Model: Hybrid
Roundtrip adopts a hybrid data isolation strategy to balance cost, isolation strength, and scalability:
| Tenant Tier | Database Strategy | Isolation Level | Use Case |
|---|---|---|---|
| Standard (SMB) | Shared database, shared schema | Row-level via TenantId (EF Core Global Query Filter) | Small-medium tenants — lower cost |
| Professional | Shared database, separate schema | Schema-level isolation | Mid-size tenants with data volume concerns |
| Enterprise | Dedicated database | Full isolation | Large tenants, regulated industries, compliance requirements |
Tenant Resolution
Tenants are identified per request via subdomain (tenant.roundtrip.app) or JWT claim. A custom ASP.NET Core middleware resolves TenantContext early in the pipeline and registers it as a scoped service, injected into DbContext, Hangfire jobs, and SignalR hubs.
EF Core Global Query Filter
Every entity implementing ITenantEntity has a Global Query Filter applied in OnModelCreating that automatically appends WHERE TenantId = @currentTenant to all queries. This provides defense-in-depth — even if a developer forgets to filter by tenant, the database query is still scoped correctly.
Keycloak Tenant Realms
Each tenant is provisioned a Keycloak realm, providing complete user isolation at the identity layer. Tenant administrators can configure their own SSO providers, MFA policies, and user roles within their realm without affecting other tenants.
Roundtrip · Tech Stack Benefits Analysis v1.0 · A Traxs Company Product · March 2026