SAFER Documentation

Android Installation

Mon, 01 Jan 0001 00:00:00 +0000

SAFER Beta Installation Guide

Thanks for helping test the SAFER beta. This guide will walk you through installing the Android phone app and the WearOS watch app.

Before You Start

What You’ll Need

For the Android Phone App

An Android phone
The SAFER_Android.apk file

For the WearOS Watch App

An Android phone paired with a WearOS watch
A Windows, Mac, or Linux computer
The SAFER_WearOS.apk file
Both devices connected to the same home Wi-Fi or mobile hotspot

Important: WearOS installation will not work on the UC Davis Wi-Fi network because device-to-device communication is restricted.

App.tsx

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

This file is required for expo to define what happens upon app start.

Exports

Only a single function is exported within this file, and that is App(). This is the main that first starts upon app entry.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

System overview

┌─────────────────────────────────────────────┐
│ Web Client │
│ (map view, dispatch UI) │
└────────────────────┬────────────────────────┘
 │ REST / WebSocket
┌────────────────────▼────────────────────────┐
│ API Server │
│ (authentication, routing) │
└───────────┬─────────────────────────────────┘
 │
┌───────────▼──────────┐ ┌──────────────────┐
│ Database │ │ Message Broker │
│ (persistent data) │ │ (live updates) │
└──────────────────────┘ └──────────────────┘

Components

Web Client

A single-page application served as static files. Communicates with the API server over REST for CRUD operations and over WebSocket for live updates.

Architecture of the Daily Work Area Popup

Mon, 01 Jan 0001 00:00:00 +0000

Summary

The smallest useful design moves the daily popup gate from app launch semantics to screen popup semantics. The relevant work area screen owns the eligibility check when it becomes active. A tiny local persistence helper stores the last local date on which the popup was actually shown.

CPM History

Mon, 01 Jan 0001 00:00:00 +0000

CPM History Schema

Database

File: weather_cache.db
Engine: expo-sqlite

Table: `cpm_history`

Column	Type	Null	Notes
`cpm`	`REAL`	`NOT NULL`	One computed CPM value per successful minute tick.
`timestamp`	`INTEGER`	`NOT NULL`	Epoch milliseconds when the value was recorded.

Data Invariants

Each row stores only cpm and timestamp.
Values must be finite numbers (insertCpmRow validates inputs).
Retention is capped at 40 rows; oldest rows are removed first on insert overflow.

Access Patterns

Insert and bounded retention: insertCpmRow(cpm, timestamp?).
Recent read window: getRecentCpmRows(sinceTimestamp, limit).
Read ordering: newest first (ORDER BY timestamp DESC, rowid DESC).

CPM Pipeline

Mon, 01 Jan 0001 00:00:00 +0000

Scope

This document defines the runtime CPM pipeline from accelerometer samples to prediction consumption.

Canonical Flow

App.tsx starts startActivityService() on mount and calls stopActivityService() on cleanup.
activityService starts expo-sensors accelerometer streaming at ~30 Hz.
Sensor samples are buffered in memory (src/sensors/accelerometer.ts), converted from g to m/s^2, timestamped from the native sensor event, and pruned to the last ~75 seconds.
activityService treats a CPM window as ready only when it spans nearly 60 seconds, allowing one configured sensor interval of tolerance.
Every 60 seconds, activityService reads the most recent ready window and calls computeCpmFrom60s(...) in src/model/inferenceActivity.ts, which consumes the collected 30 Hz window directly.
When CPM computation succeeds, one row is written to cpm_history in SQLite through src/db/cpmDb.ts.
Callers such as predictionHeatRisk and PredictionCoreTempCard consume getActivityCpm40Average() from activityService.

Readiness Contract (`getActivityCpm40Average`)

Window: last 40 minutes.
Minimum history: at least 35 rows.
Freshness: latest row must be <= 2 minutes old.
Return: average CPM when ready, otherwise null.

Supporting References

Schema: schemas/cpm-history.md
Diagram: ../diagrams/activity-cpm-pipeline.mmd

Invariants

Model behavior lives in src/model/inferenceActivity.ts; orchestration should stay in activityService.
The model consumes the collected 30 Hz window directly; there is no separate 60 Hz downsampling stage.
Each successful minute tick produces at most one persisted CPM row.
Storage shape, retention, and query ordering live in the schema doc.

context/DailyWorkAreaContext.ts

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

DailyWorkAreaProvider manages the full lifecycle of the application’s “daily work area” workflow.

The provider coordinates:

prompting the user to define a work area,
restoring prior work-area selections,
launching the work-area editor modal,
pre-caching weather data for relevant geographic regions,
seeding map state from device location,
and exposing shared work-area state through React context.

This module acts as the orchestration layer between:

components/DailyWorkAreaModal.tsx

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

