How to use TVM Sales.
A step-by-step manual for everyone who touches the platform — field reps logging visits on mobile, managers reading the live map on desktop, and admins setting up tenants and territories. Bookmark this page; reference it when something looks off.
What TVM Sales is.
TVM Sales is a CRM for field-sales teams that need to verify what their reps are doing on the ground — not just trust the daily report. It has two surfaces:
- A mobile app for reps. They log into it once, see today’s plan, navigate to the next school/client, check in with a photo and a 30-second form when they’re inside the geofence, and move on.
- A web dashboard for managers and admins. Shows where every rep is on a live map, plays back routes minute-by-minute, surfaces flagged visits, and runs the configuration (territories, plans, forms, team).
The two surfaces share a single backend (the API at https://sales.thetvm.com/api). Anything a rep does on mobile shows up on the manager’s screen within seconds. Anything an admin configures shows up on the rep’s phone the next time the app refreshes.
Who uses what.
Field force
Mobile app only. Sees today’s plan, checks in at clients, logs outcomes, records voice notes. Cannot see other reps or admin config.
Live ops
Web dashboard. Reads the live map, day playback, alerts, insights, and rep performance. Can assign visits and approve/reject flagged visits.
Setup & control
Everything a manager can do, plus tenant settings: clients/leads, territories, team, custom forms, integrations (EduxenOS, OpsXen, WhatsApp).
Configuration → Team on the dashboard and edits the user.Your first day, end-to-end.
The shortest path from “fresh tenant” to “a verified visit landing on the map.”
Admin: bootstrap the tenant.
Your TVM contact runs the bootstrap script once. It creates the tenant, the first admin user, and seeds a starter territory. You receive an email with your sign-in link and a temporary password.
Admin: sign in and change the password.
Open sales.thetvm.com/login, enter your credentials. On first sign-in you’ll be prompted to set a permanent password and (optionally) enable 2FA.
Admin: import clients (the schools/businesses you visit).
Go to Clients → Add, fill in name, address, and the geofence radius (typically 50–200m). The dashboard will geocode the address and drop a pin. Repeat or bulk-paste JSON via the API for now (a CSV uploader is on the roadmap).
Admin: draw territories.
Territories → New. A territory is a polygon on the map; clients inside it get auto-assigned to whichever rep owns the territory. (For now territories are created by POSTing GeoJSON; a UI polygon editor is in the queue.)
Admin: invite reps and assign territories.
Team → Invite creates rep accounts. Each rep gets an email with a one-time link to set their password. After they sign in, edit them and set their territory.
Manager: assign today’s plan.
Plans → Today. Pick a rep, drag clients into the day’s sequence (or click Optimize route to let OSRM order them by drive time). Save.
Rep: install the app and sign in.
Send the Android APK link from your IT contact. The rep installs, opens it, signs in with the credentials they set in step 5. Today’s plan appears.
Rep: start workday and visit a client.
Tap Start workday. Drive to the first client. Tap Check in. The app confirms you’re inside the geofence (the map pulses), takes a photo, you pick an outcome and tap Submit.
Manager: watch it land on the dashboard.
Open Live map. The rep’s pin shows them at the client. Open Visits — the new visit row appears with a trust score. That’s the loop.
How to use the mobile app.
One-thumb operation, designed for the back of an Uber. Three taps to log a verified visit.
Sign in
Open the TVM Sales app. Enter your work email and password. Tap Sign in →. If your admin enabled 2FA on your account, you’ll be asked for a 6-digit authenticator code.
Today tab
Top banner shows whether your workday is open, how many visits you’ve done out of the total, distance covered, and your current trust score. Below the banner is your NEXT UP list. The next unfinished visit is highlighted with a blue border.
- Start workday — green button on the banner. Tap it before your first visit. GPS pings start streaming and the trust engine begins watching.
- Navigate → — opens Google Maps with turn-by-turn directions to the client.
- Check in — opens the check-in flow when you arrive (covered next).
- End workday — same banner button at the end of your day. GPS streaming stops.
Check in at a client
This is the core loop. The screen has six sections, top to bottom:
- GPS card (dark). Shows your live coordinates and accuracy. Wait until it says ● INSIDE GEOFENCE in green. If it says LOCATING… for more than 30 seconds, walk a few meters or step outside.
- Trust signals row. Three small cards (GPS / Speed / Sensor). All should read ✓ OK. If any reads × FAIL, the visit will be flagged for review.
- Visit info. Confirms which client you’re at.
- Photo proof. Tap Open camera and snap a photo of the entrance, lobby, or any clear marker. Don’t use a saved photo — only fresh captures count toward trust.
- Outcome. Pick one: Demo done, Follow-up, Converted, Not interested, or Other.
- Voice note + Notes (optional). Record a 30-second voice memo (auto-transcribed by Whisper) or type free-form notes for your manager.
Tap the big blue Check in & finish visit button at the bottom. The app uploads the photo, records the visit, and bounces you back to the Today tab. The visit moves to DONE.
Leads tab
Your personal pipeline — every lead with you as the assignee, grouped by stage (new · contacted · demo_scheduled · demo_done · negotiation · won · lost). Tap a row to see history.
Profile tab
Your identity (name, tenant, role, 2FA status), your week stats (streak, personal best, visits this week, conversions), and a sparkline showing daily activity. Sign out lives at the bottom.
If you get flagged
A flagged visit isn’t an accusation — it’s a heuristic that wants a human review. Open the visit on the dashboard or tap the “Why was I flagged?” link in the notification. You’ll see exactly which signals fired (e.g., photo_age_mismatch: photo was taken 38 minutes before check-in) and a plain-English explanation. If something looks wrong, message your manager — they can clear the flag.
How to use the web dashboard.
Sign in at sales.thetvm.com/login. The sidebar shows two groups of pages: Operations (the live work) and Configuration (the setup). Most days you’ll only need Operations.
Overview
Landing screen. Five KPI cells at the top (active reps · visits today · 7d visits · open flags · conversions), an embedded live map, the alert feed, the pipeline, and the top-reps leaderboard. The single screen tells you whether the day is going well.
Live map
Every rep on shift, color-coded by trust state. Auto-refreshes every 30 seconds. Click a rep’s pin to see their day timeline. Use the Today / Live / Week toggle to widen the time window.
Visits
Every check-in, newest first. Filter by rep, client, outcome, or trust score. Click a visit to open the detail page — photo, GPS trace, trust score breakdown with per-signal explanations, and (if recorded) the voice note transcript.
Plans
Day plans per rep. Click Today to see who’s assigned what; click into any plan to drag the sequence, add/remove visits, or hit Optimize route (uses the OSRM road graph; falls back to Haversine nearest-neighbor if OSRM isn’t ready).
Alerts
Two streams: flagged visits (trust score below threshold) and idle reps (workday open but no GPS pings for > 30 min). Use the action buttons to clear, escalate, or dig in.
Insights
Three panels:
- Best times to call — per client, the hour bands when prior visits had real outcomes.
- Stale leads — open leads with no event in N days (default 14).
- Territory white-space — clients in the territory with no visit in the last 30 days. Send the visit list to a rep with one click.
The weekly summary email button at the top of Insights renders the same data as HTML and emails it to all active users in the tenant.
Notifications bell
Top-right of every page. Unread count badge in red. Click for the dropdown: morning briefings, flag notifications, mention pings. Mark all read clears the badge.
Configuration pages — for admins.
Clients
The list of all schools / businesses you visit. Each client has a name, address (used to compute the coordinates and pin), and a geofence radius (the circle within which a rep is considered “on site”). 50–200m covers most cases — schools with large campuses might need 300m+.
Leads
Pipeline records with stages (new → contacted → demo_scheduled → demo_done → negotiation → won/lost), value (in paise/cents), source (web, WhatsApp, manual). Linked to a client and an owner.
Territories
Polygons on the map, owned by a single rep. Clients inside a territory auto-assign to its owner. Use them to split a city among reps.
Team
All users (reps, managers, admins). Invite new users, edit their role, edit their territory, lock or unlock accounts (a rep who fails 5 logins gets auto-locked for 15 minutes).
Forms
The visit-log schema your reps see on mobile. Add custom fields (text, number, boolean, select). The schema is per tenant, lives in tenants.settings.visitFormSchema, and applies to all reps immediately.
How the trust engine works.
Every visit gets a trust score from 0 to 100. The score starts at 100 and a list of signals deduct points when something looks suspicious. Below 60 the visit is flagged for manager review.
The ten signals
| Signal | Penalty | Fires when |
|---|---|---|
| outside_geofence | −50 | Check-in coordinates more than radius+slack from client centroid. |
| mock_location | −40 | Phone reports is_mock=true at the moment of check-in. |
| mock_location_history | −40 | Any is_mock=true ping in the past 24h, even if turned off for the actual check-in. |
| teleport | −35 | Two pings imply > 200 km/h sustained speed. |
| static_circuit | −35 | GPS pings span less than 50m for 30 minutes, but check-in is more than 1km away. |
| photo_age_mismatch | −25 | EXIF DateTimeOriginal differs from check-in time by more than 10 min. |
| photo_missing | −15 | No photo attached. |
| gps_accuracy_low | −10 | Reported accuracy worse than 100m. |
| bssid_inconsistency | −30 | WiFi/cell fingerprint has zero overlap with rep’s recent check-ins. |
| rapid_repeat_visit | −15 | Same client visited twice within 30 minutes. |
Reps can see exactly why a visit was flagged via the Why flagged? screen on mobile or the visit detail page on web. Each signal has a plain-English explanation written for rep consumption — no jargon.
Offline & low-signal use.
Reps work in the basements of Tier-3 schools and the back roads of Haryana. The mobile app is built for that:
- Today’s plan is fetched once at sign-in and cached locally. You can scroll it without a connection.
- Check-ins queue when offline. The submit button still works — the visit goes into a local queue. The Today screen banner shows a “queued · N” chip.
- Auto-flush. The moment the app sees a network connection, it replays the queue in order. Photos and voice notes go up too.
- Idempotent. If a visit got partially uploaded before signal dropped, the server deduplicates by client-side UUID — you won’t see ghost duplicates.
expo-secure-store, which has a ~2KB cap on iOS. If you queue more than ~10 visits without sync, the oldest may be dropped. A SQLite-backed queue is on the roadmap. Practical workaround: pop into Wi-Fi range once a day to flush.Things that go wrong, and what to do.
Mobile: GPS card stuck on “LOCATING…”
Step outside or near a window. Indoor GPS in concrete buildings can take a minute. If it still doesn’t resolve, kill the app and reopen — sometimes the OS holds a stale fix. As a last resort, toggle airplane mode off-and-on.
Mobile: “Outside geofence” error on check-in
Walk closer to the building entrance. Most geofences are 50–200m around the address centroid. If you’re visibly inside the grounds and it still fails, the client’s pin is wrong — message your manager to widen the radius or fix the address.
Mobile: “invalid or expired token” on the Today screen
Your session timed out. Tap Profile → Sign out, then sign in again. (Silent token refresh is on the roadmap; for now it’s a manual re-login.)
Mobile: photo button does nothing
You denied the camera permission on first launch. Open Android Settings → Apps → TVM Sales → Permissions → Camera → Allow.
Web: dashboard shows “Loading…” forever
Refresh the page. If still stuck, check the browser console (F12 → Console) — almost always either an expired token or a CORS error. Sign out and back in.
Web: live map is empty
Either no rep has checked in today yet, or no rep has “Start workday” pressed. GPS pings are gated on an open workday — that’s by design (drains less battery, prevents off-hours surveillance).
Manager: a visit looks legitimate but is flagged
Open the visit detail page. Read the per-signal explanations. Most often it’s photo_age_mismatch (the rep used a saved photo) or gps_accuracy_low (poor signal indoors). You can clear the flag manually with the Approve button.
Locked out after wrong passwords
Five failed attempts triggers a 15-minute auto-lock. Wait it out, or ask your admin to reset (currently a SQL command — UI tooling is in queue).
Words you’ll see.
- Tenant
- Your organization. One TVM Sales account is one tenant. All users, clients, and territories live inside a single tenant — no cross-tenant data sharing.
- Geofence
- The radius around a client’s address centroid within which a rep can check in. Default 100m, configurable per client.
- Workday
- A time window opened with “Start workday” and closed with “End workday.” GPS pings are only stored during open workdays (battery + privacy).
- Trust score
- A 0–100 number per visit. Sum of 100 minus all firing signal penalties, floored at 0. Below 60 = flagged.
- Signal
- A heuristic that watches for one specific kind of anomaly (e.g., teleport, mock_location). Each signal has an integer penalty.
- Plan
- A rep’s ordered sequence of clients to visit on a given date. Drag to reorder, click Optimize Route to auto-sort by drive time.
- Lead
- A pipeline record tied to a client. Has a stage, a value, an owner, and an event history.
- Workspace pages
- The blue-coded pages in the sidebar (Operations + Configuration). Live at sales.thetvm.com/dashboard, /map, /visits, etc.
- Trust engine
- The package @tvm/trust that computes scores and signal explanations. Lives at packages/trust in the monorepo.