TouchToFix
Technical Documentation

01 System Architecture

TouchToFix v2 (vnext) is a microservice-oriented platform deployed on Google Cloud Platform. All components run in Docker containers orchestrated by Docker Compose behind an nginx reverse proxy with TLS termination.

Request Flow

Browser / Mobile App
    ↓ HTTPS (443)
nginx (nginx:alpine)
    ↓ reverse proxy by Host header
    ├── api.touchtofix.com → api:3100 (NestJS)
    │       ↕ Prisma ORM
    │       ├── postgres:5432
    │       └── redis:6379 (WebSocket relay)
    ├── app.touchtofix.com → static Flutter web (customer)
    ├── expert.touchtofix.com → static Flutter web (expert)
    ├── admin.touchtofix.com → admin:80 (React SPA)
    ├── fixme.touchtofix.com → fixme:80 (FixMe Portal)
    └── touchtofix.com → website:80 (Marketing)

02 Technology Stack

03 API Reference

Base URL: https://api.touchtofix.com · All authenticated routes require: Authorization: Bearer {jwt}

Auth Module

Tickets Module

Chat Module

Remote Sessions (VNC) Module

AI Diagnosis Module

Admin Module (admin key required)

All admin routes are protected by AdminAuthGuard. Pass admin API key in header: x-admin-key: {key}

WebSocket Events

Connect to: wss://api.touchtofix.com/ws with JWT in query: ?token={jwt}

04 Database Schema

PostgreSQL database managed by Prisma ORM. Migrations located at prisma/migrations/. Schema file: prisma/schema.prisma.

05 Mobile Apps

Both apps share the same Flutter codebase style, design system, and dependency set. They are compiled to iOS (IPA), Android (APK/AAB), and Web (static HTML).

Customer App — ttf_customer_vnext

Expert App — ttf_expert_vnext

Build Commands

# Customer web app
cd version2/mobile/ttf_customer_vnext
flutter build web --release
# Output: build/web/

# Expert web app
cd version2/mobile/ttf_expert_vnext
flutter build web --release
# Output: build/web/

# Android APK
flutter build apk --release

# iOS IPA (requires macOS + Xcode)
flutter build ipa --release

App Configuration

Both apps read from lib/config/app_config.dart:

class AppConfig {
  static const String apiBaseUrl  = 'https://api.touchtofix.com';
  static const String wsBaseUrl   = 'wss://api.touchtofix.com';
  static const String fixmeBaseUrl = 'https://fixme.touchtofix.com';
  static const String appName     = 'TouchToFix';
}

06 Authentication & Security

OTP Auth Flow

1. Client → POST /auth/otp/request  { phone, phoneSuffix }
      Server: generates 6-digit OTP, stores with 5-min TTL, sends via SMS
2. Client → POST /auth/otp/verify   { phone, phoneSuffix, code }
      Server: validates OTP, returns { token: JWT, user: {...} }
3. All subsequent requests: Authorization: Bearer {JWT}

Desktop Transfer Token Flow

1. Mobile app → POST /auth/desktop-transfer
      Server: creates 32-byte hex token + 6-digit OTP, expires in 5 min
      Returns: { token, otpCode, expiresAt, url }
      url = https://app.touchtofix.com?dt={token}&otp={otpCode}

2. Mobile app: displays QR code of url, shows OTP with countdown

3. PC browser opens url (scans QR or manual):
   Flutter web app detects ?dt + ?otp params in Uri.base
   → POST /auth/desktop-transfer/verify  { token, otpCode }
   → Server validates, marks token used, returns { token: JWT, user }
   → SessionStore.saveSession(token, userId)
   → Navigates to /home as logged-in user

Role-Based Access Control

Security Measures