This module implements a full-screen React Native modal for defining and editing a user’s “daily work area” using an interactive map interface.

The component combines:

map-based geographic selection
address autocomplete and geocoding
adjustable radius selection
work-area persistence actions
accessibility support
safe-area aware mobile layout behavior

The modal allows a user to:

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

What is SAFER?

CHANGE ME

Who is this guide for?

CHANGE ME

How this guide is organised

CHANGE ME

Section	What you’ll find
Getting Started	Installation and first login
The Map View	Navigating the live map and reading unit icons
Incident Management	Creating, assigning, and closing incidents
Settings	Account preferences and notification options

Getting help

CHANGE ME If something in this guide is unclear, please open a GitHub issue so we can improve it.

api/ndfdWeather.ts

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

This module fetches, validates, and normalizes hourly weather forecast data from the NOAA NDFD (National Digital Forecast Database) XML API into a strongly typed internal format.

Its responsibilities include:

Daily Work Area

Mon, 01 Jan 0001 00:00:00 +0000

Daily Work-Area Pre-Cache Behavior

Scope

This document defines the once-per-day work-area screen flow that pre-warms weather cache entries from a farmer-selected circular work area.

Canonical Flow

When the Home/work-area screen becomes focused, the app checks whether the local calendar day has already shown the work-area pre-cache modal.
If the day has not shown the modal, a blocking full-screen modal asks the farmer to define today’s work area by tapping a map center point, selecting an address suggestion, or finding a typed address, then choosing a radius.
The modal seeds from today’s saved area first; otherwise it pre-fills from the most recent prior work area within the fallback window; otherwise it opens centered on Sacramento and may recenter once to current device location if foreground permission succeeds before the farmer edits.
Save today’s area persists one DailyWorkAreaCircle for the current local day and marks the day handled.
Use previous work day is available only when a saved work area exists within the previous 7 local calendar days; it does not create a new circle for today, but it does mark today handled after pre-cache runs.
A top-right Close action is available only when no recent fallback exists; it dismisses the already-shown daily prompt without warming weather cells.
The chosen circle is expanded by one weather-cache cell (2.5 km) for safety, converted into deduped cache-cell center points, and passed to precacheWeatherForLocations(...).
precacheWeatherForLocations(...) warms one forecast cell per unique location by fetching and storing a fresh 24-hour forecast horizon for that cell.
Manual reopen/edit from Home uses the same modal and re-runs pre-cache when the farmer saves a new circle later that day.

Persistence Rules

One circle is stored per local day key (YYYY-MM-DD in device-local time).
Prompt-shown state is stored separately from daily circles so app launch alone cannot suppress the work-area prompt before the farmer reaches the Home/work-area screen.
Fallback lookup only considers the most recent prior saved work day within 7 days.
Daily pre-cache treats the current hour as part of the horizon when the upstream NDFD response includes it; otherwise it accepts the next 24 contiguous forecast hours.

Invariants

Daily work-area pre-caching does not change prediction weather sourcing; foreground and background predictions still use live device location.
Pre-cache writes must go through precacheWeatherForLocations(...), which uses a dedicated fetch/store warming path rather than the single-hour getWeatherPointCached(...) lookup contract.
The modal is blocking only for the first focused Home/work-area screen visit of the local day where the modal has not already appeared; later edits are user-initiated from Home and are dismissible.

components/Dashboard.ts

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

This module implements an interactive physiological temperature history dashboard for React Native.

It visualizes historical core body temperature data using:

a zoomable time-series chart
dynamic Y-axis scaling
pinch-to-zoom gestures
scrollable historical navigation
adaptive tick labeling
physiological temperature-zone overlays
localized time formatting
unit-system conversion support

The dashboard is designed for mobile performance and readability across a wide range of time spans, from one hour to one week.

IOS Installation

Mon, 01 Jan 0001 00:00:00 +0000

Accessing SAFER

SAFER runs in your web browser. No software installation is needed for day-to-day use.

Open your browser and navigate to the URL provided by your administrator.
You will be greeted by the SAFER login screen.

Supported browsers

Browser	Minimum version
Chrome / Edge	110+
Firefox	110+
Safari	16+

Note

SAFER requires JavaScript to be enabled. If you see a blank page, check that your browser has not blocked scripts for this site.

Local Setup

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites for SAFER for IOS/Android

On your system ensure that you have node installed
If you are making an Android an android build, ensure that you have the SDK installed and that the ANDROID_HOME environment variable is set

Reason behind the Daily Work Popup

Mon, 01 Jan 0001 00:00:00 +0000

Problem

The daily work area popup is currently tied too closely to the first app open for a calendar day. If the app opens and the relevant work area screen is not reached, the popup can be skipped for that day even though the user has not actually seen it.

Testing of the Daily Work Popup

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

This plan verifies the daily work area popup behavior described in:

