Offline-First Field Inspection App for EU Digital Building Logbook: CRDT Sync and AI-Assisted Reporting

Architecture Blueprint & Data Orchestration for Offline-First Field Inspection Systems

The foundational engineering challenge for an offline-first field inspection app supporting the EU Digital Building Logbook (DBL) is the reconciliation of autonomous local data generation with centralized compliance requirements. The architecture must assume zero connectivity at the point of inspection, yet guarantee eventual consistency across distributed instances. This demands a topological shift from traditional client-server models to a Local-First mesh, where each field device operates as a sovereign node within a synchronized network.

Synchronization Topology & Conflict-Free Replicated Data Types (CRDTs)

Traditional online databases rely on a single source of truth. In the inspection domain, this is untenable. An inspector on a remote construction site in rural France or a refurbishment project in a basement level may experience intermittent or absent connectivity. The system must, therefore, treat each device as an authoritative writer, merging concurrent edits without data loss.

This is achieved through CRDT-based synchronization, specifically leveraging State-based CRDTs (CvRDTs). The core principle is that every update to a data unit (e.g., a detected defect, an inspection checklist item, or a measurement) is represented as a monotonic operation that converges towards a deterministic final state across all peers.

Engineering Stack for CRDT Sync:

| Layer | Technology Choice | Justification | | :--- | :--- | :--- | | Synchronization Protocol | Automerge (Rust/WASM) or Yjs (Core) | Both provide decentralized merge semantics. Yjs offers superior performance for complex text and array mutations common in report editing. Automerge excels in schema flexibility. For a regulatory compliance app, Yjs with a custom document model for inspection types provides the best balance of speed and structural consistency. | | Local Persistence | IndexedDB (via Dexie.js or idb-keyval) | Native to all modern mobile browsers (Progressive Web App). Supports structured data storage with indexing, enabling efficient local queries of thousands of inspection records. | | Offline Networking | WebRTC + Libp2p | For peer-to-peer sync when devices are in proximity (e.g., two inspectors on the same bridge). Libp2p provides the NAT traversal and peer discovery necessary for ad-hoc mesh networking. | | Backend Bridge | WebSockets (Persistent) + REST (Fallback) | For sync with the central DBL server. WebSockets provide real-time push of changes. REST is used for batch synchronization when a WebSocket connection is re-established after an extended offline period. | | Conflict Resolution Strategy | Last-Writer-Wins (LWW) with Application-Level Merge | While CRDTs handle concurrent writes, intentional conflicts (e.g., two inspectors contradicting a measurement) require a business-rule layer. LWW on a composite timestamp (device_id + logical_clock) provides a deterministic default. Application-level merge allows a supervisor to review and override the result post-sync. |

Core System Inputs, Outputs, and Failure Modes

Understanding the failure modes of an offline-first system is critical for regulatory compliance. The system must not simply fail; it must degrade gracefully and log the context of the failure for audit trails.

Input/Output/Failure Matrix:

| Component | Input | Expected Output | Failure Mode | Graceful Degradation | | :--- | :--- | :--- | :--- | :--- | | CRDT Document Engine | User input (text, photo UUID, measurement value). | A self-contained, versioned operation (Doc Op). | IndexedDB transaction fails due to storage quota. | Prompt user to free space. Queue operation in ephemeral memory with a pending flag. Retry on next write. | | Photo Capture & Compression | Raw camera stream (4-12 MB JPEG). | Compressed image (200-800 KB) + perceptual hash (pHash). | Camera hardware failure or permission denial. | Fallback to text-only description. Generate a null image UUID but flag the field as incomplete_media. | | Local Sync Engine (Peer-to-Peer) | Discovered peer via mDNS/Bonjour. | All pending Doc Ops exchanged and acknowledged. | Peer disappears mid-sync. | Retry logic with exponential backoff (3 attempts). On failure, continue local operations. Mark peer sync as incomplete. Full sync will occur when both connect to the cloud backend. | | Geolocation Module | GPS coordinates (1 Hz). | GeoJSON Point with timestamp and accuracy (in meters). | GPS signal lost (underground or deep inside structure). | Cache last known position. Prompt user to manually place a pin on a cached offline map tile (pre-loaded OSM). | | AI Reporting Module (Client-Side) | Local CRDT document (inspection data + media pointers). | Draft report in structured JSON (conforming to DBL schema). | AI model (TFLite) fails to load or returns hallucination. | Disable AI features. Fallback to manual template filling. Report generation context (ai_disabled) is written to the document metadata. |

