BAB 5: AUTOMATED CIVIC NOTIFICATION GATEWAY (ORKESTRASI API PIHAK KETIGA)

Layer Automated Civic Notification Gateway pada Gandiwa Stack merupakan spesifikasi komponen subsistem backend yang bertugas mengatur, menjadwalkan, dan mengeksekusi pengiriman pesan asinkronus ke jaringan seluler melalui integrasi API (Application Programming Interface) pihak ketiga secara otomatis. Pada infrastruktur komputasi tepi (Edge Runtime) seperti Cloudflare Workers, interaksi keluar yang tidak terkontrol menuju gateway pihak ketiga dapat memicu degradasi performa dan eskalasi beban komputasi akibat lonjakan eksekusi kueri yang tidak terkontrol, serta berpotensi melanggar etika kenyamanan sosial pengguna akhir jika data disinkronkan pada waktu yang tidak tepat. Subsistem ini mengunci efisiensi dan keamanan transmisi tersebut menggunakan dua pilar utama: algoritma proteksi latensi waktu luring (stale time verification) dan isolasi pencatatan log transaksional kondisional.

5.1 Algoritma Proteksi Latensi Luring (Anti Late-Night Spam)

Ketika sistem beroperasi dalam arsitektur Hybrid Local-First, pemrosesan data mutasi dan log aktivitas diizinkan berjalan sepenuhnya secara luring di perangkat pengguna. Namun, ketika konektivitas internet pulih dan sinkronisasi massal dipicu di latar belakang, seluruh tumpukan data lama akan dialirkan menuju server komputasi tepi secara serentak. Jika server langsung menelan dan mengeksekusi perintah pengiriman pesan tanpa memfilter riwayat waktu pembuatan data asli, pengguna akhir (seperti warga atau wali murid) akan menerima lonjakan pesan otomatis di larut malam yang mengganggu kenyamanan sosial. Gandiwa Stack memitigasi anomali ini melalui fungsi validasi logika penanda kedalwarsa (isStale).

Perhitungan Parameter Durasi Penundaan (Delay Timestamp Check): Saat server Edge menerima muatan data sinkronisasi, sistem membaca parameter waktu pengambilan data asli di sisi klien (capturedAt) dan membandingkannya secara matematis dengan waktu internal server saat ini. Evaluasi pengiriman pesan otomatis dikontrol oleh Temporal Expiry Interceptor Gateway. Subsistem melakukan kalkulasi delta waktu linier antara pembuatan enkripsi lokal dengan runtime server. Jika ambang batas kronologis terlampaui, atau jam astronomis peladen mendeteksi transisi waktu operasional harian wilayah target, status pipa pengiriman langsung ditandai dengan flag interseptor stale, memblokir komunikasi keluar secara permanen di level runtime.
Interseptor Batas Operasional Jam Server (Server-Side Operational Hours Gate): Selain menghitung durasi penundaan, algoritma secara aktif memeriksa penanda waktu jam lokal wilayah target. Jika waktu server saat itu telah melewati pukul 15:00 sore, sistem akan memaksa variabel isStale menjadi true, terlepas dari seberapa cepat data tersebut berhasil dikirim dari klien ke server.
Terminasi Eksekusi API Gateway Ketat: Begitu kondisi isStale == true terpenuhi, server Edge langsung memotong jalur eksekusi kueri keluar dan membatalkan pengiriman payload pesan menuju API gateway eksternal (seperti API). Langkah terminasi ini menjaga integritas rate limit gateway API eksternal dari saturasi tidak terkontrol, mencegah blokir nomor akibat indikasi aktivitas spamming, dan menjaga privasi waktu istirahat pengguna akhir tanpa menghentikan rekapitulasi data internal sistem.

5.2 Pencatatan Log Transaksional Kondisional (Conditional Upsert Pipeline)

Meskipun pengiriman notifikasi ke perangkat luar dibatalkan oleh algoritma pembatasan waktu, integritas data master transaksional dalam basis data PostgreSQL tidak boleh terganggu. Automated Civic Notification Gateway memisahkan alur penulisan database transaksional inti dengan pencatatan log komunikasi melalui mekanisme pipa data kondisional.

