Gateway notifikasi: mengubah alarm Kafka menjadi pesan WhatsApp dan Telegram

01Masalah

• Alarm sudah sampai ke Kafka, tetapi orang yang harus menindaklanjutinya tidak membaca topik Kafka. Mereka membaca WhatsApp dan Telegram.
• Langganan topik mentah juga tidak punya konsep siapa yang harus diberi tahu untuk kelas alarm tertentu, atau lewat kanal mana.

02Batasan

• Target pengirimannya layanan pihak ketiga, jadi gateway harus tahan terhadap kanal yang mati atau belum terautentikasi.
• Penerima dan preferensi kanal berubah terpisah dari stream alarm, jadi tempatnya di database, bukan di file konfigurasi.
• Lalu lintas alarm bersifat burst, dan panggilan notifikasi lambat dibanding konsumsi pesan, sehingga consumer tidak boleh tersendat di belakangnya.
• Dashboard dan consumer dua-duanya butuh sinyal kesehatan, karena consumer yang mati diam terlihat sama dengan plant yang sedang sepi.

03Arsitektur dan aliran data

• Inbound: proses worker mengonsumsi pesan alarm dari topik alarm dalam consumer group-nya sendiri.
• Routing: penerima dipilih berdasarkan level prioritas dan kanal yang diaktifkan tiap pengguna, dibaca dari PostgreSQL.
• Pengiriman: Telegram lewat integrasi bot, dan WhatsApp lewat instance WAHA HTTP API, bukan API Business resmi.
• State: PostgreSQL menyimpan penerima, registrasi chat Telegram, dan preferensi, dengan tabel yang dibuat saat startup oleh database manager.
• Control plane: backend FastAPI menyediakan endpoint ber-auth JWT, dan dashboard React mengelola penerima serta preferensi.
• Audit: setiap hasil pengiriman dipublikasikan ke topik notification logs, sehingga riwayatnya tersedia untuk dashboard dari substrat yang sama dengan alarmnya.
• Supervisi: thread watchdog memeriksa kesehatan consumer dan memaksa proses keluar bila thread consumer mati, sehingga container restart alih-alih menganggur.

04Keputusan engineering

• Event loop asyncio berjalan di thread latar khusus, dan bot Telegram tetap di thread utama karena membutuhkan signal handler.
• Watchdog sengaja memilih keluar paksa daripada pemulihan di tempat, menukar restart container dengan kepastian bahwa consumer yang macet tidak bisa diam-diam lolos sebagai sehat.
• Integrasi kanal berada di balik package notifier, sehingga menambah kanal tidak menyentuh consumer.
• Riwayat notifikasi dipublikasikan kembali ke Kafka alih-alih hanya ditulis ke database, menjaga satu transport untuk ingestion sekaligus observability.
• Autentikasi Kafka bersifat opsional dan baru memakai SASL PLAIN bila kredensial tersedia, sehingga pengembangan lokal tidak butuh auth broker.
• Jalur modem GSM dipisahkan dari notifier jaringan, karena mode kegagalannya bersifat fisik, bukan level protokol.

05Pengujian dan verifikasi

• Kesenjangan yang diakui: sisi Python tidak punya test suite. Satu-satunya artefak test di repositori adalah file test bawaan Create React App.
• Tidak ada workflow CI, jadi tidak ada yang berjalan otomatis saat push.
• Yang bisa diverifikasi dari repositori adalah struktur dan niatnya: penyusunan consumer, routing berdasarkan prioritas, adapter kanal, database manager, dan topologi Docker Compose.

06Yang terbukti saat ini

• Gateway multi-kanal yang berfungsi, dengan manajemen penerima, preferensi kanal per pengguna, dan jejak audit pengiriman.
• Terkontainerisasi end to end, mencakup backend, dashboard, worker, dan layanan WhatsApp.
• Yang tidak diklaim: tidak ada angka throughput, keandalan, atau uptime. README memakai bahasa pemasaran yang tidak diukur oleh apa pun di repositori, jadi frasa itu tidak diulang di sini.

Source dan referensi