System Overview

Complete overview of the S-MA-C-H system, components, and the artwork monitoring workflow.

Components

Web Application (Angular)

Users: All roles Purpose: Central management and monitoring platform

Key Functions:

Manage artworks (categorized with tags)
Configure environmental monitoring thresholds per artwork
View active monitorings (stationary + transport)
Monitor real-time alerts and events
View historical monitoring data
Analyze sensor data
Generate artwork passports (v1.0.0)

StaRT Mobile Application (React Native)

Users: Administrators and Super-Admins (on-site) Developer: Jay Purpose: On-site monitoring execution

Key Functions:

View Ready artworks
Setup monitoring: Select type (stationary/transport), auto-detect dataloggers, configure thresholds
Start monitoring: Begin recording with GPS + timestamp
Stop monitoring: End recording with GPS + timestamp
Push events to backend (start, alerts, stop)
Capture photos during monitoring

Backend API (Spring Boot)

Technology: Java, Spring Boot, MongoDB Purpose: Central data and business logic

Key Functions:

RESTful API for web and mobile apps
Data management (MongoDB)
File storage (MinIO/S3)
Authentication (Keycloak integration)
Alert processing
Event-based workflow
Artwork passport generation (v1.0.0)

IoT Dataloggers

Manufacturer: AES Techno Purpose: Environmental monitoring

Hardware Setup:

1 Logger (box) connects via plug to 1 Sensor
1 Sensor contains 1-3 captors depending on model:
- Temperature (°C)
- Humidity (% RH)
- Accelerometer (3-axis, raw int16 stored / m/s² displayed) - indicates transport monitoring
Datalogger = Logger + Sensor (connected pair)

Data Flow:

Configuration: Administrator/Super-Admin (StaRT) → Bluetooth → Datalogger
Recording: Datalogger collects data locally
Alerts: Datalogger → Bluetooth → StaRT → Backend API → Web App
Upload: Datalogger → USB → Computer → S3

IoT Gateways (v0.4.0)

Purpose: Cellular relay for transport monitoring

Hardware Setup:

Installed in transport vehicle (cabin or trailer)
Collects data from nearby Dataloggers via Bluetooth
Relays data to Backend API via cellular network

Gateway Assignment:

During monitoring Setup, gateways are assigned with a position (cabin or trailer)
Each datalogger can optionally reference a gateway it connects through
Gateways are managed in the Inventory alongside loggers, sensors, and packaging

Artwork Model

An Artwork is the central resource in the system. Each artwork can have multiple monitoring sessions over time.

Artwork Structure

Organization > Artwork (with tags)

Artwork:
  status: draft > ready > standby > monitoring > analysing > archived
  ├── inclosure (static protection in museum/storage)
  ├── crate (transport protection)
  ├── Checklist (common monitoring tasks)
  ├── Base Configuration (thresholds + frequency for all devices)
  ├── Monitorings [0-N] (history of all monitoring sessions)
  │   ├── Monitoring 1 (completed) - stationary
  │   ├── Monitoring 2 (completed) - transport
  │   └── Monitoring 3 (in_progress) - Active monitoring
  ├── (v1.0.0) S3 Data Space (photos, uploads, analysis, documents)
  └── (v1.0.0) Passport (synthesis of all analyses)

Key Concepts:

1 Artwork can have multiple Monitorings over time (history)
Only 1 active Monitoring per Artwork at any time
Monitoring types:
- stationary: Museum/storage monitoring (uses inclosure)
- transport: Movement monitoring (uses crate, optionally inclosure inside depending on artwork)
Auto-detection: If accelerometer sensor detected → suggests transport type

API Path Parameter: Reference vs ID

The API uses the artwork reference (URL-safe slug like bayeux-tapestry-replica) in path parameters, not the MongoDB ObjectId. This makes URLs more readable and stable:

✅ GET /artworks/bayeux-tapestry-replica
❌ GET /artworks/674ebf66cf6f5c456e1e27a8

The reference field is unique per organization and serves as the primary identifier in API paths.

Inventory Items

All packaging and equipment are managed in the Inventory (4 types):

Logger (box) - IMEI unique identifier
Sensor - IMEI unique identifier
- Contains 1-3 captors (temperature, humidity, accelerometer)
Gateway (v0.4.0) - Cellular relay device (identity unique identifier)
- Installed in transport vehicle (cabin or trailer)
- Relays datalogger data via cellular network
Packaging:
- inclosure: Static protection (associated with artwork, optional in crate during transport)
- crate: Transport protection (used only for transport monitoring)

Datalogger Association:

