SurakshaPath - System Integration Architecture

High-Level Architecture

📍 Physical Layer (In-Vehicle & Track)

📹

In-Vehicle Camera

Hikvision DS-7604NI

MQTT

📊

OBD-II Device

ELM327 / Teltonika

MQTT

📍

GPS Tracker

u-blox NEO-M9N

MQTT

📷

Track CCTV

Hikvision 4MP

RTSP

🚦

IoT Sensors

Cone sensors, barriers

MQTT

MQTT / RTSP over 4G LTE

⚡ Edge Computing Layer (RTO Premises)

🖥️

Edge Server

NVIDIA Jetson AGX

gRPC

📡

MQTT Broker

Eclipse Mosquitto

MQTT

🧠

AI Inference

TensorRT Models

gRPC

REST / WebSocket / Kafka over Internet

☁️ Cloud Services Layer (AWS)

🚪

API Gateway

FastAPI + Rate Limiter

📱

Device Service

Registration, Heartbeat

🧪

Test Session

Telemetry Ingestion

🚗

Driving Monitor

Behavior Analysis

👤

Verification

Face Recognition

Kafka Events / PostgreSQL

💾 Data & Event Layer

🐘

PostgreSQL

RDS + pgvector

📬

Apache Kafka

MSK (Event Streaming)

⚡

Redis

ElastiCache

📁

Video Evidence

API Integration

🌐 External Integrations

🏛️

Parivahan

Sarathi/Vahan API

📂

DigiLocker

Document Fetch

🆔

UIDAI

Aadhaar eKYC

💳

NPCI

UPI Payments

Existing SurakshaPath Services (Backend)

These microservices already exist in the backend/services/ directory and handle the core integration logic:

Device Management Service

✓ Built

backend/services/device-management-service/

Device registration (IMEI, serial)
Vehicle pairing
Heartbeat monitoring
Firmware OTA updates
Geofence management

Test Session Service

✓ Built

backend/services/test-session-service/

Session lifecycle management
Telemetry ingestion via Kafka
Real-time event publishing
Session replay storage

Driving Monitor Service

✓ Built

backend/services/driving-monitor/

Behavior analysis engine
Event detection (overspeed, harsh brake)
Real-time driver scoring
Risk classification

Driver Verification Service

✓ Built

backend/services/driver-verification-service/

Face embedding enrollment
Cosine similarity verification
Quality assessment
Anti-proxy detection

Evidence Collection Service

✓ Built

backend/services/evidence-collection/

Multi-source video aggregation
Chain of custody
Privacy engine (blurring)
Clip extraction

API Gateway

✓ Built

backend/gateway/

Rate limiting (Redis)
Circuit breaker
WebSocket support
Health monitoring

Complete Data Flow: Check-in to License

Candidate Check-in (QR Scan)

QR Scanner Biometric

Candidate scans QR from mobile app. Biometric captures fingerprint/face.

POST /api/v1/sessions/check-in

→ Validates booking, creates test session
→ Assigns vehicle & devices
→ Returns session_id

Face Enrollment & Verification

In-Vehicle Cam

Driver Verification Service enrolls face embeddings. Continuous verification during test.

POST /api/v1/verification/enroll

→ FaceEngine.enroll() stores embedding
→ cosine_similarity threshold: 0.85
→ Stored in PostgreSQL with pgvector

Device Pairing & Test Start

OBD-II GPS Camera

All devices paired to vehicle. Test session activated.

PUT /api/v1/devices/{device_id}/pair

→ Links OBD, GPS, Camera to vehicle_id
→ Activates telemetry streaming
→ MQTT topics: surakshapath/{device_id}/telemetry

Real-time Telemetry Streaming

Speed GPS Accel Video

OBD sends speed, RPM, acceleration. GPS sends location. Camera sends face frames.

WSS wss://api.surakshapath.in/ws/telemetry/{session_id}

→ 10 Hz telemetry (100ms intervals)
→ Published to Kafka topic: telemetry.raw
→ Driving Monitor consumes & analyzes

Behavior Analysis & Scoring

AI Engine

Driving Monitor Service analyzes telemetry windows, detects events, computes score.

// From behavior_analysis.py
analyse_telemetry_window(points) → {
  events: [overspeed, harsh_brake, swerve, phone_use],
  avg_speed: 42.5,
  max_speed: 65.2,
  driver_score: 82,
  risk_level: "low"
}

Test Completion & Result Generation

Scoring

Session ends. Final score calculated. Results published via Kafka.

POST /api/v1/sessions/{session_id}/complete

→ publish_session_completed() to Kafka
→ Evidence clips extracted from S3
→ Score card generated

License Issuance (DigiLocker + Sarathi)

Parivahan DigiLocker

