whatsapp-inbox-platform/docs/code-documentation.md

WhatsApp Inbox Platform – Dokumentasi Kode

Dokumen ini menjelaskan arsitektur dan alur utama aplikasi supaya mudah dipahami saat onboarding, debug, atau audit.

1. Gambaran Sistem

Stack yang dipakai:

• Frontend + backend: Next.js 15 (App Router).
• Database: PostgreSQL + Prisma ORM.
• Autentikasi custom: cookie session berbasis payload ter-tanda-tangan.
• Job worker: campaign retry worker berbasis script Node.
• Proses produksi: PM2 + Nginx sebagai reverse proxy.
• Logging dan health check: endpoint internal + script operasi.

2. Struktur Folder Penting

app/ Himpunan route Next.js, termasuk endpoint autentikasi dan halaman admin.

lib/ Modul inti:

• auth/session.
• prisma client.
• util i18n.
• request url utility.
• audit & rate limit.

prisma/ Skema dan migrasi database.

scripts/ Operasional dan maintenance:

• ops scripts.
• job scripts.

public/ Asset statis.

3. Alur Autentikasi

3.1 Login

1. POST ke /auth/login.
2. Validasi rate limit, credential, dan status user.
3. Jika valid, session dibuat dan disimpan di cookie wa_inbox_session.
4. Cookie diset dengan:
   • httpOnly.
   • sameSite: "lax".
   • secure sesuai env/protocol.
   • domain dari SESSION_COOKIE_DOMAIN bila di-set.
   • maxAge dari nilai session TTL.
5. Response diarahkan ke route default sesuai role.

File:

• app/auth/login/route.ts

3.2 Middleware Guard

Setiap request (kecuali API) dilewati middleware untuk validasi:

• Mengecek session cookie.
• Redirect ke /login?next=... jika tidak ada session.
• Mengarahkan user ke default path role jika sudah login dan masuk halaman publik tertentu.
• Redirect unauthorized jika role tidak punya akses.
• Menangani locale cookie fallback.

File:

• middleware.ts

3.3 Parse Session

Session token dibuat dari payload user lalu ditandatangani dengan HMAC.

Modul inti:

• lib/auth.ts

Berisi:

• tipe session.
• validasi role.
• serialisasi/deserialisasi cookie.
• helper konfigurasi session (getSessionTtlSeconds, getSessionCookieDomain).

4. Konfigurasi Session dan Cookie

4.1 TTL Session

Nilai diambil dari env:

• SESSION_TTL_SECONDS (prioritas utama).
• SESSION_TTL_HOURS (fallback legacy).

Default fallback tetap saat env tidak ada.

4.2 Cookie Hardening

Untuk environment HTTPS/prod:

• COOKIE_SECURE=true.
• SESSION_COOKIE_DOMAIN=web.zappcare.id (jika pakai subdomain).
• SESSION_COOKIE_DOMAIN akan diabaikan untuk localhost/127.0.0.1.

5. Modul dan Script Operasional

5.1 Script Deploy Aman

scripts/ops-safe-restart.sh:

• cek .env.
• install dependency (npm ci).
• build.
• deploy migration Prisma (npm run db:deploy).
• restart/start PM2.
• optional healthcheck.
• save PM2 state.

NPM script:

• npm run ops:safe-restart

5.2 Script Verifikasi Session

scripts/ops-session-check.mjs:

• login otomatis via akun health check.
• verifikasi cookie sesi terbit.
• validasi TTL.
• cek akses page protected (/super-admin) dengan cookie sesi.

NPM script:

• npm run ops:session-check

5.3 Dokumentasi Operasional Terkait

• ops-runbook.md
• production-readiness-checklist.md

6. Catatan Debug Umum

Gejala: Kembali ke halaman login setelah klik menu

Penyebab paling umum:

• sesi tidak tersimpan karena cookie secure/domain tidak cocok.
• domain/protocol HTTPS mismatch.
• proses logout tidak sengaja terpicu.
• path/role mismatch pada middleware.

Pengecekan:

• lihat response headers:
  • X-Auth-Session
  • X-Auth-Session-Has-Cookie
  • X-Auth-Base-Url
• cek cookie di browser devtools (nama wa_inbox_session, secure/domain/path/maxAge).
• cek log aplikasi (pm2 logs ... + grep AUTH).

Gejala: Loop redirect login (bahasa Inggris / error invalid credential)

Pastikan:

• AUTH_SECRET ada di env prod.
• APP_URL / OPS_BASE_URL sesuai domain HTTPS.
• COOKIE_SECURE sesuai mode.
• Nginx tidak strip header Cookie.

7. Catatan Implementasi Khusus

• Logout flow sudah difokuskan ke request non-prefetch agar tidak terpicu by mistake pada prefetch link.
• Script yang diubah untuk mencegah kegagalan sesi karena navigasi prefetch.
• Penambahan debugging header di middleware/login untuk mempercepat root cause analysis.

8. Dependency Environment Wajib (Ringkas)

• DATABASE_URL
• AUTH_SECRET
• APP_URL
• SESSION_TTL_SECONDS
• COOKIE_SECURE
• SESSION_COOKIE_DOMAIN (jika dibutuhkan)
• WHATSAPP_*, CAMPAIGN_*, dan token internal sesuai fitur aktif.

Lihat juga:

• ops-runbook.md
• production-readiness-checklist.md
• .env.example