# Kebutuhan Infrastruktur & Arsitektur — Sistem Digital Hubla

**Penyusun:** Sanggabiz Consulting · **Klien:** PDAM Tirtamarta
**Asumsi:** Deployment di **Vercel**, platform web pakai **Astro**. Fokus Hubla (Fase 1), dirancang siap untuk bidang berikutnya.
**Pendamping:** [PRD](prd-hubla-digital-2025.md) · **Versi:** 0.1 — 24 Juni 2026

---

## 1. Ringkasan Jawaban Cepat

| Pertanyaan | Jawaban singkat |
|---|---|
| **Butuh database?** | **Ya, wajib.** Astro hanya lapisan web/SSR; data tiket, pelanggan, billing, work order, kas harus persisten & transaksional. Rekomendasi: **PostgreSQL** (serverless: Neon/Supabase/Vercel Postgres). |
| **Butuh AI agent?** | **Sebagian, ya — tapi tidak semuanya "agent".** Pisahkan: (a) **AI deterministik/ML** untuk OCR meter, anomali, scoring; (b) **LLM Agent (Claude)** untuk chatbot WhatsApp triase + emergency routing + copilot back-office. Untuk MVP Hubla, AI bernilai tertinggi = **bot WhatsApp omnichannel + emergency keyword routing**. |
| **Cukup Astro + Vercel saja?** | Untuk frontend + API ringan: ya. Untuk **background jobs** (broadcast massal, billing batch, scoring, rekonsiliasi) dan **realtime/host-to-host**: **butuh layanan tambahan** (queue, cron, worker) karena serverless Vercel punya batas durasi eksekusi. |

## 2. Peran Astro dalam Arsitektur Ini

Astro dipakai sebagai **lapisan presentasi + BFF (Backend-for-Frontend)**:

- **SSR/Hybrid rendering** untuk: Customer Portal (PWA), Admin CRM, Dashboard BI, landing/marketing.
- **API Routes (server endpoints)** Astro di Vercel Functions untuk operasi CRUD ringan & orkestrasi.
- **Island architecture** (React/Vue/Svelte islands) untuk bagian interaktif (inbox tiket, dashboard, form).
- **PWA + offline cache** (service worker) untuk app lapangan (meter reading, work order, POD) — memenuhi NFR offline-first.

**Yang TIDAK boleh dibebankan ke Astro/Vercel Functions saja:**
- Proses lama / batch (broadcast jutaan WA, billing engine, scoring harian) → pakai **queue + worker / cron**.
- State realtime persisten (antrean, notifikasi langsung) → pakai layanan realtime/websocket terkelola.
- Koneksi host-to-host bank yang butuh uptime 99.9% & < 5 dtk → idealnya **service backend khusus** (lihat §6).

## 3. Diagram Arsitektur (High-Level)

```mermaid
flowchart TB
  subgraph Clients[Pengguna]
    WA[WhatsApp]
    Cust[Customer Portal PWA]
    Admin[Admin CRM Web]
    Field[App Lapangan PWA offline]
    Exec[Dashboard Direksi]
  end

  subgraph Vercel[Vercel - Astro]
    Web[Astro SSR + UI Islands]
    API[Astro API Routes / BFF]
  end

  subgraph Edge[Layanan Pendukung]
    Queue[Queue + Cron Worker\nInngest/QStash]
    AI[LLM Agent - Claude API]
    OCR[OCR/Vision Service]
    RT[Realtime/Websocket]
  end

  subgraph Data[Data Layer]
    PG[(PostgreSQL\nNeon/Supabase)]
    Redis[(Redis cache/queue)]
    Blob[(Object Storage\nfoto meter, POD, berkas)]
  end

  subgraph Ext[Integrasi Eksternal]
    WABA[WhatsApp Business API]
    PG2[Payment Gateway / Switcher]
    Bank[Bank Host-to-Host / Rek Koran]
    Maps[Maps/GPS]
  end

  WA <--> WABA --> API
  Cust & Admin & Field & Exec --> Web --> API
  API <--> PG
  API <--> Redis
  API --> Blob
  API --> Queue
  API <--> AI
  Field --> OCR --> API
  Queue --> WABA
  Queue --> Bank
  API <--> PG2
  PG2 --> Bank
  API <--> Maps
  API <--> RT --> Admin
```