If passed, license issued via Sarathi API. Pushed to DigiLocker.

POST https://sarathi.parivahan.gov.in/api/v1/license/issue

→ Submits test result to Sarathi
→ License number generated
→ Pushed to DigiLocker API

                            Key Integration Points
                            MQTT Broker: Eclipse Mosquitto at edge for device communication
Kafka Topics: telemetry.raw, session.events, verification.events
WebSocket: Real-time dashboard updates via gateway
PostgreSQL: All persistent data with pgvector for embeddings
Redis: Session cache, rate limiting, pub/sub
S3: Video evidence storage with lifecycle policies

                        

Latency Budget

Device → Edge	<50ms
Edge → Cloud	<100ms
AI Inference	<200ms
Dashboard Update	<500ms

Protocol & Interface Details

Device Communication (MQTT)

// MQTT Topic Structure
surakshapath/devices/{device_id}/telemetry
surakshapath/devices/{device_id}/status
surakshapath/devices/{device_id}/commands

// Telemetry Payload (JSON)
{
  "timestamp": "2026-05-18T10:30:00.123Z",
  "session_id": "sess_abc123",
  "gps": { "lat": 23.3441, "lng": 85.3096, "speed_kmph": 42.5 },
  "obd": { "rpm": 2500, "throttle": 35, "fuel": 72 },
  "imu": { "accel_g": 0.15, "yaw_rate": 2.3 },
  "camera": { "face_detected": true, "eyes_on_road": true }
}

Kafka Event Schema

// From backend/shared/events/schemas.py
EventEnvelope {
  event_type: "telemetry.raw" | "session.completed",
  payload: {
    session_id: string,
    user_id: string,
    telemetry_data: TelemetryPoint[],
  },
  metadata: {
    source_service: "test-session-service",
    timestamp: ISO8601,
    correlation_id: UUID,
  }
}

WebSocket Messages

// Real-time dashboard updates
{
  "type": "TELEMETRY_UPDATE",
  "session_id": "sess_abc123",
  "data": {
    "current_speed": 45.2,
    "current_score": 87,
    "events": ["lane_change"],
    "position": { "lat": 23.3441, "lng": 85.3096 }
  }
}

{
  "type": "VIOLATION_DETECTED",
  "session_id": "sess_abc123",
  "violation": {
    "type": "overspeed",
    "severity": "medium",
    "value": 72,
    "threshold": 60
  }
}

Face Verification API

// From face_engine.py
POST /api/v1/verification/verify
{
  "driver_id": "drv_123",
  "embedding": [0.123, -0.456, ...] // 512-dim
}

Response:
{
  "matched": true,
  "confidence": 0.92,
  "quality_score": 0.88,
  "anti_spoof_passed": true
}

// Cosine similarity threshold: 0.85
// Uses pgvector for efficient similarity search

Implementation Status

Component	Status	Location / Technology	Notes
API Gateway	✓ Built	`backend/gateway/` - FastAPI	Rate limiting, circuit breaker, WebSocket
Device Management	✓ Built	`backend/services/device-management-service/`	Registration, pairing, heartbeat, geofence
Test Session Service	✓ Built	`backend/services/test-session-service/`	Session lifecycle, Kafka integration
Driving Monitor	✓ Built	`backend/services/driving-monitor/`	Behavior analysis, scoring algorithm
Face Verification	✓ Built	`backend/services/driver-verification-service/`	Enrollment, cosine similarity, pgvector ready
Evidence Collection	✓ Built	`backend/services/evidence-collection/`	Multi-source aggregation, privacy engine
Kafka Producer/Consumer	✓ Built	`backend/shared/events/`	Shared event schemas, producer client
Mobile App (React Native)	✓ Built	`mobile/src/`	Test screens, verification, results
Edge MQTT Broker	⚠ Partial	Docker (Mosquitto)	Config ready, needs edge deployment scripts
AI Inference (TensorRT)	⚠ Partial	`ai-ml/`	Models exist, Jetson deployment needed
Parivahan/Sarathi API	○ Planned	Government API integration	Requires MoU with state transport dept
DigiLocker Push	○ Planned	NAD/DigiLocker API	Requires government partnership

Deployment Architecture

☁️ Cloud (AWS)

EKS: Kubernetes for all microservices
RDS PostgreSQL: Primary database with pgvector
ElastiCache Redis: Caching, rate limiting
MSK (Kafka): Event streaming
S3: Video evidence storage
CloudFront: CDN for mobile assets

Defined in: infrastructure/terraform/main.tf

🏢 Edge (Per RTO)

NVIDIA Jetson AGX: AI inference
Mosquitto: Local MQTT broker
Redis: Local cache
NVR: Local video recording
4G/5G Router: Failover connectivity

Defined in: infrastructure/docker/docker-compose.yml