WhatsApp — SaaS Multi-Tenant & Polqo Migration Plan

Status: 🟡 W0.1 DONE (2026-06-16) — middleware tenant context shipped. W0.2-W0.5 pending. Owner: Backend Lead Prasyarat: ✅ Extraction Phase 0–4 DONE (lihat whatsapp-service-status.md) — service sudah standalone & hardened, tapi single-tenant. Dokumen terkait:

architecture.md — desain endpoint + persistence (canonical)
whatsapp-service-status.md — status per phase
template-catalog.md — katalog template + roadmap SaaS
../firebase/polqo-migration-plan.md — pola referensi (FCM sudah punya plan ini, WhatsApp meniru)
ADR 0009 (polqo repo) — project isolation Polqo vs Kesles
ADR 0005 (polqo repo) — fork-and-run-parallel extraction pattern

⚠️ Revisi 2026-06-16 — locked decisions

Setelah audit lapangan (codebase + memory + diskusi product), beberapa asumsi awal direvisi:

A. Schema sudah tenant-ready (audit 2026-06-16)

Berbeda dengan asumsi awal "grep tenant kosong":

✅ notification.whatsapp_messages, _send_attempts, _delivery_events, _provider_configs, _templates SEMUA sudah punya tenant_id (mig v1/002), default sentinel 00000000-0000-0000-0000-000000000001
✅ Index idx_whatsapp_messages_tenant_created sudah ada
Konsekuensi: W0 tidak butuh migration baru — cukup app-layer (handler context + store filter + insert path)

B. Dua sentinel tenant Kesles (bukan satu)

Bedakan Kesles Company vs Kesles Merchant App:

Tenant UUID	Nama	Scope	Billing
`00000000-0000-0000-0000-000000000001`	kesles-merchant-app	OTP user, transaction alert, payment receipt, staff invitation, semua built-in feature di app	Kesles bayar
`00000000-0000-0000-0000-000000000002`	kesles-company	Marketing outbound Kesles → calon merchant (sales blast, onboarding email)	Kesles bayar
`<uuid per merchant>`	merchant subscriber (FUTURE)	Custom send merchant → end-customer mereka (di luar fitur built-in)	Merchant bayar via topup

C. Model billing — quota + overflow (FUTURE, subscription belum ada)

Audit 2026-06-16 confirm: infrastruktur subscription/billing BELUM ADA di codebase:

❌ Tidak ada tabel merchant_subscriptions, subscription_plans, merchant_wallet, topup_balance
❌ Tidak ada UI subscribe / topup di dashboard
❌ Tidak ada produk berbayar "Kesles Merchant Pro" — masih konsep
✅ QRIS bank Kesles ada (untuk transaksi merchant ↔ end-customer di payment_service:8085), tapi belum ada flow QRIS internal untuk billing Kesles → merchant

Konsekuensi untuk WA plan:

Sampai produk subscription launch: SEMUA send WA dari merchant via Kesles platform → tagih ke Kesles. Tidak ada bonus quota tracking + topup merchant.
Model "quota + overflow" yang sebelumnya dibahas (bonus 10/bulan + topup) DEFER sampai infrastructure subscription ada.
Template merchant_subscription_expiry yang disebut di plan asli DICABUT dari scope W1-W6 — tidak ada subscription produk untuk diingatkan.
Plan terpisah subscription-product-plan.md akan dibuat untuk track infrastructure subscription (target: TBD).

D. WABA strategy — nomor Kesles existing

Pakai 1 nomor WhatsApp Business yang sudah verified Meta (existing Kesles). Multiple tenant share WABA yang sama.

Konsekuensi W0.4: webhook routing tidak bisa rely pada phone_number_id (semua tenant pakai phone_number_id sama). Routing alternatif: lookup provider_message_id di whatsapp_messages table → ambil tenant_id dari row source send.

E. Phase 4 template ordering — low-risk first → OTP last

Plan asli rekomendasi tetap valid. OTP migrasi ke Polqo paling akhir karena critical path (auth login). Detail rationale di §4 Phase W4.

F. Mobile app behavior — platform vs merchant outbound split