AI-Assisted Reporting: On-Device Inference and Offline Model Orchestration

The "AI-assisted reporting" component cannot rely on cloud APIs. It must run an on-device model, typically via TensorFlow Lite (TFLite) or CoreML. The model's job is twofold: (1) classify defects in captured images (e.g., "crack," "spalling," "corrosion") and (2) generate natural language descriptions from structured field data.

Model Architecture and Data Pipeline:

The core model for defect classification is a lightweight Convolutional Neural Network (CNN) such as MobileNetV3-Small, quantized to INT8 for speed. For natural language generation (NLG), a smaller Transformer variant like DistilGPT2 or a T5-small is fine-tuned on historical inspection reports. The pipeline is orchestrated as follows:

1. Image Capture: Photo is taken. A secondary low-resolution thumbnail is generated immediately for faster AI processing.
2. Local Inference: The TFLite runtime processes the image. Output is a probability vector across n defect classes.
3. Data Fusion: The classification results are merged with the structured input (location, inspector notes, measurement) into a prompt template.
4. NLG Inference: The prompt is fed to the local LLM. The model returns a draft paragraph for the report.
5. Post-processing: A rule-based script sanitizes the output (spell-check, limit length, flag uncertain phrases).

Configuration Template (YAML):

# model_config.yaml
ai:
  image_classifier:
    model_path: "/models/defect_detector_quant_v3.tflite"
    labels_path: "/models/labels_defect.txt"
    confidence_threshold: 0.65
    # Defines minimum confidence for automatic tagging
    input_shape: [224, 224, 3]
    normalize:
      mean: [127.5, 127.5, 127.5]
      std: [127.5, 127.5, 127.5]

  report_generator:
    model_path: "/models/report_draft_small_v2.tflite"
    max_length: 256
    temperature: 0.7
    # Lower temperature = more deterministic, less creative
    prompt_prefix: "Inspecteur: observation sur le chantier. Défaut: {defect_class}. Localisation: {location}. Note technique: {note}."

  fallback:
    enable_rules_based_fallback: true
    # If NLG model fails, use simple template replacement
    template: "Defect de type {defect_class} localisé à {location}. Note: {note}."

The AI module must be designed to never block the user flow. If the model takes longer than 2 seconds, the operation is queued, and the user continues to the next field. The report is later updated in the background. This asynchrony is critical for user experience in the field.

The Digital Building Logbook (DBL) Schema Mapping

The architectural design must ensure that the internal data model maps seamlessly to the emerging EU DBL standards, specifically the EN 17479:2021 and the proposed ISO 19650 extensions for building logbooks. The local-first data model, represented in JSON Schema, must be a superset of the DBL requirement.

Core Entities and Relationships:

• BuildingAsset: A unique building identified by its EPC (Energy Performance Certificate) ID or a national building register ID.
• InspectionEvent: A specific instance of an inspection. Contains inspector_id, timestamp, gps_location.
• InspectionItem: A single record of observation. Contains defect_class, media_uuid, measurement, status (compliant, non-compliant, requires_further).
• ReportDocument: The aggregated output. May contain multiple InspectionEvent and InspectionItem references. This is the submission artifact to the DBL.

Database Schema Mockup (TypeScript):

// db_schema.ts

