link-stack/apps/bridge-worker

Bridge Worker

Background job processor for handling asynchronous tasks in the CDR Link communication bridge system.

Overview

Bridge Worker uses Graphile Worker to process queued jobs for message handling, media conversion, webhook notifications, and scheduled tasks. It manages the flow of messages between various communication channels (Signal, WhatsApp, Facebook, Voice) and the Zammad ticketing system.

Features

• Message Processing: Handle incoming/outgoing messages for all supported channels
• Media Conversion: Convert audio/video files between formats
• Webhook Notifications: Notify external systems of events
• Scheduled Tasks: Cron-based job scheduling
• Job Queue Management: Reliable job processing with retries
• Multi-Channel Support: Signal, WhatsApp, Facebook, Voice (Twilio)

Development

Prerequisites

• Node.js >= 20
• npm >= 10
• PostgreSQL database
• Redis (for caching)
• FFmpeg (for media conversion)

Setup

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run development server with auto-reload
npm run dev

# Start production worker
npm run start

Environment Variables

Required environment variables:

• DATABASE_URL - PostgreSQL connection string
• GRAPHILE_WORKER_CONCURRENCY - Number of concurrent jobs (default: 10)
• GRAPHILE_WORKER_POLL_INTERVAL - Job poll interval in ms (default: 1000)
• ZAMMAD_URL - Zammad instance URL
• ZAMMAD_API_TOKEN - Zammad API token
• TWILIO_ACCOUNT_SID - Twilio account SID
• TWILIO_AUTH_TOKEN - Twilio auth token
• SIGNAL_CLI_URL - Signal CLI REST API URL
• WHATSAPP_SERVICE_URL - WhatsApp bridge service URL
• FACEBOOK_APP_SECRET - Facebook app secret
• FACEBOOK_PAGE_ACCESS_TOKEN - Facebook page token

Available Scripts

• npm run build - Compile TypeScript
• npm run dev - Development mode with watch
• npm run start - Start production worker

Task Types

Signal Tasks

• receive-signal-message - Process incoming Signal messages
• send-signal-message - Send outgoing Signal messages
• fetch-signal-messages - Fetch messages from Signal CLI

WhatsApp Tasks

• receive-whatsapp-message - Process incoming WhatsApp messages
• send-whatsapp-message - Send outgoing WhatsApp messages

Facebook Tasks

• receive-facebook-message - Process incoming Facebook messages
• send-facebook-message - Send outgoing Facebook messages

Voice Tasks

• receive-voice-message - Process incoming voice calls/messages
• send-voice-message - Send voice messages via Twilio
• twilio-recording - Handle Twilio call recordings
• voice-line-audio-update - Update voice line audio
• voice-line-delete - Delete voice line
• voice-line-provider-update - Update voice provider settings

Common Tasks

• notify-webhooks - Send webhook notifications

Leafcutter Tasks

• import-leafcutter - Import data to Leafcutter
• import-label-studio - Import Label Studio annotations

Architecture

Job Processing

Jobs are queued in PostgreSQL using Graphile Worker:

await addJob('send-signal-message', {
  to: '+1234567890',
  message: 'Hello world'
})

Cron Schedule

Scheduled tasks are configured in crontab:

• Periodic message fetching
• Cleanup tasks
• Health checks

Error Handling

• Automatic retries with exponential backoff
• Dead letter queue for failed jobs
• Comprehensive logging with winston

Media Handling

Supports conversion between formats:

• Audio: MP3, OGG, WAV, M4A
• Uses fluent-ffmpeg for processing
• Automatic format detection

Integration Points

• Zammad: Creates/updates tickets via API
• Signal CLI: REST API for Signal messaging
• WhatsApp Bridge: HTTP API for WhatsApp
• Twilio: Voice and SMS capabilities
• Facebook: Graph API for Messenger

Docker Support

# Build image
docker build -t link-stack/bridge-worker .

# Run with docker-compose
docker-compose -f docker/compose/bridge.yml up

The worker includes cron support via built-in crontab.