Sumber traffic	Tenant	Billing
Mobile user OTP, transaction alert, payment receipt	`kesles-merchant-app`	Kesles
Merchant dashboard OTP	`kesles-merchant-app`	Kesles
Staff invitation (built-in)	`kesles-merchant-app`	Kesles
Merchant broadcast ke list pelanggan (future fitur premium)	`<merchant-tenant-id>`	Merchant via topup (FUTURE — pending subscription product)

Sampai subscription produk ada: semua scenario billed to Kesles. Merchant-initiated broadcast belum perlu separate billing — Kesles absorb cost sampai produk launch.

0. Kenapa dokumen ini ada

FCM sudah punya polqo-migration-plan.md. WhatsApp belum. Satu-satunya plan WhatsApp yang ada (whatsapp-extraction-plan.md) sudah diarsipkan karena extraction selesai. Dokumen ini mengisi gap tersebut: bagaimana WhatsApp berpindah dari internal single-tenant tool menjadi notification-as-a-service multi-tenant di bawah platform Polqo.

Berbeda dari FCM (yang masalah utamanya cuma swap kredensial Firebase), WhatsApp punya dua pekerjaan terpisah yang harus dibedakan:

Multi-tenancy — backend & DB belum punya konsep tenant_id sama sekali.
Rombak UI — menu "WhatsApp API" sekarang adalah tester super-admin, bukan console merchant. UI ini harus dibangun ulang sebagai produk SaaS.

Urutan wajib: multi-tenancy backend dulu → UI SaaS → baru migrasi Polqo. Merombak UI sebelum ada tenant_id di backend = rework.

1. Kondisi Sekarang (per 2026-06-15)

Backend — matang tapi single-tenant

Komponen	Status	Catatan
`services/whatsapp_service`	🟢 LIVE PROD :8091	Phase 0–4 DONE, hardening P0–P3 + G2/G5 selesai
Multi-tenancy (`tenant_id`)	❌ TIDAK ADA	`grep tenant internal/` kosong — semua hardcoded Kesles
Tabel `notification.whatsapp_messages` (+`_send_attempts`,`_delivery_events`)	🟢 di `db_kesles_merchant_notification`	Tidak ada kolom `tenant_id`
Meta WABA / API key	🔒 Tunggal	Satu nomor, satu `WHATSAPP_API_KEY`, satu `WHATSAPP_ALLOWED_TEMPLATES`
Template	🔒 Hardcoded `merchant_*`	Diapprove untuk WABA Kesles, bukan per-tenant

8 endpoint live: /health, /ready, /internal/whatsapp/otp, /internal/whatsapp/messages, /internal/whatsapp/template, /internal/whatsapp/messages/{id}, GET|POST /webhooks/whatsapp/status. Tidak satupun tenant-aware.

UI — tester, bukan SaaS

Menu "WhatsApp API" (MerchantDashboardMenu.whatsappApi) di-gate MerchantDashboardPermission.devToolsAccess (super-admin only). Dua submenu:

Submenu	File	Apa adanya
WhatsApp Tester	`whatsapp_tester_panel.dart` (452 LOC)	Form kirim manual, menampilkan raw JSON body endpoint internal. Untuk debug developer.
Bulk Messaging	`whatsapp_bulk_messaging_panel.dart` (1514 LOC)	Blast `merchant_tester_reminder` ke daftar tester closed-testing (hardcoded).

Keduanya return _SuperAdminGateBanner() kalau role bukan superAdmin. Tidak ada konsep tenant, kuota, langganan, koneksi nomor self-service, atau log per-merchant.

2. Arsitektur Target

Saat ini (single-tenant)

merchant_core_api
    │  HTTP POST /internal/whatsapp/template  (X-Internal-API-Key)
    ▼
whatsapp-service (Kesles, :8091)
    │  Meta Cloud API (graph.facebook.com/v23.0)
    ▼
Meta WABA (Kesles)

Target akhir (multi-tenant + Polqo)

merchant_core_api / caller lain
    │  HTTP POST /internal/whatsapp/template  (X-Internal-API-Key + X-Tenant-ID)
    ▼