interface BuildingAsset {
  dblUUID: string;
  address: {
    street: string;
    city: string;
    country: string; // ISO 3166-1 alpha-2
    postCode: string;
  };
  assetProperties: {
    constructionYear: number;
    floorArea: number; // m^2
    energyPerformanceClass: 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G';
    // Additional fields from EPC database
  };
  systemMetadata: {
    createdTimestamp: number; // Unix ms
    lastModifiedTimestamp: number;
    versionCounter: number; // For CRDT merge tracking
  };
}

interface InspectionEvent {
  eventUUID: string; // UUID v4
  parentAssetUUID: string; // FK to BuildingAsset
  eventType: 'SITE_VISIT' | 'REMOTE_ASSESSMENT' | 'REVIEW';
  startTimestamp: number;
  endTimestamp: number | null; // Still in progress
  inspectorID: string;
  gpsCoordinates: GeoJSON.Point | null;
  // Local-first fields
  localDeviceID: string; // Unique device identifier
  isOfflineCreated: boolean;
  syncStatus: 'PENDING' | 'PARTIAL' | 'COMPLETE';
}

interface InspectionItem {
  itemUUID: string;
  parentEventUUID: string; // FK to InspectionEvent
  category: string; // e.g., "STRUCTURAL", "HVAC", "FIRE_SAFETY"
  defectClass: string | null; // e.g., "CRACK_TYPE_A"
  measurement: {
    type: 'LENGTH' | 'WIDTH' | 'DEPTH' | 'TEMPERATURE' | 'HUMIDITY';
    value: number;
    unit: string; // e.g., "mm", "°C"
    accuracy: number; // ±mm or ±°C
  } | null;
  mediaReferences: string[]; // Array of UUIDs referencing local media store
  inspectorNotes: string;
  aiSuggestion: string | null; // From local NLG model
  // Audit trail
  createdOnDevice: string;
  createdTimestamp: number;
  lastModifiedTimestamp: number;
}

interface ReportDocument {
  reportUUID: string;
  assetUUID: string;
  eventsIncluded: string[]; // Array of eventUUIDs
  status: 'DRAFT' | 'VALIDATION' | 'SUBMITTED' | 'REJECTED';
  content: any; // The actual report payload, potentially in JSON or a serialized CRDT doc
  submissionTimestamp: number | null;
  digitalSignatureHash: string | null; // Post-submission signature
}

This schema is designed to be both human-readable and machine-parseable. The use of systemMetadata and localDeviceID fields is non-negotiable for offline-first conflict resolution. When two inspectors submit conflicting updates for the same InspectionItem, the system uses lastModifiedTimestamp combined with a deterministic tie-breaker (e.g., lower deviceID wins) before escalating to the application-level conflict resolver.

Data Integrity and Audit Trail Architecture

Regulatory compliance demands an immutable audit trail. This is particularly challenging in a system that allows offline edits. The architecture must implement a Verifiable Log pattern, even in the offline state.

1. Local Operation Log: Every operation (create, update, delete) on any InspectionItem or ReportDocument is appended to a local append-only log (implemented as a separate IndexedDB object store or a simple SQLite table).
2. Hash Chaining: Each operation record contains a SHA-256 hash of the previous operation's hash, forming a local blockchain. When online, these local hash chains are aggregated and transmitted to the cloud backend.
3. Reconciliation Proof: The cloud backend stores the entire history. A new sync session begins with the device providing the last known root hash of its local chain. The backend verifies this against its stored state. Discrepancies are resolved by fetching the missing operations.

Mockup of Audit Log Entry (JSON):

{
  "operation_id": "op-20251028-001",
  "previous_hash": "a6b4c8d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8",
  "timestamp": 1730102400000,
  "actor": "field_inspector_07",
  "action": "UPDATE",
  "target_storage": "InspectionItem",
  "target_uuid": "8a9b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "diff_patch": {
    "defectClass": {
      "from": "CRACK_UNKNOWN",
      "to": "CRACK_TYPE_B"
    },
    "inspectorNotes": {
      "from": "Hairline crack found.",
      "to": "Hairline crack found. Depth estimated at 2mm."
    }
  },
  "device_id": "phone-inspector-03-uuid",
  "signature": "Base64EncodedSignatureUsingDevicePrivateKey"
}