Datalogger = Logger + Sensor (connected pair)
NOT stored in inventory as separate entity
Extracted from active monitorings (auto-detected by StaRT during Setup)
Each datalogger can optionally have its own config that overrides the monitoring-level base configuration
Each datalogger can optionally reference a gateway it connects through (v0.4.0)
Loggers and Sensors can show "in use" status in lists (link to Monitoring → Artwork)

Gateway Assignment (v0.4.0):

Gateways are assigned to a monitoring with a position (cabin or trailer)
Stored in Monitoring.gateways[] as GatewayAssignment records
Dataloggers can reference their gateway via Datalogger.gateway field

Inventory is shared across artworks (not sub-resources). Items are sold by S-MA-C-H to organizations (v1.0.0).

Configuration Inheritance

Configuration follows a 3-level inheritance chain:

Artwork.config → Monitoring.config → Datalogger.config

Artwork.config: Base configuration defined on the artwork (default thresholds)
Monitoring.config: Copied from artwork at Setup, can be adjusted. Serves as base for all dataloggers in this monitoring.
Datalogger.config (optional): Per-datalogger override. If null, inherits Monitoring.config. If set, completely overrides it for that specific datalogger.

Use case: Different sensor positions on an artwork may need different thresholds (e.g., stricter temperature range near fragile embroidery, more sensitive vibration thresholds at edges).

Artwork States

Artwork status is determined by its active monitoring:

State	Description	Based on Monitoring	Who	Can Cancel?
draft	Being configured	No monitoring	Administrator	✅ Yes
ready	Configured, no active monitoring	No active monitoring OR last monitoring completed	Administrator	✅ Yes (only when no active monitoring)
standby	Monitoring created, waiting for Start	1 monitoring in pending	System (after Setup)	❌ No (monitoring active)
monitoring	Recording active	1 monitoring in in_progress	System (after Start)	❌ No (monitoring active)
analysing (v1.0.0)	Data uploaded, awaiting analysis	1 monitoring in uploaded	System (after data upload)	❌ No
archived	Artwork no longer monitored	All monitorings completed	Administrator/Super-Admin	❌ No
cancelled	Artwork cancelled	-	Administrator/Super-Admin	-

Cancellation Restrictions

An artwork can only be cancelled when in draft or ready state. Once a monitoring is active (standby, monitoring, or analysing), the artwork cannot be cancelled to avoid disrupting active monitoring sessions. The monitoring must reach completed state first.

One Active Monitoring Per Artwork

An artwork can only have one active monitoring at a time (either pending or in_progress). Previous monitorings must reach ended or completed before creating a new one.

Monitoring States

Each monitoring session is auto-created by StaRT Setup and progresses through analysis:

v0.3.0 Scope

In v0.3.0, monitoring status stops at ended. The uploaded and completed statuses, along with the analysing artwork status, are planned for v1.0.0 with S3 data upload and expert analysis features.

State	Description	Data Collected	Who
pending	Monitoring created, waiting for Start	Type (stationary/transport), dataloggers detected, config overridden	Administrator/Super-Admin (StaRT Setup)
in_progress	Recording active, collecting events	start event, alerts, positions (if transport)	Administrator/Super-Admin (StaRT Start)
ended	Recording stopped	stop event	Administrator/Super-Admin (StaRT Stop)
uploaded (v1.0.0)	Data uploaded to S3, awaiting analysis	S3 data reference	System (USB upload)
completed (v1.0.0)	Expert analysis complete	Analysis, comments, charts	Administrator/Super-Admin (Web)

Monitoring Data Collection by State

pending (Phase 1 - Setup):

Type: stationary OR transport
Gateways: optional list of gateway assignments with position (v0.4.0)
Dataloggers: auto-detected list (Logger + Sensor pairs, optionally linked to a gateway)
Configuration: overridden or default from Artwork.baseConfig

in_progress (Phase 2 - Start → Events → Stop):

start event: timestamp + GPS location
alert events: threshold violations (temperature, humidity, accelerometer) with sensor type + values (v0.4.0)
position events: GPS tracking during journey (transport only), with optional telemetry (gyroscope, accelerometer, speed) (v0.4.0)
stop event: timestamp + GPS location

uploaded (Phase 3 - Data Upload):

S3 data reference (uploaded via USB)
Full sensor data available in S3

completed (Phase 4 - Expert Analysis):

Expert comments
Data analysis charts
Artwork passport updates (v1.0.0)
Reports

Monitoring Cannot Be Restarted

Once Stop is pressed, the monitoring enters ended state and CANNOT be restarted. To create a new monitoring session, use Setup again in StaRT to create a new monitoring.

Monitoring Workflow

Complete lifecycle from creation to analysis.