whatsapp-service (Kesles, :8091) ← jadi thin proxy saat USE_POLQO_WA=true
    │  HTTP POST /api/whatsapp/send?tenant_id=kesles  (X-Tenant-ID + X-Internal-API-Key)
    ▼
polqo-whatsapp-service (api.polqo.com)
    │  Meta Cloud API
    ▼
Meta WABA (per-tenant; Polqo yang kelola)

merchant_core_api tidak berubah — tetap memanggil whatsapp-service lokal, sekarang dengan header X-Tenant-ID. Persis pola FCM: service lokal berubah peran jadi proxy ke Polqo.

3. Feature Flag

Diset di whatsapp-service (bukan merchant_core_api), selaras pola USE_POLQO_FCM:

USE_POLQO_WA=false           # default — kirim langsung ke Meta WABA Kesles
USE_POLQO_WA=true            # proxy ke Polqo WhatsApp service
POLQO_WA_BASE_URL=https://api.polqo.com
POLQO_WA_TENANT_ID=kesles
POLQO_WA_API_KEY=<api-key-dari-polqo>
# Cutover bertahap per template (analog POLQO_FCM_EVENTS):
POLQO_WA_TEMPLATES=merchant_otp_code,merchant_payment_receipt

Template yang ada di POLQO_WA_TEMPLATES → kirim ke Polqo. Sisanya → Meta WABA Kesles. Cutover bertahap tanpa deploy ulang (cukup restart env).

4. Tahapan

Phase W0 — Multi-tenancy Backend (BLOCKER, kerjakan duluan)

Estimasi: 3–5 hari total. Schema sudah tenant-ready (audit 2026-06-16), W0 fokus app-layer:

W0.1 — Middleware `withTenantID` + context ✅ DONE 2026-06-16

