ARCHITECTURE.md

UBI Risk Coprocessor Architecture

Overview

The UBI Risk Coprocessor is designed to process vehicle telemetry data and calculate insurance risk scores within a Cartesi machine while maintaining external API communication for data ingestion.

System Components

1. External Data Flow

• DIMO API Integration
  • Vehicle telemetry data fetched via frontend
  • Data formatted according to DimoTelemetryData interface
  • API calls remain external to coprocessor

2. Coprocessor Components

• Input Handler

  • Receives formatted telemetry data
  • Validates input structure
  • Prepares data for risk model

• Risk Analysis Model

  • Runs within Docker container
  • Processes validated telemetry data
  • Uses logistic regression for risk calculation
  • Coefficients configured for:
    • Vehicle usage patterns
    • Driving behavior metrics
    • Location-based risk factors

• Output Processor

  • Scales results for blockchain (18 decimals)
  • Formats response for smart contract consumption

3. Data Flow Architecture

[External APIs] -> [Frontend] -> [Smart Contract] -> [Coprocessor]
     |               |              |                    |
     |               |              |                    |
DIMO API         Data Format    Input Notice        Risk Model
     |               |              |                    |
Vehicle Data    JSON Payload    Blockchain          Calculation
     |               |              |                    |
Real-time      Standardized    Transaction         Risk Score

Implementation Requirements

Docker Configuration

• Base image: cartesi/node:20.11
• Environment setup for Node.js runtime
• Dependencies installation
• Model configuration loading

Risk Model Integration

• Model runs entirely within coprocessor
• No external API calls during calculation
• Pre-configured coefficients
• Input validation and sanitization

Data Processing Flow

1. External data collection (frontend)
2. Data formatting and validation
3. Coprocessor input processing
4. Risk model calculation
5. Result scaling and output

Security Considerations

• Input validation at multiple levels
• No external network access during calculation
• Deterministic processing
• Verifiable outputs

Testing Strategy

1. Unit tests for risk model
2. Integration tests for data flow
3. End-to-end tests with mock data
4. Performance benchmarking

Deployment Checklist

• Docker container configuration
• Risk model coefficient validation
• Input/output format verification
• Network isolation confirmation
• Performance optimization
• Security audit