## 4. Apakah Butuh Database? — **Ya** (detail)

**Wajib database relasional transaksional.** Alasan: data inti saling berelasi & butuh konsistensi (tiket↔pelanggan↔tagihan↔pembayaran↔work order), butuh audit trail, dan banyak operasi finansial yang tidak boleh hilang/ganda.

**Rekomendasi:** **PostgreSQL serverless** — kompatibel Vercel & cocok untuk koneksi serverless:
- **Neon** atau **Supabase** (juga menyediakan Auth, Storage, Realtime) atau **Vercel Postgres**.
- ORM: **Drizzle** atau **Prisma** (Drizzle lebih ramah serverless/edge).
- **Connection pooling** wajib (PgBouncer/Neon pooler) karena fungsi serverless membuka banyak koneksi.

**Komponen data tambahan:**
| Kebutuhan | Teknologi | Untuk |
|---|---|---|
| Cache & rate-limit & antrean ringan | **Redis** (Upstash) | Sesi, dedup tiket, throttle broadcast |
| Object storage | **Vercel Blob / Cloudflare R2 / S3** | Foto meter, bukti perbaikan, POD e-sign, berkas pasang baru |
| Analytics/BI | **Postgres + materialized views** atau warehouse ringan | Dashboard CSAT, P&L, piutang (Fase ≥2) |
| Pencarian | Postgres full-text (cukup untuk MVP) | Cari pelanggan/tiket |

**Catatan:** Untuk MVP Hubla, **Supabase** menarik karena memberi Postgres + Auth + Storage + Realtime dalam satu paket → mempercepat Fase 1, dan tetap selaras dengan Astro/Vercel.

## 5. Apakah Butuh AI / AI Agent? — **Sebagian** (detail)

Pisahkan tiga jenis "AI" agar tidak over-engineering:

### 5.1 AI Deterministik / ML (bukan agent)
| Use case (JTBD) | Pendekatan | Kebutuhan |
|---|---|---|
| **OCR pembacaan meter (26)** | Vision/OCR model (Claude vision atau OCR khusus) | Service inferensi + fallback koreksi manual |
| **Anomali tagihan (28)** | **Rule-based dulu** (deviasi > 30%), ML belakangan | Tidak perlu agent; cukup logic di billing engine |
| **Collection scoring (31)** | **Rule-based + skoring** (lama tunggakan **+ ambang nominal Rp**) | Mulai rules; ML opsional setelah ada data |
| **Segmentasi upsell (7,12)** | Query/segmentasi DB | Tidak perlu LLM |

### 5.2 LLM Agent (Claude) — bernilai tinggi, opsional untuk MVP
| Use case | Peran Agent |
|---|---|
| **Bot WhatsApp omnichannel (1,2,29)** | Triase keluhan, jawab FAQ tagihan, pandu pembayaran, klasifikasi & buat tiket otomatis |
| **Emergency keyword routing (1)** | Deteksi niat darurat ("pipa bocor tengah malam") → eskalasi ke petugas piket 24/7 |
| **Copilot back-office** | Bantu CS draft balasan, ringkas riwayat pelanggan, draft quotation B2B (22) |

> **Rekomendasi model:** **Claude** (Anthropic API) — default ke model terbaru paling kapabel (mis. Claude Opus/Sonnet 4.x) untuk reasoning bot & copilot; gunakan model lebih kecil/murah untuk klasifikasi intent volume tinggi. Tool-use/function calling dipakai agar agent bisa membaca tagihan, membuat tiket, dan memicu work order lewat API internal.

### 5.3 Rekomendasi untuk MVP Hubla
- **Wajib AI di MVP:** klasifikasi intent + emergency routing pada inbox WhatsApp (nilai operasional langsung).
- **Tunda ke fase teknis terkait:** OCR meter (Fase 2), scoring/anomali (Fase 2).
- **Hindari di MVP:** ML kustom yang butuh data historis besar — pakai rules dulu.

