<!--
  Project Documentation
  Scope: WhatsApp Inbox Platform
-->

# 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`