Eksekusi Atomik Data Master via Drizzle ORM: Seluruh berkas aktivitas dan log logis yang dikirim dari klien tetap diproses menggunakan kueri penggabungan/pembaruan (upsert) secara aman ke dalam tabel basis data utama (seperti attendance_sessions dan attendance_logs). Drizzle ORM menjamin proses penulisan ini berjalan transaksional dan terisolasi penuh di bawah proteksi Row Level Security (RLS) PostgreSQL.
Isolasi Log Komunikasi Terpisah: Untuk melacak riwayat pengiriman pesan tanpa membebani tabel bisnis utama, status pengantaran diparkir ke dalam tabel log terisolasi bernama attendance_notifications. Jika status isStale bernilai false, sistem mengirimkan data ke API, menerima respons sukses, lalu mencatat status sebagai dispatched. Namun, jika isStale bernilai true, sistem melewati pemanggilan API eksternal dan langsung menulis status sebagai bypassed_stale di pangkalan data.
Optimalisasi Bandwidth & Memori Edge: Pemisahan pipa data ini memampukan Cloudflare Workers untuk mengembalikan respons HTTP berupa status sukses beserta jumlah pesan yang berhasil dikirim (waSentCount) dan flag indikator penundaan (isStale) kembali ke dasbor pengguna dalam hitungan milidetik. Struktur asinkronus ini membebaskan thread komputasi dari waktu tunggu respons eksternal API yang lambat, menjaga performa server tetap berada di level tertinggi.

FAQ BAB 5: AUTOMATED CIVIC NOTIFICATION GATEWAY

Q: Mengapa sistem membatalkan pengiriman notifikasi WhatsApp jika data absensi diinput lebih dari 60 menit yang lalu? A: Gandiwa Stack mengimplementasikan arsitektur Local-First di mana guru dapat mencatat absensi secara luring. Ketika koneksi internet pulih, seluruh tumpukan data luring disinkronkan ke server secara bersamaan. Tanpa filter temporal, server akan mengeksekusi perintah pengiriman pesan untuk data yang mungkin sudah berusia berjam-jam, mengakibatkan wali murid menerima puluhan notifikasi sekaligus di larut malam. Parameter capturedAt membawa cap waktu asli pencatatan data, yang dibandingkan secara matematis dengan waktu server untuk menghitung delta dan menentukan status isStale.

Q: Apakah data absensi tetap tersimpan di database meskipun notifikasi WhatsApp dibatalkan? A: Ya, secara mutlak. Sistem memisahkan dua alur data secara independen: alur penulisan data transaksional ke tabel attendance_sessions dan attendance_logs selalu dieksekusi menggunakan kueri upsert Drizzle ORM tanpa syarat. Pembatalan notifikasi hanya memengaruhi alur pemanggilan API. Status pembatalan dicatat sebagai bypassed_stale di tabel attendance_notifications untuk keperluan audit, memastikan integritas rekap akademik tidak pernah terganggu oleh logika pembatasan waktu.

Q: Apa yang dimaksud dengan Conditional Upsert Pipeline dan bagaimana ia menjaga konsistensi data? A: Conditional Upsert Pipeline adalah pola pemrosesan data yang memisahkan operasi penulisan database inti dari operasi komunikasi eksternal berdasarkan hasil evaluasi kondisi runtime. Operasi upsert (insert or update) ke tabel data master selalu dieksekusi terlebih dahulu secara transaksional dan terisolasi di bawah proteksi RLS PostgreSQL. Setelah itu, sistem mengevaluasi kondisi isStale untuk menentukan apakah pipeline komunikasi eksternal perlu diaktifkan atau dilewati , menjamin bahwa kegagalan atau pembatalan komunikasi tidak pernah merusak integritas data internal.

Rujukan Arsitektur & Navigasi

Sinkronisasi Notifikasi Luring: Pipa sinkronisasi notifikasi luring ini bergantung penuh pada toleransi kegagalan lokal yang dibahas pada Performance & Local-First Engineering di Bab 3.
Pemetaan Data Relasional: Skema penulisan log transaksional condisional menggunakan jembatan relasional Drizzle ORM yang dibahas pada Bab 1.4 (Type-Safe Relational Mapping).