Skip to main content

Security & Offline Architecture

Overview​

Cyzag Blueprint is designed with security and offline-first operation as core principles. Industrial environments require apps that work reliably without connectivity, while also protecting sensitive operational data at rest and in transit.

Security First​

Encryption at Rest​

All data stored locally on mobile devices is encrypted at rest. This ensures that if a device is lost or stolen, the asset data, readings, observations, and photos remain protected. The encryption approach varies by platform:

  • iOS: Uses iOS Data Protection APIs and Keychain for sensitive credentials
  • Android: Uses Android Keystore and encrypted shared preferences/database
  • Web: Session tokens stored in secure browser storage with appropriate flags

Secure Transport​

All communication between mobile clients and the backend API uses HTTPS with TLS 1.2 or higher. API authentication tokens are short-lived and can be refreshed, reducing the risk of token compromise.

Scoped Access by Environment​

Users authenticate once and receive access tokens scoped to specific environments (e.g., "Plant A", "Plant B"). This ensures operators and supervisors only see data relevant to their assigned facilities.

Offline-First Architecture​

Why Offline-First?​

Industrial environments often have unreliable connectivity in parts of the plant. Operators need to complete rounds, capture readings, and record observations without interruption — even if they walk through areas with no Wi-Fi or cellular coverage.

How It Works​

Local Data Store: Mobile apps maintain a local database (SQLite on Android, Core Data or Realm on iOS) that stores:

  • Asset definitions and asset types
  • Functional locations hierarchy
  • Round templates and checkpoints
  • Operator's assigned rounds
  • Captured readings, observations, and photos (queued for sync)

Read-Heavy Sync: Before going offline, the app syncs down the latest asset data, round templates, and reference data. This ensures operators have everything they need even if they stay offline for an entire shift.

Write Queuing: As operators capture readings and complete checkpoints, changes are written to the local database and added to a sync queue. When connectivity returns, the app pushes queued changes to the server in order.

Conflict Resolution: If two operators edit the same data offline, the last-write-wins strategy is used for most fields. Critical conflicts (e.g., concurrent edits to the same round) are flagged for manual resolution.

Background Sync: Mobile apps monitor network availability and automatically sync in the background when connectivity is detected. Operators don't need to manually trigger sync.

Data Flow​

Initial Sync (Offline Prep)​

  1. Operator logs in with credentials (online)
  2. App receives authentication token
  3. App downloads assigned rounds, asset data, and reference data
  4. Local database is populated and encrypted
  5. Operator can now work offline

During a Round (Offline)​

  1. Operator opens a round template
  2. App loads checkpoints from local database
  3. Operator walks to each checkpoint and captures readings
  4. Readings are written to local database and added to sync queue
  5. App shows visual feedback that data is saved locally (pending sync)

Background Sync (When Connectivity Returns)​

  1. App detects network availability
  2. Sync engine processes the queue: uploads readings, observations, photos
  3. Server responds with acknowledgment and any updated data
  4. Local database is updated with server timestamps and IDs
  5. Operator sees confirmation that data is now synced

Viewing Synced Data (Online or Offline)​

  1. Supervisors and engineers can view completed rounds and readings on the web app
  2. Historical trends and last known values are available immediately (server-side)
  3. Mobile apps can also view synced data from other operators after their next sync

Technical Details​

Authentication Flow​

  • User logs in with username/password → receives JWT access token + refresh token
  • Access token is short-lived (15 minutes)
  • Refresh token is used to obtain new access tokens without re-login
  • Tokens are stored securely (Keychain on iOS, Keystore on Android)

API Communication​

  • All API calls use HTTPS
  • Access token is sent in Authorization: Bearer <token> header
  • If token expires during offline period, refresh happens automatically when connectivity returns

Local Database Schema​

  • Mirrors server-side entities (Assets, AssetTypes, AssetAttributes, Rounds, Checkpoints, Readings)
  • Includes sync metadata (last sync time, pending changes flag, server ID vs. local ID)
  • Encrypted at rest using platform-native encryption APIs

Sync Strategy​

  • Pull First: Download latest data from server before pushing local changes
  • Push Changes: Upload queued readings, observations, and round completions
  • Resolve Conflicts: Server validates and merges changes, returns updated timestamps
  • Update Local State: Mark queued items as synced, update local IDs with server IDs

Security Posture by Phase​

Phase 1​

  • Encryption at rest for mobile data
  • HTTPS for all API calls
  • Token-based authentication with refresh
  • Scoped access by environment

Phase 2 (Planned)​

  • Role-based access control (RBAC) for triage and alert management
  • Audit logs for who acknowledged/escalated observations
  • Enhanced token scoping by user role

Phase 3 (Planned)​

  • Work order assignment with role-based permissions
  • Integration authentication for CMMS/ERP systems
  • Detailed audit trail from round to work order completion

See Also: