Fieldworker’s browser

Leaflet map · GPS · Attribute forms

Store first, synchronize later

When connectivity becomes available

Server API → PostgreSQL / PostGIS

Validation · Authentication · Duplicate-safe writes

# Create a vanilla JavaScript project
npm create vite@latest field-collector -- --template vanilla

# Enter the project
cd field-collector

# Install the starter dependencies
npm install

# Install GIS and local storage libraries
npm install leaflet localforage

# Install the PWA build plugin
npm install -D vite-plugin-pwa

field-collector/
├── index.html
├── vite.config.js
├── public/
│   ├── data/
│   │   └── field-zones.geojson
│   └── icons/
│       ├── icon-192.png
│       └── icon-512.png
└── src/
    ├── main.js
    ├── outbox.js
    ├── style.css
    └── sw.js

import { defineConfig } from "vite";
import { VitePWA } from "vite-plugin-pwa";

export default defineConfig({
  plugins: [
    VitePWA({
      // Use our own service worker.
      strategies: "injectManifest",

      // Location and output name of the custom service worker.
      srcDir: "src",
      filename: "sw.js",

      // Precache the application shell and small static resources.
      injectManifest: {
        globPatterns: [
          "**/*.{html,js,css,svg,png,ico,webmanifest,json}"
        ],

        // Large map packages are downloaded selectively instead.
        globIgnores: [
          "**/offline-tiles/**"
        ],

        // Prevent unexpectedly large resources entering the app shell.
        maximumFileSizeToCacheInBytes: 2 * 1024 * 1024
      },

      // Define the installation experience.
      manifest: {
        name: "Offline Field Collector",
        short_name: "Field Collector",
        description: "Offline-first geographic field data collection.",
        start_url: "/",
        scope: "/",
        display: "standalone",
        background_color: "#f8fafc",
        theme_color: "#174b3a",
        icons: [
          {
            src: "/icons/icon-192.png",
            sizes: "192x192",
            type: "image/png"
          },
          {
            src: "/icons/icon-512.png",
            sizes: "512x512",
            type: "image/png"
          }
        ]
      },

      // Test the production-built worker rather than relying on
      // development-server behavior for offline verification.
      devOptions: {
        enabled: false
      }
    })
  ]
});

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />

    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0"
    />

    <meta name="theme-color" content="#174b3a" />

    <link rel="manifest" href="/manifest.webmanifest" />

    <title>Offline Field Collector</title>
  </head>

  <body>
    <header class="app-header">
      <div>
        <h1>Field Collector</h1>
        <p>Capture observations offline</p>
      </div>

      <span id="app-status" role="status" aria-live="polite">
        Initializing…
      </span>
    </header>

    <section class="toolbar">
      <button id="gps-start" type="button">
        Start GPS
      </button>

      <button id="gps-stop" type="button" disabled>
        Stop GPS
      </button>

      <button id="prepare-tiles" type="button">
        Prepare offline map
      </button>

      <button id="sync-now" type="button">
        Sync now
      </button>
    </section>

    <section class="survey-panel">
      <form id="entry-form">
        <label>
          Observation category

          <select name="category" required>
            <option value="vegetation">Vegetation</option>
            <option value="water">Water</option>
            <option value="infrastructure">Infrastructure</option>
            <option value="other">Other</option>
          </select>
        </label>

        <label>
          Field notes

          <textarea
            name="notes"
            rows="2"
            maxlength="5000"
            placeholder="Describe the observation"
          ></textarea>
        </label>

        <button type="submit">
          Save observation
        </button>
      </form>

      <p id="position-status">
        Select a location on the map or obtain a GPS fix.
      </p>

      <p id="queue-status">No records loaded.</p>

      <ul id="record-list" aria-label="Saved observations"></ul>
    </section>

    <main id="map" aria-label="Field collection map"></main>

    <script type="module" src="/src/main.js"></script>
  </body>
</html>

* {
  box-sizing: border-box;
}

html,
body {
  margin: 0;
  height: 100%;
  font-family: system-ui, sans-serif;
  color: #172033;
  background: #f8fafc;
}

body {
  min-height: 100vh;
  display: flex;
  flex-direction: column;
}

button,
select,
textarea {
  font: inherit;
}

button {
  padding: 9px 12px;
  border: 1px solid #cbd5e1;
  border-radius: 6px;
  background: #ffffff;
  cursor: pointer;
}

button:disabled {
  cursor: not-allowed;
  opacity: 0.5;
}

