offline-first architecture

What offline-first means

Most platforms are built for the best case: when the network fails, they fail with it. wede is built for the worst case. Every operation you send to wede has a defined path whether the network is up, degraded or down, and no operation is stored twice. Offline-first is part of the core that every integration uses, together with events, delivery through your channel cascade and webhooks. Teams, dispatch and missions are an optional module for operational verticals that send people to the field (emergency services, healthcare field teams, field services and delivery); the rest of this page applies to every integration, with or without it. In practice, offline-first in wede rests on four principles:

Every operation is accepted once. Each event carries an idempotency_key. Sending it again, online or in a later batch, never creates a second event.
Operations captured without connectivity are not lost. Your apps capture operations locally with an integrity checksum and send them in a batch when connectivity returns. See Sync.
Delivery follows the state of the zone. When a zone is online, events travel over REST. When it is not, wede follows the continuity mode of your tenant. See Connectivity.
Nothing is dropped silently. If every channel in the cascade fails, the event is queued for store-and-forward instead of being marked as failed.

Delivery channels

These are the channels wede uses, with the value the API returns in channel_used and in delivery webhooks.

Channel	API value	Used for
REST (internet)	`rest_full`	Events received over the internet in an `online` zone, and `low` and `normal` events in a `degraded` zone
REST, compressed	`rest_compressed`	`high` and `critical` events received while the zone is `degraded`
SMS	`sms`	Fallback when internet is unavailable
Voice	`voice`	Fallback by voice call
Satellite	`satellite`	Fallback where there is no terrestrial network
LoRa	`lora`	Long-range radio fallback for field devices
Edge	`edge`	Local edge delivery
Store-and-forward	`queued_offline`	The event is queued (`pending`) and becomes `completed` when the queued operation is reconciled

Your API call is the same whatever channel delivers the event. The channel wede used is recorded on the event (channel_used) and sent in the event.delivered webhook. Delivery through any channel, including REST, makes the event completed and clears its stored payload.

Continuity modes

Each tenant runs in one of two continuity modes. The mode comes from your plan. Automatic cascade. Events for a zone that is online or degraded travel over REST. For a zone in any other state, wede tries the fallback channels of your tenant in the order agreed for your tenant, retrying each channel before moving to the next. If the whole cascade fails, the event is queued for store-and-forward. Store-and-forward. Events are queued (channel_used: "queued_offline") and completed once the queued operation is reconciled. No intermediate channels are attempted. In both modes, each queued operation has a unique identity and is accepted once. See Connectivity for the zone states that drive these decisions.

Device registration and offline dispatch queue

This section applies to the optional teams and dispatch module. Besides event sync, wede keeps a dispatch queue per device. An app can create dispatch requests without connectivity, each with a sequence number, and send them when it reconnects. wede then scores the available teams and dispatches the best one, exactly as it does for an online dispatch (see Score engine).

The device endpoints require a user session (Authorization: Bearer <token>). Registering and syncing a device needs a role with SDK access (company_admin, company_tech, country_admin or field_operator). Reading a device queue needs dispatch visibility (company_admin, operational_supervisor or corporate_client). An API key receives 403 forbidden.

Register a device

POST /v1/devices/register

{
  "device_id": "3f1c9a52-7d7e-4a51-9f0e-2b8c6e1d4a10",
  "platform": "android",
  "app_version": "2.1.0"
}

Field	Required	Description
`device_id`	Yes	Identifier generated by your app, 1 to 200 characters. Keep it stable for the life of the installation
`platform`	Yes	`ios`, `android`, `web` or `other`
`app_version`	No	Up to 50 characters

Response 201:

{ "device_id": "3f1c9a52-7d7e-4a51-9f0e-2b8c6e1d4a10", "registered": true }

Registering the same device again is safe: it updates the app version and the last time the device was seen. An invalid body returns 400 validation_error.

Sync the device queue

POST /v1/devices/sync