docs/daily-work-area-popup/daily-work-area-popup-prd.md
docs/daily-work-area-popup/daily-work-area-popup-architecture.md

The main claim to prove is that the popup is gated by whether it has actually popped up for the current local day, not by whether the app has opened today.

Weather Caching

Mon, 01 Jan 0001 00:00:00 +0000

Weather Cache Schema

Database

File: weather_cache.db
Engine: expo-sqlite
Journal mode: WAL

Table: `forecast_points`

Column	Type	Null	Notes
`cell_id`	`TEXT`	`NOT NULL`	Spatial cache bucket key from lat/lon.
`forecast_time`	`TEXT`	`NOT NULL`	Canonical UTC hour key (`toHourKey(...)`).
`valid_to`	`INTEGER`	`NOT NULL`	Expiration timestamp in epoch milliseconds.
`payload`	`TEXT`	`NOT NULL`	JSON-serialized `WeatherPoint`.
`last_accessed`	`INTEGER`	`NOT NULL`	Epoch milliseconds for LRU eviction.

Primary key:

Environment

Mon, 01 Jan 0001 00:00:00 +0000

Environment Variable Files

You can make any number of environment variables in the root of the main SAFER for IOS and SAFER for Android repo. The default, and recommended is: .env

Specifying the Variables

To specify the variable, within your environment file simply put the variable name followed by an equals and the value:

components/PredictionCoreTempCard.ts

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

This component renders a real-time “Predicted Core Body Temperature” card that combines:

environmental heat stress (WBGT)
user physiological profile data
recent physical activity intensity
ML/ONNX-based inference

to estimate a user’s current core body temperature and heat-risk state.

Usage Guide

Mon, 01 Jan 0001 00:00:00 +0000

What is SAFER?

CHANGE ME

Who is this guide for?

CHANGE ME

How this guide is organised

CHANGE ME

Section	What you’ll find
Getting Started	Installation and first login
The Map View	Navigating the live map and reading unit icons
Incident Management	Creating, assigning, and closing incidents
Settings	Account preferences and notification options

Getting help

CHANGE ME If something in this guide is unclear, please open a GitHub issue so we can improve it.

Wear OS Installation

Mon, 01 Jan 0001 00:00:00 +0000

Accessing SAFER

Give up

Weather Caching Behavior

Mon, 01 Jan 0001 00:00:00 +0000

Scope

This document defines the runtime lookup policy for getWeatherPointCached(...) in src/services/weatherService.ts. Daily work-area pre-warming uses the same weather service module but follows its own dedicated 24-hour horizon warming path through precacheWeatherForLocations(...).

WatchOS Installation

Mon, 01 Jan 0001 00:00:00 +0000

Accessing SAFER

You can’t, it doesn’t yet exist

components/TestCoreTempCard.ts

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

TestCoreTempCard is a lightweight developer/testing component used to manually validate the core temperature inference pipeline.

The component provides a deterministic test harness around runCoreTempInference by:

Supplying a fixed set of known inputs

SAFER Documentation

Android Installation

SAFER Beta Installation Guide

Before You Start

What You’ll Need

For the Android Phone App

For the WearOS Watch App

App.tsx

Purpose

Exports

Architecture

System overview

Components

Web Client

Architecture of the Daily Work Area Popup

Architecture: Daily Work Area Popup

Summary

CPM History

CPM History Schema

Database

Table: cpm_history

Data Invariants

Access Patterns

CPM Pipeline

Scope

Canonical Flow

Readiness Contract (getActivityCpm40Average)

Supporting References

Invariants

context/DailyWorkAreaContext.ts

Purpose

components/DailyWorkAreaModal.tsx

Purpose

Introduction

What is SAFER?

Who is this guide for?

How this guide is organised

Getting help

api/ndfdWeather.ts

Purpose

Daily Work Area

Daily Work-Area Pre-Cache Behavior

Scope

Canonical Flow

Persistence Rules

Invariants

components/Dashboard.ts

Purpose

IOS Installation

Accessing SAFER

Supported browsers

Local Setup

Prerequisites for SAFER for IOS/Android

Reason behind the Daily Work Popup

Problem

Testing of the Daily Work Popup

Test Plan: Daily Work Area Popup

Purpose

Weather Caching

Weather Cache Schema

Database

Table: forecast_points

Environment

Environment Variable Files

Specifying the Variables

components/PredictionCoreTempCard.ts

Purpose

Usage Guide

What is SAFER?

Who is this guide for?

How this guide is organised

Getting help

Wear OS Installation

Accessing SAFER

Weather Caching Behavior

Scope

WatchOS Installation

Accessing SAFER

components/TestCoreTempCard.ts

Purpose

Table: `cpm_history`

Readiness Contract (`getActivityCpm40Average`)

Table: `forecast_points`