.app-header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 16px;
  padding: 12px 18px;
  background: #174b3a;
  color: #ffffff;
}

.app-header h1,
.app-header p {
  margin: 0;
}

.app-header h1 {
  font-size: 1.2rem;
}

.app-header p {
  margin-top: 4px;
  font-size: 0.85rem;
}

#app-status {
  font-size: 0.85rem;
}

.toolbar {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
  padding: 10px 14px;
  background: #e8efe9;
}

.survey-panel {
  padding: 12px 14px;
  background: #ffffff;
  border-bottom: 1px solid #dbe2ea;
}

#entry-form {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  align-items: end;
}

#entry-form label {
  display: grid;
  gap: 5px;
  flex: 1 1 180px;
  font-size: 0.85rem;
}

textarea,
select {
  min-width: 0;
  width: 100%;
  padding: 8px;
  border: 1px solid #cbd5e1;
  border-radius: 5px;
}

#position-status,
#queue-status {
  margin: 8px 0 0;
  font-size: 0.85rem;
}

#record-list {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  padding-left: 20px;
  margin: 8px 0 0;
  font-size: 0.8rem;
}

#map {
  flex: 1;
  min-height: 320px;
}

@media (max-width: 620px) {
  .app-header {
    align-items: flex-start;
    flex-direction: column;
    gap: 8px;
  }

  #entry-form {
    align-items: stretch;
    flex-direction: column;
  }
}

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "zone": "A",
        "name": "Sample survey zone"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [36.810, -1.280],
            [36.825, -1.280],
            [36.825, -1.295],
            [36.810, -1.295],
            [36.810, -1.280]
          ]
        ]
      }
    }
  ]
}

import localforage from "localforage";

// A named IndexedDB-backed store shared by the app and service worker.
export const outbox = localforage.createInstance({
  name: "FieldCollectorPWA",
  storeName: "field_entries",
  description: "Locally captured field observations"
});

const API_ENDPOINT = "/api/observations";

// Return all locally stored field records.
export async function listFieldEntries() {
  const records = [];

  await outbox.iterate((value, key) => {
    if (String(key).startsWith("entry:")) {
      records.push(value);
    }
  });

  // Newest observations appear first.
  return records.sort((a, b) => {
    return b.properties.captured_at.localeCompare(
      a.properties.captured_at
    );
  });
}

// Submit pending entries to the server.
// The server must enforce uniqueness for the record ID.
export async function syncPendingEntries() {
  const entries = [];

  await outbox.iterate((value, key) => {
    if (
      String(key).startsWith("entry:") &&
      value.syncStatus !== "synced" &&
      value.syncStatus !== "needs_review"
    ) {
      entries.push({ key, value });
    }
  });

  entries.sort((a, b) => {
    return a.value.properties.captured_at.localeCompare(
      b.value.properties.captured_at
    );
  });

  let sent = 0;

  for (const { key, value } of entries) {
    try {
      const response = await fetch(API_ENDPOINT, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Idempotency-Key": value.id
        },
        credentials: "same-origin",
        body: JSON.stringify(value)
      });

      // Most 4xx responses require user or data correction.
      // HTTP 408 and 429 are treated as retryable.
      if (
        response.status >= 400 &&
        response.status < 500 &&
        ![408, 429].includes(response.status)
      ) {
        const current = await outbox.getItem(key);

        if (current && current.syncStatus !== "synced") {
          await outbox.setItem(key, {
            ...current,
            syncStatus: "needs_review",
            lastSyncError: `HTTP ${response.status}`,
            lastAttemptAt: new Date().toISOString()
          });
        }

        continue;
      }

      // Stop the current batch on a transient server failure.
      if (!response.ok) {
        throw new Error(`Server returned HTTP ${response.status}`);
      }

      // Re-read the current record to avoid overwriting a successful
      // update made by another tab or a concurrent service worker.
      const current = await outbox.getItem(key);

      if (current && current.syncStatus !== "synced") {
        await outbox.setItem(key, {
          ...current,
          syncStatus: "synced",
          syncedAt: new Date().toISOString(),
          lastSyncError: null
        });
      }

      sent += 1;
    } catch (error) {
      const current = await outbox.getItem(key);

      if (current && current.syncStatus !== "synced") {
        await outbox.setItem(key, {
          ...current,
          syncStatus: "pending",
          syncAttempts: (current.syncAttempts ?? 0) + 1,
          lastAttemptAt: new Date().toISOString(),
          lastSyncError: String(error.message ?? error)
        });
      }

      // Stop so the remaining records can be retried later.
      // In a service-worker sync event, the rejection also allows
      // the browser to retry the background synchronization task.
      throw new Error(
        `Synchronization stopped after ${sent} successful records: ${error.message}`
      );
    }
  }

  return { sent, processed: entries.length };
}

