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 collections and artworks
Configure environmental monitoring thresholds per artwork
View active monitorings (static + 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 (static/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, mm/s) - 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

Artwork Model

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

Artwork Structure

Organization > Collection > Artwork

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) - Static
  │   ├── Monitoring 2 (Completed) - Transport
  │   └── Monitoring 3 (InProgress) - 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:
- static: 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

Inventory Items

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

Logger (box) - IMEI unique identifier
Sensor - IMEI unique identifier
- Contains 1-3 captors (temperature, humidity, accelerometer)
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)
Loggers and Sensors can show "in use" status in lists (link to Monitoring → Artwork)

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

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 `InProgress`	System (after Start)	❌ No (monitoring active)
Analysing	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 InProgress). 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:

State	Description	Data Collected	Who
Pending	Monitoring created, waiting for Start	Type (static/transport), dataloggers detected, config overridden	Administrator/Super-Admin (StaRT Setup)
InProgress	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	Data uploaded to S3, awaiting analysis	S3 data reference	System (USB upload)
Completed	Expert analysis complete	Analysis, comments, charts	Administrator/Super-Admin (Web)

Monitoring Data Collection by State

Pending (Phase 1 - Setup):

Type: static OR transport
Dataloggers: auto-detected list (Logger + Sensor pairs)
Configuration: overridden or default from Artwork.baseConfig

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

Start event: timestamp + GPS location
Alert events: threshold violations (temperature, humidity, vibration)
Position events: GPS tracking during journey (transport only)
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: static (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/{id}/monitoring → 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

Static: 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

Press "Start" button:

Start dataloggers recording (Bluetooth command)

Push start event to API:

json

POST /artworks/{artworkId}/monitorings/events
{
  "type": "start",
  "severity": "info",
  "date": "2025-01-08T10:00:00Z",
  "location": { "latitude": 49.276, "longitude": -0.702 },
  "sourceType": "monitoring",
  "source": "monitoring-uuid"
}

Result:

Monitoring status: Pending → InProgress
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/{artworkId}/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": "2025-01-08T15:30:00Z",
  "location": { "latitude": 48.856, "longitude": 2.352 },
  "sourceType": "sensor",
  "source": "IMEI-sensor-123456789",
  "value": 25.5,
  "message": "high_temperature"
}

Backend finds active monitoring using this sensor IMEI

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

json

{
  "type": "position",
  "severity": "info",
  "date": "2025-01-08T15:35:00Z",
  "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": "2025-01-08T15:40:00Z",
  "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/{artworkId}/monitorings/events
{
  "type": "stop",
  "severity": "info",
  "date": "2025-01-08T22:00:00Z",
  "location": { "latitude": 51.507, "longitude": -0.127 },
  "sourceType": "monitoring",
  "source": "monitoring-uuid"
}

Result:

Monitoring status: InProgress → 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 18-22°C, Humidity 45-55%, Vibration max 5mm/s, 5-min interval

Monitorings (created over time for same artwork):

Static Monitoring (Museum storage, December 2024):
- Type: static
- 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: InProgress
- 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 ​

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

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