Phase 1: Setup (Administrator/Super-Admin using StaRT)

On-Site - Using StaRT Mobile App

Two paths to Start:

Path 1 - New Monitoring (Setup first):

Auth → Org → GET /artworks?status=ready → Select Artwork → Setup → Start

Path 2 - Resume Monitoring (Start later):

Auth → Org → GET /artworks?status=standby → Select Artwork → Start

Setup Actions (Path 1 only):

Authenticate in StaRT app
Select organization (if multiple in JWT)
GET /artworks?status=ready → List artworks ready for setup
Select Artwork
Press "Setup" button:
- Select monitoring type: stationary (museum) OR transport (movement)
  - Auto-suggest transport if accelerometer sensor detected
- Auto-detect dataloggers via Bluetooth
  - Displays list of detected Logger+Sensor pairs (dataloggers)
- Review/adjust configuration from Artwork.baseConfig:
  - Temperature thresholds
  - Humidity thresholds
  - Vibration thresholds
  - Recording frequency
- Push configuration to dataloggers (via Bluetooth)
POST /artworks/{reference}/monitorings → Creates monitoring
- Response: { "id": "monitoring-uuid", "status": "pending", "type": "transport", ... }

Result (both paths):

Monitoring object displayed (dataloggers, config)
StaRT stores monitoring-uuid in session
Ready for Start button
Artwork status: ready → standby (Path 1 only)

Monitoring Type Selection

stationary: Museum/storage monitoring (uses inclosure protection)
transport: Movement monitoring (uses crate, optionally inclosure inside depending on artwork)
Auto-suggestion: If accelerometer sensor detected, StaRT suggests transport type

Phase 2: Start (Administrator/Super-Admin using StaRT)

On-Site - Monitoring Location

Common for both paths:

Display Monitoring → Press "Start" Button

Date/Time Format: Epoch Milliseconds

All date/time fields in the API (date, created, updated) are serialized as epoch milliseconds (Unix timestamp in ms), not ISO 8601 strings. Example: 2025-01-08T10:00:00Z → 1736330400000

Press "Start" button:

Start dataloggers recording (Bluetooth command)

Push start event to API:

json

POST /artworks/{reference}/monitorings/events
{
  "type": "start",
  "severity": "info",
  "date": 1736330400000,
  "location": { "latitude": 49.276, "longitude": -0.702 },
  "sourceType": "monitoring",
  "source": "monitoring-uuid"
}

Result:

Monitoring status: pending → in_progress
Artwork status: standby → monitoring
StaRT opens session with selected monitoring
Dataloggers actively recording

Phase 3: During Monitoring (Real-time Events)

During monitoring, StaRT app pushes events to backend:

All events use unified endpoint:

POST /artworks/{reference}/monitorings/events

Source-Based Routing:

Backend uses sourceType + source to find the correct monitoring
No need for monitoringId in payload

Event Types:

Alert Events (threshold violations from sensor):

json

{
  "type": "alert",
  "severity": "warning",
  "date": 1736350200000,
  "location": { "latitude": 48.856, "longitude": 2.352 },
  "sourceType": "sensor",
  "source": "IMEI-sensor-123456789",
  "value": 25.5,
  "message": "25.5 > 22"
}

Backend finds active monitoring using this sensor IMEI

Position Events (GPS tracking from logger, transport only):

json

{
  "type": "position",
  "severity": "info",
  "date": 1736350500000,
  "location": { "latitude": 48.856, "longitude": 2.352 },
  "sourceType": "logger",
  "source": "IMEI-logger-987654321"
}

Backend finds active monitoring using this logger IMEI

Notification Events (v1.0.0) (user annotations):

json

{
  "type": "notification",
  "severity": "info",
  "date": 1736350800000,
  "location": { "latitude": 48.856, "longitude": 2.352 },
  "sourceType": "user",
  "source": "admin@bayeux.test",
  "message": "Rest stop",
  "tag": "Road damaged"
}

Backend broadcasts notification to all users in the organization

Web App Monitoring:

Administrator/Super-Admin: View real-time alerts, respond if needed
Viewers: View real-time alerts (read-only)

Alert Flow:

Datalogger detects threshold breach
    ↓ Bluetooth
StaRT Mobile receives alert
    ↓ API
Backend processes event
    ↓ SSE
Web App displays notification
Administrator/Viewers notified

Phase 4: Stop (Administrator/Super-Admin using StaRT)

On-Site - End of Monitoring

Administrator/Super-Admin:

During active session → Press "Stop" button:

Stop dataloggers recording (Bluetooth command)

Push stop event to API:

json