import L from "leaflet";
import "leaflet/dist/leaflet.css";
import "./style.css";

import {
  outbox,
  listFieldEntries,
  syncPendingEntries
} from "./outbox.js";

// UI elements
const statusElement = document.getElementById("app-status");
const positionStatus = document.getElementById("position-status");
const queueStatus = document.getElementById("queue-status");
const recordList = document.getElementById("record-list");
const entryForm = document.getElementById("entry-form");

const gpsStartButton = document.getElementById("gps-start");
const gpsStopButton = document.getElementById("gps-stop");
const prepareTilesButton = document.getElementById("prepare-tiles");
const syncNowButton = document.getElementById("sync-now");

// This setting must be changed to true when a licensed,
// same-origin offline tile package is available.
const USE_LOCAL_TILE_PACKAGE = false;

// Initialize a Leaflet map centered on the sample survey area.
const map = L.map("map").setView([-1.2864, 36.8172], 13);

// Online-only demonstration basemap.
// Its tiles are deliberately not precached by this application.
if (USE_LOCAL_TILE_PACKAGE) {
  L.tileLayer("/offline-tiles/{z}/{x}/{y}.png", {
    minZoom: 8,
    maxZoom: 18,
    attribution: "Attribution for your licensed tile source"
  }).addTo(map);
} else {
  L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
    maxZoom: 19,
    attribution: "© OpenStreetMap contributors"
  }).addTo(map);
}

// Keep GPS selection separate from map display and database storage.
let selectedLocation = null;
let locationMarker = null;
let gpsWatchId = null;
let hasCenteredOnGps = false;

function setStatus(message) {
  statusElement.textContent = message;
}

function setSelectedLocation(latlng, accuracyM = null, source = "map") {
  selectedLocation = {
    lat: latlng.lat,
    lng: latlng.lng,
    accuracyM,
    source,
    capturedAt: new Date().toISOString()
  };

  // Create the marker once and update it on subsequent fixes.
  if (!locationMarker) {
    locationMarker = L.circleMarker(latlng, {
      radius: 8,
      color: "#ffffff",
      weight: 2,
      fillColor: "#0d8f64",
      fillOpacity: 1
    }).addTo(map);
  } else {
    locationMarker.setLatLng(latlng);
  }

  const accuracyText = Number.isFinite(accuracyM)
    ? ` · estimated accuracy ${Math.round(accuracyM)} m`
    : "";

  positionStatus.textContent =
    `${source === "gps" ? "GPS position" : "Selected position"}: ` +
    `${latlng.lat.toFixed(6)}, ${latlng.lng.toFixed(6)}` +
    accuracyText;
}

// Allow manual point selection as a GPS fallback.
map.on("click", (event) => {
  setSelectedLocation(event.latlng, null, "map");
});

function startGpsTracking() {
  // Geolocation normally requires HTTPS or localhost and user permission.
  if (!("geolocation" in navigator)) {
    setStatus("This browser does not support geolocation.");
    return;
  }

  if (gpsWatchId !== null) {
    return;
  }

  gpsWatchId = navigator.geolocation.watchPosition(
    (position) => {
      const {
        latitude,
        longitude,
        accuracy
      } = position.coords;

      const latlng = L.latLng(latitude, longitude);

      // Update the currently selected field location.
      setSelectedLocation(latlng, accuracy, "gps");

      // Center on the first fix without forcing the map to jump
      // on every later GPS update.
      if (!hasCenteredOnGps) {
        map.setView(latlng, 17);
        hasCenteredOnGps = true;
      }

      setStatus("GPS position updated.");
    },

    (error) => {
      const messages = {
        1: "Location permission was denied.",
        2: "The position is unavailable.",
        3: "The GPS request timed out."
      };

      setStatus(messages[error.code] ?? error.message);
    },

    {
      enableHighAccuracy: true,
      timeout: 15000,
      maximumAge: 5000
    }
  );

  gpsStartButton.disabled = true;
  gpsStopButton.disabled = false;

  setStatus("Waiting for GPS position…");
}

function stopGpsTracking() {
  if (gpsWatchId !== null) {
    navigator.geolocation.clearWatch(gpsWatchId);
    gpsWatchId = null;
  }

  gpsStartButton.disabled = false;
  gpsStopButton.disabled = true;

  setStatus("GPS tracking stopped.");
}

