Core Mission: Bridge the field-to-office gap by enforcing physical proof-of-presence, eliminating ghost visits, and providing uninterrupted offline reliability.

• A real-time supervisory web portal for route scheduling, point-of-interest sequencing, and live monitoring.
• An offline-first Progressive Web App (PWA) for field reps that enforces physical proximity (default 30-meter geofence) before unlocking visit check-ins.
• A local IndexedDB queue with idempotent background sync that guarantees zero data loss in low-connectivity or dead-zone environments.

1. Hardware-Enforced Proximity: The client UI physically disables check-in submission until GPS telemetry confirms the agent is within the geofence radius. The backend repeats the exact mathematical verification upon ingestion.
2. Offline-First by Design: The mobile PWA treats network connectivity as an opportunistic enhancement, not a requirement. All reads and writes target an IndexedDB local store first.
3. Deterministic Multi-Tenant Governance: Hierarchical RBAC (SUPERADMIN → ADMIN → REP) enforcing strict resource quotas (maxReps, maxPoints, maxRoutes) and isolation.

// backend/src/visits/visits.service.ts
getDistanceInMeters(lat1: number, lon1: number, lat2: number, lon2: number): number {
  const R = 6371e3 // Earth's mean radius in meters
  const phi1 = (lat1 * Math.PI) / 180
  const phi2 = (lat2 * Math.PI) / 180
  const deltaPhi = ((lat2 - lat1) * Math.PI) / 180
  const deltaLambda = ((lon2 - lon1) * Math.PI) / 180

  const a =
    Math.sin(deltaPhi / 2) * Math.sin(deltaPhi / 2) +
    Math.cos(phi1) * Math.cos(phi2) * Math.sin(deltaLambda / 2) * Math.sin(deltaLambda / 2)
  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))

  return R * c // distance in meters
}

1. IDOR Prevention: Ensures REP users can only submit logs where repId === currentUser.id.
2. Idempotency Guarantee: Checks idempotencyKey (UUIDv4) to prevent duplicate processing on network retries.
3. Route Point Verification: Confirms the target route stop exists in the database.
4. Ownership Verification: Validates that the active route is currently assigned to the submitting representative.
5. Temporal Date Resolution: Verifies that the visit occurred on a scheduled date according to weekly recurrence rules (isRouteScheduledOnDate).
6. Server-Side Geofence Audit: Recomputes distance against settings.geofenceRadius. If distance exceeds the threshold, the visit is flagged as REJECTED with an explicit reason string.
7. Daily Limit Guard: Enforces that only one successful SYNCED check-in is logged per point per day.

// Core sync processing step in visits.service.ts
const distance = this.getDistanceInMeters(
  v.checkInLatitude,
  v.checkInLongitude,
  rp.point.latitude,
  rp.point.longitude
)

let syncStatus: SyncStatus = SyncStatus.SYNCED
let rejectReason = null

if (distance > geofenceRadius) {
  syncStatus = SyncStatus.REJECTED
  rejectReason = `La distance de check-in (${Math.round(distance)}m) dépasse le rayon autorisé de ${geofenceRadius}m.`
}

// Core Domain Models in backend/prisma/schema.prisma
model User {
  id           String   @id @default(uuid())
  name         String
  email        String   @unique
  passwordHash String
  role         Role     // SUPERADMIN | ADMIN | REP
  active       Boolean  @default(true)
  maxReps      Int      @default(5)
  maxPoints    Int      @default(20)
  maxRoutes    Int      @default(30)
  
  routes       Route[]  @relation("RepRoutes")
  visits       Visit[]  @relation("RepVisits")
}

model Point {
  id          String       @id @default(uuid())
  name        String
  address     String?
  latitude    Float
  longitude   Float
  routePoints RoutePoint[]
}

model Route {
  id             String         @id @default(uuid())
  repId          String
  rep            User           @relation("RepRoutes", fields: [repId], references: [id])
  startDate      DateTime
  endDate        DateTime?
  recurrenceType RecurrenceType // NONE | WEEKLY
  recurrenceDays String[]       // e.g. ["MONDAY", "WEDNESDAY"]
  status         RouteStatus    @default(ACTIVE)
  routePoints    RoutePoint[]
}

model Visit {
  id                String     @id @default(uuid())
  routePointId      String
  routePoint        RoutePoint @relation(fields: [routePointId], references: [id], onDelete: Cascade)
  repId             String
  rep               User       @relation("RepVisits", fields: [repId], references: [id])
  occurrenceDate    String     // YYYY-MM-DD
  deviceTimestamp   DateTime
  serverTimestamp   DateTime   @default(now())
  checkInLatitude   Float
  checkInLongitude  Float
  distanceFromPoint Float
  note              String?
  syncStatus        SyncStatus @default(PENDING) // PENDING | SYNCED | REJECTED
  rejectReason      String?
  idempotencyKey    String     @unique

  @@unique([routePointId, occurrenceDate, idempotencyKey])
}

• Continuous GPS Watcher: Real-time polling of browser Geolocation API with accuracy indicators (accuracy < 15m).
• Dynamic Proximity HUD: Live distance calculation showing meters remaining until within range.
• Visual Radar Animations: Pulse indicators highlighting active target points on the interactive Leaflet map.
• Modal Check-In Bottom Sheet: Fluid bottom sheets for rapid note entry and instant local submission.

// frontend/src/lib/indexedDb.ts — Offline Persistence Engine
const DB_NAME = "traceo_pwa_db"
const STORE_NAME = "pending_visits"

export async function addVisitToQueue(visit: QueuedVisit): Promise<void> {
  const db = await openDb()
  return new Promise((resolve, reject) => {
    const tx = db.transaction(STORE_NAME, "readwrite")
    const store = tx.objectStore(STORE_NAME)
    const req = store.put(visit)
    req.onsuccess = () => resolve()
    req.onerror = () => reject(req.error)
  })
}

• Live Activity Feed: Real-time stream of incoming check-ins, reporting agent identity, client site, timestamp, and registered check-in distance.
• Route Sequencer: Interactive ordering of client stops with immediate sequence re-indexing and rep assignment.
• Interactive Geospatial Dashboard: Leaflet map visualizer rendering agent paths, point clusters, and visit status color codes (Green = Visited, Grey = Pending, Red = Rejected).

Route Sequencer & Cyclical Assignment

Geospatial Point-of-Interest Directory

• Brand Teal (#155E63 / 185 65% 24%): Primary brand identity, communicating precision and enterprise reliability.
• Verified Emerald (#1F9D55 / 146 67% 37%): Clear visual confirmation for authenticated visits within geofence range.
• Alert Crimson (#C0362C / 4 63% 46%): Instant feedback for distance breaches or route discrepancies.
• Surface Neutrals (#F5F7F5 / #15211E): Low eye-strain background and ink contrast adhering to WCAG AAA standards.

Field Agent Quota & Role Administration

Standardized Field Workflow Guides

1. Dual-Layer Geospatial Defense: Client-side geofencing is essential for user experience (giving immediate feedback), but server-side recalculation is the only way to guarantee tamper-proof security.
2. Idempotency is Mandatory for Offline Sync: Offline queues will experience network drops mid-request. Assigning immutable client-side UUIDs (idempotencyKey) ensures network retries never duplicate transactional data.
3. Prisma Lean Selects Prevent Mobile Over-Fetching: Mobile field agents require lean payloads. Explicit Prisma selects trimmed unnecessary payload weight by over 70%, accelerating offline synchronization over degraded mobile networks.