The inclusion of a device-specific digital signature (signature) ensures that even offline operations are cryptographically bound to the physical device, providing a robust non-repudiation mechanism that is crucial for legal disputes or insurance claims.

Comparative Engineering Stacks: A Technical Trade-Off Analysis

Choosing the wrong foundational stack for an offline-first, CRDT-based app can lead to catastrophic sync failures. The following table compares the three dominant approaches for building the core synchronization layer.

| Criteria | Stack A: Automerge + Rust/WASM | Stack B: Yjs + Native Web API | Stack C: Custom Operational Transformation (OT) | | :--- | :--- | :--- | :--- | | Data Model Flexibility | Excellent. Schema-less or S.O.C. (Schema on Client). Ideal for unstructured inspection notes. | Very Good. Schema-aware via custom data types. High performance for arrays and text. | Poor. Must define all operations upfront. Brittle to schema changes. | | Synchronization Performance | Good, but Rust/WASM overhead can be felt on lower-end devices for large documents (>50k ops). | Excellent for documents up to 100k ops. Native Web APIs (Web Workers) offload computation. | Very Good for small, well-defined operations. Degrades exponentially with document complexity. | | Conflict Resolution | LWW with automatic merge. Higher risk of concurrent edit loss if not careful. | Intent-aware merge. Yjs uses operational transform internally but exposes CRDT semantics. Best for user-facing collaboration. | Requires custom conflict resolution logic for every operation type. Extremely high engineering cost. | | Total Sync Complexity | Medium. Automerge handles transport, but WASM debugging is hard. | Low to Medium. Yjs is pure JavaScript/TypeScript. Easier to debug and profile. | High. Must build transport, persistence, and transformation layers from scratch. | | Offline First Support | Built-in. Designed for local-first. | Built-in. Native support for local persistence hooks. | Must be manually integrated. | | Maturity & Ecosystem | Maturing. Active research. Good for collaborative text editors. | Mature. Used in major collaborative editors (e.g., Atlassian, Realm). Best for production. | Technical debt trap. Not recommended for new projects. | | Recommended Use Case | When schema is unknown or rapidly evolving (R&D-heavy field). | Default recommendation for DBL inspection app. High performance, lower risk. | Legacy integration only. |

Conclusion on Stack Selection: For the EU Digital Building Logbook app, Stack B (Yjs + Native Web API) is the optimal choice. It provides the necessary performance for large inspection documents with hundreds of photos and notes, has a mature ecosystem for debugging, and integrates seamlessly with IndexedDB for local persistence. Stack A is a viable alternative for research-oriented features, but Yjs offers a more stable foundation for a regulatory compliance application.

Security Architecture: Offline Encryption and Access Control

Security cannot be compromised in an offline mode. Users must authenticate once, and the device must maintain an encrypted session token that is stored securely.

1. Local Data Encryption: All IndexedDB stores are encrypted at rest using the Web Crypto API with AES-GCM. The encryption key is derived from the user's password using PBKDF2 with a high iteration count (100k+ iterations) and a device-bound salt.
2. Offline Token Storage: The session token is not stored in plaintext. It is stored in the IndexedDB encrypted store. The system never exposes the raw token to JavaScript memory except during the initial decryption for a network request.
3. Access Control Model (RBAC):
   • Inspector: Can create and edit InspectionItem and InspectionEvent. Cannot delete submitted ReportDocument.
   • Supervisor: Can view all items, assign tasks, and resolve application-level conflicts.
   • Regulator: Read-only access to final reports and audit logs.

This architecture ensures that even if a device is lost or stolen, the inspection data remains encrypted and inaccessible without the user's passphrase. The integration of these security principles with the offline-first data flow is what differentiates a professional-grade application from a prototype. For a turnkey Intelligent-Ps SaaS Solutions (https://www.intelligent-ps.store/) deployment, these configurations would be pre-designed into the deployment pipeline, ensuring compliance with GDPR and EU eIDAS regulations from day one.