gpsStartButton.addEventListener("click", startGpsTracking);
gpsStopButton.addEventListener("click", stopGpsTracking);

async function loadFieldZones() {
  const response = await fetch("/data/field-zones.geojson");

  if (!response.ok) {
    throw new Error(
      `Unable to load field zones: HTTP ${response.status}`
    );
  }

  const geojson = await response.json();

  // Convert GeoJSON features into Leaflet layers.
  const zoneLayer = L.geoJSON(geojson, {
    style: {
      color: "#147d53",
      weight: 2,
      fillColor: "#38a169",
      fillOpacity: 0.2
    },

    onEachFeature: (feature, layer) => {
      const zoneName = feature.properties?.name ?? "Unnamed zone";

      layer.bindTooltip(String(zoneName));
    }
  });

  zoneLayer.addTo(map);
}

// Report failures without taking down data capture.
loadFieldZones().catch((error) => {
  console.error(error);
  setStatus("Survey zones unavailable; local capture remains usable.");
});

function createObservation(formData) {
  if (!selectedLocation) {
    throw new Error(
      "Select a map location or obtain a GPS fix before saving."
    );
  }

  const now = new Date().toISOString();

  return {
    type: "Feature",

    // Stable local ID, also used as the server idempotency key.
    id: crypto.randomUUID(),

    // GeoJSON always stores coordinate arrays as [longitude, latitude].
    geometry: {
      type: "Point",
      coordinates: [
        selectedLocation.lng,
        selectedLocation.lat
      ]
    },

    properties: {
      category: String(formData.get("category")),
      notes: String(formData.get("notes") ?? "").trim(),

      accuracy_m: selectedLocation.accuracyM,
      location_source: selectedLocation.source,

      captured_at: selectedLocation.capturedAt ?? now,
      client_created_at: now
    },

    // Synchronization metadata stays outside the feature properties.
    syncStatus: "pending",
    syncAttempts: 0,
    createdAt: now,
    lastSyncError: null
  };
}

entryForm.addEventListener("submit", async (event) => {
  event.preventDefault();

  try {
    const formData = new FormData(entryForm);
    const observation = createObservation(formData);

    // Persist the observation before attempting any API request.
    await outbox.setItem(
      `entry:${observation.id}`,
      observation
    );

    setStatus("Observation saved locally.");

    // Reset the notes while leaving the category selected.
    entryForm.elements.notes.value = "";

    await refreshRecordList();

    // Queue a server synchronization attempt when possible.
    await scheduleSync();

  } catch (error) {
    console.error("Could not save observation:", error);
    setStatus(error.message ?? "Failed to save observation.");
  }
});

import {
  precacheAndRoute,
  cleanupOutdatedCaches
} from "workbox-precaching";

import { syncPendingEntries } from "./outbox.js";

// Injected by vite-plugin-pwa during the production build.
// Includes the application's generated HTML, JS, CSS, and small data assets.
precacheAndRoute(self.__WB_MANIFEST);

// Clean up outdated Workbox precaches after application updates.
cleanupOutdatedCaches();

const TILE_CACHE = "field-offline-tiles-v1";

// Intercept only GET requests for our own offline tile package.
// Third-party basemaps are intentionally excluded.
self.addEventListener("fetch", (event) => {
  const request = event.request;
  const url = new URL(request.url);

  if (
    request.method !== "GET" ||
    url.origin !== self.location.origin ||
    !url.pathname.startsWith("/offline-tiles/")
  ) {
    return;
  }

  event.respondWith(
    (async () => {
      const cache = await caches.open(TILE_CACHE);

      // Prefer a prepared or previously cached local tile.
      const cached = await cache.match(request);

      if (cached) {
        return cached;
      }

      // Online fallback: fetch and cache only same-origin package files.
      try {
        const response = await fetch(request);

        if (response.ok) {
          await cache.put(request, response.clone());
        }

        return response;
      } catch {
        // Do not pretend a missing tile was successfully rendered.
        return new Response("Tile unavailable offline.", {
          status: 503,
          headers: {
            "Content-Type": "text/plain"
          }
        });
      }
    })()
  );
});

// Enhanced synchronization in browsers supporting Background Sync.
// The shared module accesses the same IndexedDB-backed LocalForage store.
self.addEventListener("sync", (event) => {
  if (event.tag === "sync-observations") {
    event.waitUntil(syncPendingEntries());
  }
});