✅ internal/app/tenant.go — sentinel constants (TenantKeslesMerchantApp = 0001, TenantKeslesCompany = 0002), header parse, UUID validation, ctx helper
✅ internal/app/tenant_test.go — 12 test pass (header kosong/valid/upper/invalid, sentinel fallback)
✅ Wiring di server.go — chain withInternalKey → withTenantID → idempotency → handler di 4 endpoint /internal/whatsapp/*
Behavior: zero impact (caller tanpa header → fallback ke TenantKeslesMerchantApp sentinel) — backward compatible 100%

Catatan: schema sudah punya tenant_id per audit (mig v1/002), jadi migration baru tidak diperlukan untuk add column.

W0.2 — Store: SELECT filter by tenant_id (pending)

Refactor internal/store/postgres.go: tambah tenantID string parameter ke semua method SELECT (GetMessageByID, ListMessages, GetTemplate, dll)
Append AND tenant_id = $X::uuid ke WHERE clause — index idx_whatsapp_messages_tenant_created siap dipakai
Update 4 handler — pass tenantIDFromCtx(r.Context()) ke store
Unit test: tenant A query tenant B's message → sql.ErrNoRows (isolation proof)

Estimasi: 1 hari.

W0.3 — Insert path: write tenant_id dari context (pending)

Tambah TenantID field ke struct Message, SendAttempt, DeliveryEvent
Insert query: include tenant_id column eksplisit (jangan rely DEFAULT supaya audit jelas)
Handler populate msg.TenantID = tenantIDFromCtx(r.Context()) sebelum store.Insert
Children rows (send_attempts, delivery_events) inherit tenant_id eksplisit dari parent message (consistency for audit)

Estimasi: 1 hari.

W0.4 — Webhook tenant routing (pending — strategy revised)

⚠️ Strategy berubah: karena multiple tenant share WABA Kesles existing (1 phone_number_id), tidak bisa route via phone_number_id.

Routing alternatif: lookup provider_message_id di webhook payload → query notification.whatsapp_messages.tenant_id row source → resolve tenant.

Update webhook_handlers.go: ambil provider_message_id dari payload Meta
Add store method ResolveTenantByProviderMessageID(ctx, provider_message_id) (string, error)
Inject ke context sebelum process delivery event
Fallback ke sentinel TenantKeslesMerchantApp kalau lookup miss (log warn — possibly orphan webhook)
Add http.MaxBytesReader ke webhook handler (sekalian close finding HIGH 6.1)

Estimasi: 1 hari.

W0.5 — Per-tenant config + 2 sentinel seed (pending)

⚠️ Scope revisi: untuk Phase W0, cukup 2 sentinel tenant Kesles. Per-merchant tenant DEFER ke W1+ (saat UI SaaS).

Insert seed row di notification.whatsapp_provider_configs untuk 2 sentinel (kesles-merchant-app + kesles-company) — share WABA Kesles existing, beda nama untuk identifikasi cost
Caller wiring update — semua existing call dari core_api (OTP, alert) update set header X-Tenant-ID: 00000000-0000-0000-0000-000000000001
Caller wiring dashboard_api marketing tester → X-Tenant-ID: 00000000-0000-0000-0000-000000000002
Resolve tenant config dari DB (bukan env global) — cache 5 menit Redis kalau available
Backward compat: tenant sentinel + DB row kosong → fallback env WHATSAPP_* existing
Tests: tenant isolation (tenant A config ≠ tenant B config, tenant A query bisa baca tenant A row tapi tidak tenant B)

Estimasi: 1-2 hari.

W0 — Phase gate (lulus ke W1)

✅ Build clean, tests pass (W0.1-W0.5)
✅ Seed 2 sentinel row di prod (kesles-merchant-app + kesles-company)
✅ Caller (core_api, dashboard_api) wiring kirim X-Tenant-ID eksplisit
✅ Soak 48 jam tanpa regression (Kesles single-tenant traffic existing tetap jalan)
✅ HIGH 6.1 finding closed (MaxBytesReader di webhook — fix saat sentuh W0.4)

Phase W1 — Rombak UI jadi SaaS Console

Estimasi: 5–8 hari (paralel sebagian dengan W0 setelah kontrak API tenant fix)

Lihat §6 untuk detail UI. Ringkas:

Lepas gate superAdmin, ganti ke role merchant per-tenant.
Halaman Connection/Onboarding — connect nomor WA / status verifikasi (belum ada).
Ubah Tester → Send/Template console ramah-merchant (form field bernama, bukan raw JSON body_params[]).
Usage view — pageview agregat per merchant per template per bulan. TANPA Billing: subscription produk + tagihan ke merchant DEFER sampai infrastructure subscription ada (lihat §⚠️ Revisi C). Template merchant_subscription_expiry di-draft TAPI dicabut dari scope W1-W6 karena tidak ada produk subscription untuk diingatkan.
Message log tenant-scoped (pakai /internal/whatsapp/messages/{id} + list).
Bulk baca kontak per-merchant + rate-limit/quota per tenant (bukan daftar tester hardcoded).

Phase W2 — Koordinasi & Token/Config Backfill Polqo

Estimasi: 1–2 hari (tergantung kesiapan Polqo)

Polqo sediakan tenant_id=kesles + API key untuk WhatsApp service.
Polqo konfirmasi endpoint schema /api/whatsapp/send (+ /template, /otp).
Polqo konfirmasi cara handle WABA: pakai nomor Kesles existing atau nomor shared Polqo.
Polqo sediakan callback/webhook agar delivery status balik ke Kesles DB.
Polqo konfirmasi rate limit + SLA latency/uptime per tenant.

Phase W3 — Shadow Mode (dual-send)

Estimasi: 3–5 hari, minimal 48 jam observasi

POLQO_WA_SHADOW_ENABLED=true

whatsapp-service kirim ke dua tujuan paralel — Meta WABA Kesles (primary, response inilah yang dikembalikan ke caller) + Polqo (shadow). Polqo failure tidak mempengaruhi delivery. Goal: verifikasi Polqo bisa deliver + bandingkan delivery/error rate.

⚠️ WhatsApp ≠ FCM di sini: shadow send berarti end-user bisa terima 2 pesan kalau Polqo benar-benar kirim ke nomor asli. Gunakan dry-run/sandbox di sisi Polqo untuk shadow (Polqo validasi sampai pre-send, tidak benar-benar deliver), atau batasi shadow ke nomor internal tim. Jangan shadow-send ke nomor merchant asli.

Phase W4 — Gradual Cutover per Template

Estimasi: 3–5 hari

Urut dari risiko terendah:

Urutan	Template	Risiko	Cutover
1	`merchant_tester_reminder` (marketing)	Rendah	Hari 1
2	`merchant_order_shipped`	Rendah	Hari 1
3	`merchant_payment_receipt`	Menengah	Hari 2
4	`merchant_transaction_alert`	Menengah	Hari 2–3
5	`merchant_payment_due`	Menengah	Hari 3
6	`merchant_otp_code`	Tinggi (auth flow)	Hari 4–5, setelah lain stabil

Mekanisme: tambah template ke POLQO_WA_TEMPLATES, restart. Monitor delivery/error/latency tiap step.

Phase W5 — Full Cutover

Estimasi: 1 hari

USE_POLQO_WA=true, hapus POLQO_WA_TEMPLATES.
Monitor 4 jam pertama aktif.
Jangan revoke Meta WABA credential Kesles (simpan di vault).

Phase W6 — Cleanup

Estimasi: 1 hari, 2 minggu setelah W5 stabil

Hapus code path USE_POLQO_WA=false.
Revoke Meta WABA credential Kesles dari vault.
Update architecture.md + whatsapp-service-status.md + ADR 0009.

5. Rollback

Dari phase	Aksi	Impact
W3 shadow	`POLQO_WA_SHADOW_ENABLED=false` + restart	Zero — primary tetap Meta Kesles
W4 gradual	`POLQO_WA_TEMPLATES=` (kosong) + restart	Semua balik ke Meta Kesles
W5 full	`USE_POLQO_WA=false` + restart	Balik ke Meta Kesles (credential masih valid sampai W6)

Jangan revoke Meta WABA Kesles sampai W5 stabil minimal 2 minggu.

6. Detail Rombak UI (Phase W1)

Berdasarkan whatsapp_tester_panel.dart + whatsapp_bulk_messaging_panel.dart:

Sekarang	Target SaaS
`return _SuperAdminGateBanner()` kalau bukan super-admin	Akses per role merchant, scoped `tenant_id`
Sample body raw JSON (`body_params[]`, `button_url_param`)	Form field bernama per template (pilih template → isi field)
Tidak ada onboarding	Halaman Connect WhatsApp — verifikasi nomor / status WABA
Tidak ada billing	Usage view (aggregate per merchant per template) — billing/topup DEFER sampai subscription produk ada
Lookup message manual via ID	Message log list tenant-scoped + filter status
Bulk → daftar tester hardcoded	Bulk → kontak per-merchant + quota/rate-limit per tenant

Menu "WhatsApp API" di-rename/di-split: bagian tester tetap super-admin (debug), bagian console jadi menu merchant baru.

7. Risiko & Mitigasi

Risiko	Likelihood	Impact	Mitigasi
Shadow-send kirim 2 WA ke nomor asli	Menengah	Tinggi	Sandbox/dry-run di Polqo, atau shadow ke nomor internal saja (§Phase W3)
Template belum approved di WABA Polqo	Menengah	Tinggi	Konfirmasi approval per template sebelum masuk `POLQO_WA_TEMPLATES`
`tenant_id` bocor antar tenant	Rendah	Tinggi	Tests isolation di W0, fail-closed `X-Tenant-ID`
OTP delay saat cutover (auth flow)	Rendah	Tinggi	`merchant_otp_code` cutover paling akhir, setelah lain stabil
Webhook OOM (finding 6.1 open)	Rendah	Menengah	`http.MaxBytesReader(w, r.Body, 1<<20)` saat sentuh handler di W0
Meta WABA Kesles di-revoke terlalu dini	Rendah	Tinggi	W6 cleanup hanya setelah 2 minggu stabil

8. Checklist Go/No-Go Full Cutover (Phase W5)

Semua harus YES:

9. Timeline Estimasi

Phase	Durasi	Catatan
W0 — Multi-tenancy backend	3–5 hari	Blocker
W1 — Rombak UI SaaS	5–8 hari	Sebagian paralel dengan W0
W2 — Koordinasi Polqo	1–2 hari	External dependency
W3 — Shadow mode	3–5 hari	Min. 48 jam, hati-hati double-send
W4 — Gradual cutover	3–5 hari	Per template
W5 — Full cutover	1 hari
W6 — Cleanup	1 hari	2 minggu setelah W5
Total	~3–4 minggu	Tergantung kesiapan Polqo + scope UI

Draft 2026-06-15. Pola referensi: ../firebase/polqo-migration-plan.md. Sumber audit: services/whatsapp_service/internal/, apps/merchant_dashboard/lib/dashboard/features/whatsapp_api/, whatsapp-service-status.md.

⚠️ Revisi 2026-06-16 — locked decisions​

A. Schema sudah tenant-ready (audit 2026-06-16)​

B. Dua sentinel tenant Kesles (bukan satu)​

C. Model billing — quota + overflow (FUTURE, subscription belum ada)​

D. WABA strategy — nomor Kesles existing​

E. Phase 4 template ordering — low-risk first → OTP last​

F. Mobile app behavior — platform vs merchant outbound split​

0. Kenapa dokumen ini ada​

1. Kondisi Sekarang (per 2026-06-15)​

Backend — matang tapi single-tenant​

UI — tester, bukan SaaS​

2. Arsitektur Target​

Saat ini (single-tenant)​

Target akhir (multi-tenant + Polqo)​

3. Feature Flag​

4. Tahapan​

Phase W0 — Multi-tenancy Backend (BLOCKER, kerjakan duluan)​

W0.1 — Middleware withTenantID + context ✅ DONE 2026-06-16​

W0.2 — Store: SELECT filter by tenant_id (pending)​

W0.3 — Insert path: write tenant_id dari context (pending)​

W0.4 — Webhook tenant routing (pending — strategy revised)​

W0.5 — Per-tenant config + 2 sentinel seed (pending)​

W0 — Phase gate (lulus ke W1)​

Phase W1 — Rombak UI jadi SaaS Console​

Phase W2 — Koordinasi & Token/Config Backfill Polqo​

Phase W3 — Shadow Mode (dual-send)​

Phase W4 — Gradual Cutover per Template​

Phase W5 — Full Cutover​

Phase W6 — Cleanup​

5. Rollback​

6. Detail Rombak UI (Phase W1)​

7. Risiko & Mitigasi​

8. Checklist Go/No-Go Full Cutover (Phase W5)​

9. Timeline Estimasi​

⚠️ Revisi 2026-06-16 — locked decisions

A. Schema sudah tenant-ready (audit 2026-06-16)

B. Dua sentinel tenant Kesles (bukan satu)

C. Model billing — quota + overflow (FUTURE, subscription belum ada)

D. WABA strategy — nomor Kesles existing

E. Phase 4 template ordering — low-risk first → OTP last

F. Mobile app behavior — platform vs merchant outbound split

0. Kenapa dokumen ini ada

1. Kondisi Sekarang (per 2026-06-15)

Backend — matang tapi single-tenant

UI — tester, bukan SaaS

2. Arsitektur Target

Saat ini (single-tenant)

Target akhir (multi-tenant + Polqo)

3. Feature Flag

4. Tahapan

Phase W0 — Multi-tenancy Backend (BLOCKER, kerjakan duluan)

W0.1 — Middleware `withTenantID` + context ✅ DONE 2026-06-16

W0.2 — Store: SELECT filter by tenant_id (pending)

W0.3 — Insert path: write tenant_id dari context (pending)

W0.4 — Webhook tenant routing (pending — strategy revised)

W0.5 — Per-tenant config + 2 sentinel seed (pending)

W0 — Phase gate (lulus ke W1)

Phase W1 — Rombak UI jadi SaaS Console

Phase W2 — Koordinasi & Token/Config Backfill Polqo

Phase W3 — Shadow Mode (dual-send)

Phase W4 — Gradual Cutover per Template

Phase W5 — Full Cutover

Phase W6 — Cleanup

5. Rollback

6. Detail Rombak UI (Phase W1)

7. Risiko & Mitigasi

8. Checklist Go/No-Go Full Cutover (Phase W5)

9. Timeline Estimasi