**Catatan deployment AI di Vercel:** panggilan LLM dari Astro API Route bisa kena batas timeout untuk percakapan panjang/batch. Untuk **agent loop / broadcast / batch scoring**, jalankan via **queue/worker** (Inngest/QStash) bukan request HTTP sinkron.

## 6. Kebutuhan Infrastruktur — Daftar Lengkap

### 6.1 Inti (wajib, Fase 1)
| Komponen | Pilihan rekomendasi | Catatan |
|---|---|---|
| **Hosting web** | Vercel (Astro) | SSR + edge + functions |
| **Database** | PostgreSQL — Neon/Supabase/Vercel Postgres | + connection pooling |
| **ORM/Migrations** | Drizzle (atau Prisma) | Versi skema terkontrol |
| **Auth & RBAC** | Supabase Auth / Auth.js / Clerk | Peran: pelanggan, CS, lapangan, manajer, direksi |
| **Object storage** | Vercel Blob / Cloudflare R2 / S3 | Foto, berkas, e-sign |
| **Cache/Rate-limit** | Upstash Redis | Throttle WA, sesi |
| **Background jobs & cron** | Inngest atau QStash + Vercel Cron | Broadcast, batch, reminder terjadwal |
| **WhatsApp** | WhatsApp Business API (BSP resmi: mis. Meta/penyedia lokal) | Omnichannel + broadcast |
| **LLM** | Anthropic Claude API | Bot triase + emergency routing |
| **Monitoring/Logs** | Vercel Analytics + Sentry + Logflare/Axiom | Error & audit |
| **Secrets** | Vercel Env + (opsional) Doppler | Kunci API |
| **Email/SMS fallback** | Resend / Twilio | Notifikasi non-WA |

### 6.2 Fase 2 (Penagihan)
| Komponen | Catatan |
|---|---|
| **OCR/Vision service** | Pembacaan meter (cloud vision atau model khusus) |
| **Payment Gateway / Switcher** | Virtual Account, QRIS, host-to-host (Midtrans/Xendit/Doku atau switcher bank) |
| **Bank rek koran API** | Auto-rekonsiliasi |
| **Billing engine** | Bisa modul terpisah (service) bila volume besar; pertimbangkan worker khusus |
| **Realtime** | Supabase Realtime / Pusher untuk status lunas instan |

### 6.3 Fase 3 (AMDK/Kolam)
| Komponen | Catatan |
|---|---|
| **Barcode/QR scanning** | WMS, distribusi, e-ticketing |
| **POS** | Loket AMDK & kolam |
| **Integrasi hardware** | Turnstile gate, mesin absensi biometrik (integrasi, hardware diadakan terpisah) |
| **BI/Warehouse** | Materialized views → bila perlu, warehouse (BigQuery/ClickHouse) |
| **HRIS/Payroll** | Modul atau integrasi sistem absensi cloud |

## 7. Pertimbangan & Risiko Arsitektur

1. **Batas serverless Vercel** (durasi/eksekusi) → wajib queue/worker untuk proses lama. Jangan paksakan billing batch & broadcast di API route sinkron.
2. **Host-to-host 99.9% & < 5 dtk** → komponen pembayaran sebaiknya service terpisah/managed gateway, bukan murni di Astro function.
3. **Offline-first lapangan** → desain sinkronisasi (conflict resolution) sejak awal untuk meter & work order.
4. **Keamanan data pelanggan (UU PDP)** → enkripsi, RBAC ketat, audit trail anti-tamper untuk kas & meter.
5. **Consent broadcast WA** → kelola opt-in/opt-out agar patuh kebijakan WhatsApp & PDP.
6. **Biaya AI** → gunakan model kecil untuk klasifikasi volume tinggi, model besar hanya untuk reasoning; cache jawaban FAQ.
7. **Multi-bidang sejak awal** → identity, master data, ticketing engine, design system dibuat *shared* agar SPI/Teknik/Umum tinggal menyambung.