{
  "device_id": "3f1c9a52-7d7e-4a51-9f0e-2b8c6e1d4a10",
  "last_received_seq": 0,
  "dispatches": [
    {
      "sequence_number": 1,
      "action_id": "8a6e0f3c-2b1d-4c9e-9a7f-5d3b1e2c4f60",
      "event_lat": 38.7169,
      "event_lng": -9.1395,
      "vertical": "healthcare",
      "priority": "high",
      "created_offline_at": "2026-09-20T17:00:00Z"
    }
  ]
}

Field	Required	Description
`device_id`	Yes	A device registered for your tenant, else `404 device_not_found`
`last_received_seq`	Yes	Integer, 0 or more
`dispatches`	Yes	Up to 500 entries (may be empty)
`dispatches[].sequence_number`	Yes	Integer from 1, increasing by one per entry on this device
`dispatches[].action_id`	No	ID of an action in your catalog. Needed for the entry to be dispatched
`dispatches[].event_lat`, `event_lng`	No	Location of the operation. Needed for the entry to be dispatched
`dispatches[].vertical`, `priority`, `payload`	No	Stored with the entry
`dispatches[].created_offline_at`	Yes	ISO 8601 time the entry was created on the device

Response 200:

{
  "accepted": [1],
  "duplicates": [],
  "failed": [],
  "server_seq": 1,
  "device_last_received_seq": 0,
  "synced_at": "2026-09-20T18:00:00.000Z",
  "integrity_gap_detected": false,
  "integrity_incident_id": null
}

How wede handles the queue:

Once per sequence number. Each (device_id, sequence_number) is stored once. Sending it again returns it in duplicates. failed lists sequence numbers that could not be stored.
Immediate processing. Every pending entry of the device is processed during the call. An entry with an action_id and coordinates is scored and dispatched, creating a mission. An entry without them is marked failed for review and is never retried automatically.
Sequence integrity. Sequence numbers must start at 1 and have no gaps. If a number is missing, wede blocks the pending entries after the gap (never the whole device), records a security incident, alerts your tenant administrators and returns integrity_gap_detected: true with the incident ID.
Webhook. Each sync sends a device.synced webhook with { device_id, accepted, duplicates } (counts).

Read a device queue

GET /v1/devices/:device_id/queue?status=pending Returns up to 100 entries of the device, in sequence order, as { data, count }. status is one of pending (default), processing, processed, failed or blocked_integrity.

Security

All traffic is encrypted in transit over HTTPS.
Requests authenticate with an API key (server to server) or a user session token (apps and dashboard). What a session can do depends on the user’s role. See Authentication.
Operations are written to an audit trail with the user, time and IP address. Audit entries cannot be modified or deleted.
Integrity failures (a checksum that does not match, a gap in a device sequence) are recorded as security incidents that cannot be altered, and your tenant administrators are alerted.
After delivery is confirmed, wede clears the stored payload of the event and keeps only identifiers, type, channel and lifecycle.

See Security for details.

Compliance and data residency

wede is hosted in the European Union by default. Where local regulation requires in-country data residency, a dedicated regional instance is available by agreement. wede is designed to support organisations working under:

GDPR: data minimisation by design (payloads cleared after delivery, or when the event is closed for types that send a team; one-off recipients never kept with the event; retention periods per vertical; wede staff see only event categories, never your payloads or event types).
DORA: operational resilience and ICT incident traceability for financial entities in the EU.
ISO 27001: controls aligned with access management, audit trail and information security practices.
CBUAE: resilience expectations for financial institutions in the UAE.

Data and configuration are isolated per tenant.

Introduction

Core Concepts

Examples by Vertical

What offline-first means

Delivery channels

Continuity modes

Device registration and offline dispatch queue

Register a device

Sync the device queue

Read a device queue

Security

Compliance and data residency

​What offline-first means

​Delivery channels

​Continuity modes

​Device registration and offline dispatch queue

​Register a device

​Sync the device queue

​Read a device queue

​Security

​Compliance and data residency

What offline-first means

Delivery channels

Continuity modes

Device registration and offline dispatch queue

Register a device

Sync the device queue

Read a device queue

Security

Compliance and data residency