POST /artworks/{reference}/monitorings/events
{
  "type": "stop",
  "severity": "info",
  "date": 1736373600000,
  "location": { "latitude": 51.507, "longitude": -0.127 },
  "sourceType": "monitoring",
  "source": "monitoring-uuid"
}

Result:

Monitoring status: in_progress → ended
Artwork status: monitoring → ready
StaRT closes session
⚠️ Monitoring CANNOT be restarted

Monitoring Cannot Be Restarted

Once Stop is pressed, the monitoring is finalized and CANNOT be restarted. To create a new monitoring session for the same artwork, return to Phase 1 (Setup) to create a new monitoring.

Phase 5: Data Upload (USB → S3)

Later - Via Computer

Administrator/Super-Admin:

Connect datalogger to computer via USB
Small routing tool uploads data to S3:
- Path: organization/artwork/monitoring/datalogger-IMEI/
- Data includes: sensor readings, timestamps, raw data
S3 reference stored in monitoring

Result:

Monitoring status: ended → uploaded
Artwork status: ready → analysing

Phase 6: Analysis (Administrator/Super-Admin via Web App)

Web Application

Administrator (own org) or Super-Admin (all orgs):

View artwork with monitoring in Uploaded status
Download sensor data from S3 (using reference in monitoring)
Analyze:
- Temperature, humidity, vibration charts
- Threshold breaches
- Statistics (min, max, average)
- GPS route visualization (if transport)
- Photos during monitoring
Add expert comments to monitoring
Update artwork passport (v1.0.0):
- Risk score
- Monitoring history
Mark monitoring as Completed
Generate reports (v1.0.0)

Result:

Monitoring status: uploaded → completed
Artwork status: analysing → ready

Same Analysis Permissions

Both Administrator and Super-Admin can perform analysis. The only difference is scope:

Administrator: Can analyze their organization's artworks
Super-Admin: Can analyze any organization's artworks

Creating Additional Monitorings

An artwork can have multiple monitoring sessions over time (history).

To create a new monitoring:

Ensure artwork is in ready status (no active monitoring)
Return to Phase 1 (Setup)
Press "Setup" in StaRT app
This creates a NEW monitoring for the same artwork

Example: Bayeux Tapestry Artwork

Artwork: "Bayeux Tapestry"

inclosure: Custom climate-controlled protection
crate: Large transport crate
Base Configuration: Temp 15-25°C, Humidity 40-60%, Accelerometer ±16384 raw (≈±10 m/s² at ±2g), 5-min interval

Monitorings (created over time for same artwork):

Stationary Monitoring (Museum storage, December 2024):
- Type: stationary
- Status: completed
- Duration: 30 days
Transport Monitoring - Way Out (January 8, 2025):
- Type: transport
- Status: completed
- Route: Bayeux → London
Transport Monitoring - Way Back (later date):
- Type: transport
- Status: in_progress
- Route: London → Bayeux

Result: 1 Artwork with 3 separate Monitoring sessions over time

Artwork Reusability

The Artwork object (with configuration and equipment references) can be reused for multiple monitoring sessions. Once a monitoring is completed, create a new monitoring session by using Setup again.

Next Steps

User Roles & Permissions - Who can do what

System Overview ​

Components ​

Web Application (Angular) ​

StaRT Mobile Application (React Native) ​

Backend API (Spring Boot) ​

IoT Dataloggers ​

IoT Gateways (v0.4.0) ​

Artwork Model ​

Artwork Structure ​

Artwork States ​

Monitoring States ​

Monitoring Workflow ​

Phase 1: Setup (Administrator/Super-Admin using StaRT) ​

Phase 2: Start (Administrator/Super-Admin using StaRT) ​

Phase 3: During Monitoring (Real-time Events) ​

Phase 4: Stop (Administrator/Super-Admin using StaRT) ​

Phase 5: Data Upload (USB → S3) ​

Phase 6: Analysis (Administrator/Super-Admin via Web App) ​

Creating Additional Monitorings ​

Next Steps ​

System Overview

Components

Web Application (Angular)

StaRT Mobile Application (React Native)

Backend API (Spring Boot)

IoT Dataloggers

IoT Gateways (v0.4.0)

Artwork Model

Artwork Structure

Artwork States

Monitoring States

Monitoring Workflow

Phase 1: Setup (Administrator/Super-Admin using StaRT)

Phase 2: Start (Administrator/Super-Admin using StaRT)

Phase 3: During Monitoring (Real-time Events)

Phase 4: Stop (Administrator/Super-Admin using StaRT)

Phase 5: Data Upload (USB → S3)

Phase 6: Analysis (Administrator/Super-Admin via Web App)

Creating Additional Monitorings

Next Steps