• All external traffic encrypted via TLS 1.2+ (Let's Encrypt)
• JWT tokens signed with HS256 and stored in flutter_secure_storage (iOS Keychain / Android Keystore)
• Desktop transfer tokens are single-use (usedAt timestamp prevents replay)
• WebRTC sessions are peer-to-peer encrypted — server never sees screen data
• TTFDesk OTP is session-scoped and single-use
• All admin actions written to AuditLog model
• Rate limiting on OTP endpoints to prevent brute force
• Security headers on all nginx responses (X-Frame-Options, X-XSS-Protection, HSTS)

07 Remote Desktop — TTFDesk

TTFDesk is our branded self-hosted remote control infrastructure built on RustDesk open-source (AGPL-3.0). It provides full keyboard and mouse control of the customer's PC from the expert's PC.

Infrastructure Components

TTFDesk ID Derivation

The customer's TTFDesk ID is automatically derived from their phone number, eliminating the need for manual ID lookup or sharing:

// In vnc.service.ts → requestRustdesk()
const customer = await prisma.user.findUnique({
  where: { id: session.userId },
  select: { phone: true, phoneSuffix: true }
});
const sessionCount = await prisma.vncSession.count({
  where: { userId: session.userId }
});
const counter = String(sessionCount).padStart(4, "0");
const phoneDigits = (customer.phoneSuffix ?? "").replace(/\D/g, "")
                  + (customer.phone ?? "").replace(/\D/g, "");
const ttfdeskId = phoneDigits
  ? `${phoneDigits}-${counter}`    // e.g. "60123456789-0001"
  : `ttf-${session.userId.slice(0,8)}-${counter}`;

Remote Control Flow

1. Expert taps "Request Remote Control (TTFDesk)" in expert app
2. Backend: derives ttfdeskId, generates OTP, stores in VncSession
3. Backend sends chat message { type: "rustdesk_request", ttfdeskId, rustdeskOtp, relayServer, downloadUrl }
4. Customer sees "TTFDesk Remote Control Request" card in chat:
   Step 1: Download TTFDesk from touchtofix.com/ttfdesk
   Step 2: In TTFDesk Settings → ID Server → set: api.touchtofix.com
   Step 3: In TTFDesk Settings → set Custom ID to: {ttfdeskId}
   Step 4: Set password to: {otp}
   Step 5: Confirm — expert will connect shortly
5. Expert sees: Customer TTFDesk ID + Password in styled card
6. Expert opens TTFDesk on PC, enters ID, connects with OTP

Client Configuration (TTFDesk App)

FixMe Portal — Screen Share (WebRTC)

For lighter interactions, the FixMe Portal provides browser-based screen sharing without software installation:

• Customer taps "Transfer to Desktop" in mobile app → QR code + URL generated
• Customer opens fixme.touchtofix.com on PC browser
• Expert pastes transfer token + OTP in the Expert tab
• WebRTC P2P connection established (STUN: Google, TURN: coturn self-hosted)
• Expert sees live screen + cursor annotation tools

08 Billing Engine

Session Billing Model

• Sessions are billed in 15-minute slabs (any partial slab rounds up)
• Expert sets their own hourly rate. Platform shows rate to customer before session
• Platform retains 20%; expert receives 80%
• B2B company discounts configurable per company SLA policy

Billing Calculation

durationMinutes = ceil((endedAt - startedAt) / 60_000)
slabs = ceil(durationMinutes / 15)
grossAmount = slabs * (expertRate / 4)  // rate is per hour ÷ 4
platformFee = grossAmount * 0.20
expertPayout = grossAmount * 0.80

// B2B discount applied before calculation:
grossAmount *= (1 - company.discountPercentage / 100)

Admin Billing Controls

• GET /admin/billing/summary — Platform-wide revenue report
• POST /admin/customers/:id/balance/collect — Initiate payment collection
• POST /admin/customers/:id/balance/override — Manual balance adjustment
• PUT /admin/payments/:id/status — Update payment status (PENDING → PAID → DISPUTED)

09 Deployment Guide

Server Access

gcloud compute ssh ttfnewv02 --zone=us-central1-f
# Working directory: /opt/ttf
# Compose file: docker-compose.prod.yml

Deploy Backend Update

# 1. Build locally
cd version2/backend/ttf_backend_vnext
npm run build

# 2. Package dist
tar -czf /tmp/backend_dist.tar.gz dist/ package.json package-lock.json

# 3. Upload to VM
gcloud compute scp /tmp/backend_dist.tar.gz ttfnewv02:/tmp/ --zone=us-central1-f

# 4. On VM: extract + rebuild container
cd /opt/ttf/backend/ttf_backend_vnext
tar -xzf /tmp/backend_dist.tar.gz
cd /opt/ttf
docker compose -f docker-compose.prod.yml up -d --build api

# 5. Restart nginx
docker compose -f docker-compose.prod.yml restart nginx

Deploy Flutter Web Apps

# Build
flutter build web --release

# Package + upload
tar -czf /tmp/customer_web.tar.gz -C ttf_customer_vnext/build web
gcloud compute scp /tmp/customer_web.tar.gz ttfnewv02:/tmp/ --zone=us-central1-f

# On VM: deploy
sudo rm -rf /opt/ttf/web/customer/*
mkdir -p /tmp/customer_web_tmp
tar -xzf /tmp/customer_web.tar.gz -C /tmp/customer_web_tmp
sudo cp -r /tmp/customer_web_tmp/web/* /opt/ttf/web/customer/

Database Migrations

# Development (interactive)
npx prisma migrate dev --name your_migration_name

# Production (non-interactive)
npx prisma migrate deploy

# Seed database
node prisma/seed.js

Check Service Health

cd /opt/ttf
docker compose -f docker-compose.prod.yml ps
curl https://api.touchtofix.com/health
docker logs ttf-api-1 --tail=50

10 Ports & Infrastructure

Domain Routing

TouchToFix Technologies · Technical Documentation v2.0 · March 2026 · Confidential