public/
└── offline-tiles/
    ├── manifest.json
    └── z/
        └── x/
            └── y.png

{
  "tiles": [
    "/offline-tiles/12/1205/1538.png",
    "/offline-tiles/12/1205/1539.png",
    "/offline-tiles/12/1206/1538.png"
  ]
}

async function prepareOfflineTilePackage() {
  prepareTilesButton.disabled = true;

  try {
    setStatus("Preparing offline map tiles…");

    // This manifest describes the package for the current study area.
    const response = await fetch("/offline-tiles/manifest.json");

    if (!response.ok) {
      throw new Error(
        "Tile manifest unavailable. Prepare a licensed tile package first."
      );
    }

    const manifest = await response.json();

    if (!Array.isArray(manifest.tiles) || manifest.tiles.length === 0) {
      throw new Error("The tile package contains no tile paths.");
    }

    // Cache key must match the service worker's dedicated tile cache.
    const cache = await caches.open("field-offline-tiles-v1");
    const tilePaths = [...new Set(manifest.tiles)];

    let completed = 0;

    // Small batches limit concurrency and make progress visible.
    const batchSize = 30;

    for (let i = 0; i < tilePaths.length; i += batchSize) {
      const batch = tilePaths.slice(i, i + batchSize);

      await Promise.all(
        batch.map(async (path) => {
          const url = new URL(path, window.location.origin);

          // Only same-origin offline package resources are accepted.
          if (
            url.origin !== window.location.origin ||
            !url.pathname.startsWith("/offline-tiles/")
          ) {
            throw new Error(`Invalid tile package path: ${path}`);
          }

          // Skip tiles already downloaded.
          if (!(await cache.match(url.href))) {
            await cache.add(url.href);
          }

          completed += 1;
        })
      );

      setStatus(
        `Offline tiles: ${completed} / ${tilePaths.length}`
      );
    }

    setStatus(`Prepared ${completed} offline map tiles.`);

  } catch (error) {
    console.error(error);
    setStatus(error.message ?? "Offline tile preparation failed.");
  } finally {
    prepareTilesButton.disabled = false;
  }
}

prepareTilesButton.addEventListener(
  "click",
  prepareOfflineTilePackage
);

const USE_LOCAL_TILE_PACKAGE = false;

const USE_LOCAL_TILE_PACKAGE = true;

async function refreshRecordList() {
  const records = await listFieldEntries();

  const pending = records.filter(
    (record) => record.syncStatus === "pending"
  );

  const needsReview = records.filter(
    (record) => record.syncStatus === "needs_review"
  );

  const synced = records.filter(
    (record) => record.syncStatus === "synced"
  );

  queueStatus.textContent =
    `${pending.length} pending · ` +
    `${synced.length} synced · ` +
    `${needsReview.length} need review`;

  // Rebuild the visible list without injecting survey notes as HTML.
  recordList.replaceChildren();

  for (const record of records.slice(0, 15)) {
    const item = document.createElement("li");
    const category = record.properties.category;
    const status = record.syncStatus;

    item.textContent =
      `${category} — ${status} — ${record.id.slice(0, 8)}`;

    recordList.appendChild(item);
  }
}

let foregroundSyncRunning = false;

async function scheduleSync(forceForeground = false) {
  const records = await listFieldEntries();

  const pending = records.filter(
    (record) =>
      record.syncStatus === "pending" ||
      !record.syncStatus
  );

  if (pending.length === 0) {
    setStatus("No records awaiting synchronization.");
    await refreshRecordList();
    return;
  }

  if (!navigator.onLine) {
    setStatus("Offline: observations remain stored locally.");
    return;
  }

  // Avoid overlapping foreground attempts in this page.
  if (foregroundSyncRunning) {
    return;
  }

  try {
    // Background Sync is an enhancement, not a universal guarantee.
    if (!forceForeground && "serviceWorker" in navigator) {
      const registration = await navigator.serviceWorker.ready;

      if (registration.sync?.register) {
        await registration.sync.register("sync-observations");
        setStatus("Synchronization queued for the background.");
        return;
      }
    }
  } catch (error) {
    console.warn("Background Sync unavailable:", error);
  }

  // Fallback for browsers without Background Sync or when the user
  // explicitly requests immediate synchronization.
  foregroundSyncRunning = true;

  try {
    const report = await syncPendingEntries();

    setStatus(
      `Synchronization complete: ${report.sent} records submitted.`
    );
  } catch (error) {
    setStatus(
      `Synchronization incomplete. Records remain queued: ${error.message}`
    );
  } finally {
    foregroundSyncRunning = false;
    await refreshRecordList();
  }
}