## 8. Rekomendasi Stack MVP (Fase 1) — Konkret

```
Frontend/Platform : Astro (SSR/hybrid) + UI islands (React) + PWA (offline app lapangan)
Hosting           : Vercel
Database          : PostgreSQL (Supabase) + Drizzle ORM + pooling
Auth/RBAC         : Supabase Auth
Storage           : Supabase Storage / Vercel Blob (foto, berkas, e-sign)
Cache/Queue ringan: Upstash Redis
Background jobs   : Inngest (broadcast, reminder, CSAT auto-send)
Omnichannel       : WhatsApp Business API (via BSP)
AI                : Anthropic Claude API (intent triage + emergency routing)
Monitoring        : Sentry + Vercel Analytics
```

Stack ini cukup membangun MVP Humas Pipa Air dan menjadi fondasi untuk Penagihan, AMDK/Kolam, serta bidang SPI/Teknik/Umum berikutnya.

---

## 9. Topologi Deployment dengan Aset Tersedia

Aset yang dimiliki klien: **VPS**, **Vercel Pro**, **Supabase Pro**, dan **akses AI LLM**. Kombinasi ini **menutup seluruh kebutuhan** tanpa layanan pihak ketiga tambahan (tidak perlu Upstash, Inngest/QStash, dll. — fungsinya dipindah ke VPS & Supabase).

### 9.1 Prinsip pembagian beban

> **Vercel** = yang *stateless & request-driven* (web + API pendek).
> **Supabase** = *sumber kebenaran data* (DB, Auth, Storage, Realtime).
> **VPS** = yang *long-running, persisten, atau butuh IP statis* (worker, gateway, agent, cron).
> **LLM** = otak untuk triase, OCR, dan copilot.

### 9.2 Apa jalan di mana

| Komponen | Lokasi | Alasan |
|---|---|---|
| Astro SSR/hybrid + UI (portal, CRM, dashboard) | **Vercel Pro** | CDN global, deploy preview, fungsi durasi lebih panjang (Pro) |
| API Route / BFF (CRUD pendek, auth check) | **Vercel Pro** | Dekat dengan frontend, akses Supabase via service client |
| PostgreSQL (data inti) | **Supabase Pro** | Sumber kebenaran; pakai **RLS** untuk keamanan portal pelanggan |
| Auth & RBAC (pelanggan, CS, lapangan, manajer, direksi) | **Supabase Auth** | Built-in + Row Level Security |
| Object storage (foto meter, POD, e-sign, berkas) | **Supabase Storage** | Terintegrasi RLS & DB |
| Realtime (inbox tiket live, status lunas instan) | **Supabase Realtime** | Tanpa server websocket tambahan |
| Knowledge base FAQ untuk bot (retrieval) | **Supabase pgvector** | Embedding + similarity search |
| Webhook ringan (callback bayar, inbound WA) | **Supabase Edge Functions** atau VPS | Pilih Edge bila sederhana; VPS bila perlu antrean |
| **Worker antrean** (broadcast massal, CSAT auto-send, reminder) | **VPS** (BullMQ + Redis self-host) | Proses lama melebihi batas serverless |
| **Billing/DRD batch** (puluhan ribu rekening) | **VPS** | Job berat & terjadwal |
| **Collection scoring** (nightly 00:00) | **VPS** (cron) | Batch analitik rutin |
| **Auto-rekonsiliasi** bank | **VPS** | Tarik rek koran + matching terjadwal |
| **WhatsApp gateway** (inbound/outbound, broadcast) | **VPS** | Koneksi persisten + rate control |
| **Payment host-to-host** (bank & retail) | **VPS** | Butuh **IP statis** untuk whitelisting bank, uptime 99.9%, < 5 dtk |
| **AI Agent loop** (percakapan panjang, tool-use, OCR batch ribuan meter) | **VPS** | Long-running, tidak cocok di fungsi serverless |
| **AI turn pendek** (klasifikasi intent 1 pesan, draft balasan CS) | **Vercel / Supabase Edge** → LLM | Sinkron & cepat, cukup di edge |
| Redis (queue + cache + rate-limit) | **VPS** (self-host) | Gantikan Upstash |
| Cron/scheduler | **VPS cron** (+ Vercel Cron untuk trigger ringan) | Penjadwalan andal |
| LLM (triase WA, emergency routing, OCR meter, copilot) | **AI LLM** | Dipanggil dari VPS (berat) atau edge (ringan) |
| Monitoring | **Vercel Analytics** + Sentry + log VPS | Observability |

