Skip to main content

Concepts and Architecture

This section explains the core concepts, architecture, and design principles of the MOSA Mobile SDK.

Core Concepts​

Docks​

MOSA docks are physical hardware units that provide secure bike locking and unlocking capabilities. Each dock:

  • Has a unique asset ID that identifies it
  • Contains an NFC tag for discovery and supports BLE communication with the MOSA SDK

Sessions​

A session represents a single bike/dock usage period. Sessions are automatically created and managed by the SDK.

  • CREATED: Session created, waiting for unlock key
  • ACTIVE: Session is active. For secure bike parking, this means the user has a bike parked. For bike sharing, this means the user has rented the bike and is actively using it
  • COMPLETED: Session completed successfully
  • CANCELLED: Session was cancelled

Session Properties:

  • id - Unique session identifier
  • userId - User who owns the session
  • areaId - Area where the session takes place
  • status - Current session status
  • startTime - When the session became active
  • endTime - When the session completed

Sessions are automatically created when requesting certain unlock key types (bikeLock, rentBikeUnlock, testLock). The SDK handles session management internally in tandem with the MOSA server.

Offline Store​

The SDK maintains a local offline store for:

  • Unlock Keys: Cached keys for reuse (valid until expiry)
  • Sessions: Current and recent sessions
  • Session Events: Queued events for sync when connectivity is restored

Events​

The SDK generates events throughout dock operations:

  • NFC Events: nfcScanCompleted
  • BLE Events: bleConnecting, bleConnected, bleDisconnected
  • Dock Events: dockUnlocked, dockChainRemoved, dockChainInserted, dockSecured
  • Key Events: requestKey, keySent
  • Error Events: error

See SDK Callbacks for complete event documentation.

Lifecycle & Threading​

App Lifecycle​

The SDK handles app lifecycle events:

  • Foreground: Full functionality available
  • Background: BLE operations continue via foreground service (Android) or background modes (iOS)
  • Terminated: Sessions and events are persisted for sync when app restarts

Reconnection​

The SDK automatically handles reconnection:

  • Network Loss: Queues events locally, syncs when connectivity is restored
  • Session Recovery: Can recover active sessions after app restart

Next Steps​

For platform-specific details, see the Platform Guides.