Yookr Logo

Architecture Overview

Deep dive into the backend stack and infrastructure integrations.

This guide provides an overview of how the Prediction System is built and how its internal services interact to deliver reliable predictions.

Table of Contents

System Overview

The core of the system is the Prediction API, a high-performance backend built in Rust. It acts as the central coordinator for: 1. Job Orchestration: Managing which models run, for which users, and on what hardware. 2. Schema Governance: Enforcing immutable source versions to prevent breaking changes. 3. Data Aggregation: Standardizing telemetry from various hardware types into a unified prediction format.

Service Integration

The Prediction API does not operate in isolation. It relies on a microservice ecosystem to manage hardware, persistence, and real-time data distribution:

Management API Connection

The system relies on the central Yookr Management API for hardware definitions, user permissions, and organisation data.

  • Resiliency: The backend uses a resilient client built with reqwest and reqwest-retry. It implements an ExponentialBackoff policy (max 3 retries) to handle transient network failures or temporary service unavailability.
  • Lifecycle Management: The API orchestrates the creation and deletion of Virtual Sensors in the management backend whenever a Job is configured or removed.
  • Security: All service-to-service communication is secured via Authorization tokens, ensuring that the Prediction API only modifies resources it has explicit authority over.

Database Layer

All persistent data (Jobs, Source Versions, and Predictions) is stored in MySQL.

  • Asynchronous Access: We use the sqlx crate for non-blocking database interactions, allowing the API to handle high concurrent request volumes.
  • Repository Pattern: The infrastructure layer is organized into strict repositories (e.g., JobRepository, TargetRepository) to isolate SQL logic from business services.
  • Data Integrity: Multi-step setup operations are executed within database transactions (using sqlx::Transaction) to ensure consistency between related entities.
  • Sequential Processing: When managing heavy relational graphs (like deleting a job with millions of historical predictions), the service layer uses sequential processing and connection pooling to prevent database timeouts and connection exhaustion.
  • Management Backend: The yookr-management companion service utilizes a dual-database approach, storing relational metadata in MySQL and document-based payload snapshots in MongoDB.

Message Broker (RabbitMQ)

For real-time applications, the system integrates with RabbitMQ to publish prediction results as they are ingested.

  • Streaming: New predictions are asynchronously published to a dedicated queue using the lapin crate.
  • Decoupling: This allows external consumers (like notification services or live dashboards) to react to data immediately without polling the database.
  • Fault Tolerance: The RabbitMQ integration is designed to be optional; if the broker is unavailable at startup, the API continues to function, ensuring core prediction storage remains reliable. Connections are managed with automatic reconnection logic.

Internal Tech Stack

For developers looking to contribute to or troubleshoot the backend, here is the technical breakdown:

Domain-Driven Design

The codebase follows a tiered structure to isolate business rules from external technology:

  • domain: Core entities and business rules (Zero-dependency).
  • services: Orchestration logic and application protocols (e.g., JobService, SourceVersionService).
  • infrastructure: Implementation details including SQL repositories, HTTP clients, and message brokers.
  • handlers: The web presentation layer built on Actix-Web, managing routing, request validation, and response formatting.

Ingestion Pipeline Internals

The ingestion flow is optimized for extremely high write-throughput: 1. Validation: Every incoming batch is strictly validated against the strongly-typed schema defined in its associated Source Version. 2. Buffering & Bulk Commit: To minimize database round-trips, valid predictions are committed using bulk inserts where possible, significantly reducing disk I/O overhead. 3. Target state Sync: Virtual Sensor "Latest Value" targets are updated atomically alongside the insert to ensure that dashboard visualizations and weather widgets reflect the new data immediately. 4. Broker Broadcast: Once persisted, the batch is pushed to the RabbitMQ exchange for downstream consumption.