### 9.3 Diagram topologi

```mermaid
flowchart LR
  subgraph V[Vercel Pro]
    A[Astro Web + UI]
    B[API Routes / BFF]
  end
  subgraph S[Supabase Pro]
    DB[(Postgres + RLS)]
    AUTH[Auth/RBAC]
    ST[(Storage)]
    RT[Realtime]
    VEC[(pgvector)]
  end
  subgraph VPS[VPS - layanan persisten]
    Q[Worker + Redis Queue]
    WA[WhatsApp Gateway]
    PAY[Payment Host-to-Host\nIP statis]
    AGENT[AI Agent / OCR batch]
    CRON[Cron: billing, scoring, rekon]
  end
  LLM[(AI LLM)]
  BANK[Bank / Retail / Switcher]

  A --> B --> DB
  B --> AUTH
  B --> ST
  A <-- RT --- DB
  B -->|enqueue| Q
  Q --> WA --> LLM
  Q --> DB
  AGENT --> LLM
  AGENT --> VEC
  CRON --> DB
  PAY <--> BANK
  PAY --> DB
  WA <--> BANK
```

### 9.4 Keamanan & jaringan antar-komponen

- **Vercel ↔ Supabase**: pakai `service_role key` hanya di server (API route), `anon key` + **RLS** untuk akses dari browser pelanggan.
- **VPS ↔ Supabase**: worker konek langsung ke Postgres (connection pooler) + service key; atau lewat API internal.
- **VPS** sebaiknya di balik reverse proxy (Nginx/Caddy) + TLS; endpoint host-to-host dibatasi **IP allowlist** bank.
- **Secrets**: Vercel Env untuk frontend/API; `.env` terkunci / vault di VPS. Jangan pernah taruh `service_role` di client.
- **Audit trail anti-tamper** (kas, meter) disimpan di Postgres dengan trigger append-only.

### 9.5 Kapan VPS benar-benar dipakai per fase

| Fase | Vercel + Supabase cukup? | Peran VPS |
|---|---|---|
| **1. Humas Pipa Air (MVP)** | **Hampir cukup** | Opsional: worker broadcast WA + AI agent triase. Sisanya bisa di Vercel+Supabase. |
| **2. Penagihan** | Tidak | **Wajib**: payment host-to-host (IP statis), billing batch, scoring, rekonsiliasi, OCR meter. |
| **3. AMDK/Kolam** | (di luar lingkup ini) | — |

**Kesimpulan:** untuk **MVP Fase 1**, deploy Astro ke Vercel Pro + Supabase Pro sudah jalan; VPS mulai krusial saat masuk **Penagihan (Fase 2)**. LLM dipakai sejak Fase 1 untuk bot WhatsApp + emergency routing.

### 9.6 Stack final (revisi dari §8, memakai aset tersedia)

```
Frontend/Platform : Astro (SSR/hybrid) + UI islands + PWA  →  Vercel Pro
Database          : Supabase Postgres + RLS + Drizzle ORM
Auth/RBAC         : Supabase Auth
Storage           : Supabase Storage
Realtime          : Supabase Realtime
Vector/FAQ        : Supabase pgvector
Queue/Cache       : Redis (self-host di VPS) + BullMQ
Background/Cron   : Worker Node di VPS (broadcast, billing batch, scoring, rekon)
WhatsApp gateway  : Service di VPS  ↔  WhatsApp Business API
Payment H2H       : Service di VPS (IP statis, whitelist bank)
AI                : LLM — agent di VPS (berat) + edge call (ringan)
Monitoring        : Vercel Analytics + Sentry + log VPS
```