// Manual retry
syncNowButton.addEventListener("click", () => {
  void scheduleSync(true);
});

// Network changes: use them as hints to retry.
window.addEventListener("online", () => {
  void scheduleSync();
});

window.addEventListener("offline", () => {
  setStatus("Offline: local data capture is still available.");
});

// Retry when the user returns to the application.
document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible") {
    void scheduleSync(true);
  }
});

// Register the custom PWA worker in production.
if ("serviceWorker" in navigator && import.meta.env.PROD) {
  window.addEventListener("load", async () => {
    try {
      await navigator.serviceWorker.register("/sw.js");
      setStatus("Application ready.");
    } catch (error) {
      console.error("Service Worker registration failed:", error);
      setStatus("Offline application caching could not be enabled.");
    }
  });
}

// Load the local queue on startup.
refreshRecordList().catch(console.error);

// Attempt recovery when the application starts.
window.addEventListener("load", () => {
  void scheduleSync();
});

CREATE EXTENSION IF NOT EXISTS postgis;

CREATE TABLE field_observations (
    id UUID PRIMARY KEY,

    category TEXT NOT NULL,
    notes TEXT,

    captured_at TIMESTAMPTZ NOT NULL,
    accuracy_m DOUBLE PRECISION,

    geom geometry(Point, 4326) NOT NULL,

    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Spatial index for future mapping and spatial queries.
CREATE INDEX field_observations_geom_gix
    ON field_observations
    USING GIST (geom);

npm install express pg

import express from "express";
import pg from "pg";

const app = express();

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL
});

app.use(express.json({ limit: "1mb" }));

// Add real authentication middleware before exposing this endpoint.
// For example: app.post("/api/observations", requireAuth, handler);
app.post("/api/observations", async (req, res, next) => {
  try {
    const feature = req.body;

    // Validate the basic GeoJSON and the expected point geometry.
    if (
      feature?.type !== "Feature" ||
      feature?.geometry?.type !== "Point" ||
      !Array.isArray(feature.geometry.coordinates)
    ) {
      return res.status(422).json({
        error: "A GeoJSON Point feature is required."
      });
    }

    const [longitude, latitude] = feature.geometry.coordinates;
    const properties = feature.properties ?? {};

    if (
      !Number.isFinite(longitude) ||
      !Number.isFinite(latitude) ||
      longitude < -180 ||
      longitude > 180 ||
      latitude < -90 ||
      latitude > 90
    ) {
      return res.status(422).json({
        error: "Invalid longitude or latitude."
      });
    }

    if (
      typeof feature.id !== "string" ||
      !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(feature.id)
    ) {
      return res.status(422).json({
        error: "A valid UUID is required."
      });
    }

    const category = String(properties.category ?? "").trim();
    const notes = String(properties.notes ?? "");
    const capturedAt = properties.captured_at;
    const accuracy = properties.accuracy_m;

    const parsedDate = new Date(capturedAt);

    if (!category || Number.isNaN(parsedDate.getTime())) {
      return res.status(422).json({
        error: "Category and a valid capture timestamp are required."
      });
    }

    // Check the declared idempotency key against the body ID.
    const idempotencyKey = req.get("Idempotency-Key");

    if (idempotencyKey && idempotencyKey !== feature.id) {
      return res.status(422).json({
        error: "Idempotency-Key does not match the observation ID."
      });
    }

    // Parameterized SQL prevents the values from being interpreted as SQL.
    await pool.query(
      `
      INSERT INTO field_observations (
        id,
        category,
        notes,
        captured_at,
        accuracy_m,
        geom
      )
      VALUES (
        $1,
        $2,
        $3,
        $4,
        $5,
        ST_SetSRID(ST_MakePoint($6, $7), 4326)
      )
      ON CONFLICT (id) DO NOTHING
      `,
      [
        feature.id,
        category,
        notes,
        parsedDate.toISOString(),
        Number.isFinite(accuracy) ? accuracy : null,
        longitude,
        latitude
      ]
    );

    // Repeated submissions with the same UUID do not create a duplicate.
    return res.status(200).json({
      id: feature.id,
      accepted: true
    });

  } catch (error) {
    next(error);
  }
});

app.listen(3000, () => {
  console.log("Field API listening on port 3000");
});

npm run build

npm run preview

async function requestPersistentStorage() {
  if (!navigator.storage?.persist) {
    return false;
  }

  return navigator.storage.persist();
}