Device Mapper

The Device Mapper is responsible for:

  • Fetching device (client) information for each contact

  • Filtering devices based on optional criteria

  • Selecting the proper content based on the device’s language

  • Assembling the final message for delivery, inbox, or embedded messaging

  • Reporting contacts without devices (or filtered contacts) as "not sent"

Subscription format: sending-<batch|tx>-devicemapper-<dg>-sub

Device Fetch Strategies

The Device Mapper supports three device fetch strategies, controlled by the per-customer flipper USE_POSTGRES_DEVICE_MAPPER:

Strategy Description Selection

PostgreSQL with DynamoDB Fallback

Primary fetch from PostgreSQL. For contacts with zero PostgreSQL devices, falls back to DynamoDB. Fallback can be disabled per-customer via CLIENT_FETCHER_FALLBACK_DISABLED_PER_CUSTOMER flipper.

When USE_POSTGRES_DEVICE_MAPPER is enabled for the customer (default path for migrated customers)

DynamoDB (legacy)

Fetches from DynamoDB via DeviceManager.findByContactKey(). Each contact queried individually.

When USE_POSTGRES_DEVICE_MAPPER is not enabled

PostgreSQL only

Bulk query from PostgreSQL via DeviceRepository.findByContactKeys(). Higher concurrency: batch=3, message=10.

When fallback is explicitly disabled via CLIENT_FETCHER_FALLBACK_ENABLED=false

Output Topics

After assembling messages, the Device Mapper publishes to provider-specific delivery topics:

Topic Pattern Example

sending-<tx|batch>-push-apple-<dg>

sending-tx-push-apple-dg00

sending-<tx|batch>-push-fcm-<dg>

sending-batch-push-fcm-dg01

sending-<tx|batch>-push-huawei-<dg>

sending-tx-push-huawei-dg00

sending-<tx|batch>-webpush-vapid-<dg>

sending-tx-webpush-vapid-dg00

sending-<tx|batch>-inbox-<dg>

sending-tx-inbox-dg00

sending-<tx|batch>-em-<dg>

sending-batch-em-dg01

Not-sent events are published to the data platform via eventPublisher.publishNotSentEvent.

Dependencies

  • Pub/Sub:

    • Receives personalized messages from device mapper subscriptions

    • Publishes assembled messages to provider-specific delivery topics

    • Reports "not sent" to Data Platform

    • Fatal errors go to sending-mg-errors

  • PostgreSQL: Primary device storage (tenant schemas tenant_<customerId>)

  • DynamoDB: Legacy device storage (being phased out)

  • Kibana: Logging

Device Mapper Components & Dependencies

Error Handling

  • Transient errors: Messages (up to whole batches) are NACKed, causing redelivery at a later time.

  • Fatal errors: Published to sending-mg-errors.

See Error Handling for the full retry policy.

Code Location

src/components/device-mapper/