Skip to content

Arsitektur Sistem (SV-ARCH-001)

Field Nilai
ID Dokumen SV-ARCH-001
Pilar Desain
Standar Acuan ISO/IEC/IEEE 42010 & IEEE 1016
Status Aktif / Tersinkronisasi dengan Kode
Terakhir Diperbarui 2026-11-21
Sumber Kebenaran package.json, next.config.ts, src/proxy.ts, src/app/**, src/features/**, src/lib/**, src/ui/**, docker-compose.yml, Dockerfile

Gambaran arsitektur teknis Sudirman Voice (versi 1.2.0) untuk pengembang dan pemelihara sistem. Dokumen terkait dalam suite ini: desain-sistem.md, data-model.md, keamanan-dan-privasi.md, api-dan-antarmuka.md, sdlc-dan-pengujian.md, operasional.md, dan kontribusi.md.

Sudirman Voice adalah aplikasi web monolitik modular berbasis Next.js App Router yang berjalan sebagai container Node.js standalone di VPS P3MDI di belakang reverse proxy Traefik, terhubung ke basis data terkelola Neon PostgreSQL serta layanan eksternal Google OIDC, Web Push (VAPID), SMTP Hostinger, dan pemicu cron eksternal.

flowchart TB
  User["Pengguna / Serdik / Pengelola / Admin (Browser & PWA)"]
  Cron["Layanan Cron Eksternal (cron-job.org)"]
  Traefik["Traefik Reverse Proxy (HTTPS / TLS Let's Encrypt)"]
  App["Sudirman Voice Container (Next.js 16 Standalone, Node 24)"]
  DB[("Neon PostgreSQL 16 (Pooled / Unpooled)")]
  Google["Google OAuth 2.0 / OIDC (accounts.google.com)"]
  Push["Web Push Service (FCM / Apple Push / Mozilla)"]
  SMTP["Hostinger SMTP (smtp.hostinger.com:465)"]

  User -->|"HTTPS + Cookie sv_session"| Traefik
  Cron -->|"HTTPS + Bearer CRON_SECRET"| Traefik
  Traefik -->|"HTTP :3000 + x-real-ip / x-forwarded-*"| App
  App -->|"Prisma 7 + @prisma/adapter-pg"| DB
  App -->|"OAuth Code + PKCE (TLS)"| Google
  App -->|"after() VAPID Web Push"| Push
  App -->|"Nodemailer Pool (Cron / Langsung)"| SMTP
Lapisan Teknologi Catatan Implementasi
Framework Next.js 16.4.6 (App Router, Server Components, Server Actions, output: "standalone") Memakai src/proxy.ts (pengganti middleware tradisional) dan experimental.authInterrupts: true
UI & Styling React 19.3.0, Tailwind CSS v4 (@tailwindcss/turbopack), TipTap 3.33.1 Token tema tunggal di src/app/globals.css; editor TipTap untuk pendahuluan form
Bahasa TypeScript 5 (strict: true), ES Modules ("type": "module") Runtime target Node.js >= 24
Database PostgreSQL 16 di Neon (Production: proyek organisasi voice; Dev: proyek dev; Tes lokal: port 5433 sv_test) Aplikasi memakai DATABASE_URL (pooled); Prisma CLI memakai DATABASE_URL_UNPOOLED (direct) dengan schema=public
ORM Prisma 7.10.1 + @prisma/adapter-pg + pg 8.23.1 Client hasil generate di src/generated/prisma (tidak di-commit)
Validasi Zod 4.6.7 Validasi skema input di service (src/features/*) dan parameter di Server Action
Keamanan PIN @node-rs/argon2 2.2.2 (Argon2id) & node:crypto (SHA-256, timingSafeEqual, CSPRNG) Hash PIN Argon2id; token sesi & kode email di-hash SHA-256
Dokumen & Media exceljs 4.4.0, Web Canvas API (di browser) Impor/ekspor .xlsx/.csv; kompresi & penghapusan EXIF gambar di perangkat pengguna
Notifikasi web-push 3.6.7, nodemailer 10.6.0 Jalur lonceng in-app, Web Push via after(), serta antrean & kirim langsung SMTP
Tes Vitest 5.1.0 (unit & integrasi Postgres asli), Playwright 1.63.0 (E2E mobile viewport) tests/unit/ (35), tests/integration/ (60), tests/e2e/ (21)
Hosting & CI/CD VPS Hostinger (Docker Compose di jaringan eksternal coolify di belakang Traefik), GitHub Actions Dev: voice-dev.p3mdi.id (dev), Production: voice.p3mdi.id (main)

Seluruh kode aplikasi tersusun berorientasi domain di src/features/ dan routing tipis di src/app/:

src/
proxy.ts Meneruskan header x-pathname untuk redirect /masuk?next=<path>
app/ 50 halaman (page.tsx), 15 Route Handlers (route.ts), 24 berkas Server Action
(app)/ Area terautentikasi dengan AppShell, pengecekan persetujuan & pengingat
(beranda)/ Halaman Beranda (/)
admin/ impor, laporan (+ [kode]), log, peran (+ [id]), permintaan-data, serdik
aspirasi/ daftar (/aspirasi), kirim, detail ([kode]), tindak-lanjut (+ [kode])
form/ daftar (/form), isi/riwayat ([kode]), hasil publik ([kode]/hasil)
hackathon/ daftar, detail ([kode]), nilai juri ([kode]/nilai), submisi ([kode]/submisi)
kelola/ form (+ impor, [kode], edit, export), polling (+ impor, [kode], edit, export),
hackathon (+ baru, [kode], edit, rekap, excel)
lemusdik/ aspirasi (+ impor, export, [kode]), kategori
notifikasi/ Server Actions penanda baca notifikasi
panduan/ Panduan kontekstual sesuai hak akses
persetujuan/ Layar persetujuan Ketentuan Penggunaan Data
polling/ daftar terbuka/arsip (/polling), detail ([kode])
profil/ profil, ganti-pin, laporkan, privasi (+ ketentuan, unduh)
aktivasi/ Aktivasi akun & lupa PIN (Google OIDC / kode email 6 digit)
ganti-pin/ Paksa ganti PIN wajib (mustChangePin = true)
masuk/ Login No. Serdik + PIN + Mode uji
keluar/ POST logout (hapus sesi & cookie)
api/ auth/google/{start,callback}, cron/{email,pengingat}, push, sehat
aspirasi-gambar/ Penyaji gambar aspirasi & foto bukti berotorisasi ([kode]/[id])
form-banner/ Penyaji gambar banner form berotorisasi ([kode])
hackathon-gambar/ Penyaji tangkapan layar submisi hackathon berotorisasi ([kode]/[id])
features/ 15 domain bisnis (service, validasi, aturan murni, UI spesifik domain)
admin/ Data Serdik, impor Excel/CSV Serdik, peran dinamis, audit log, label
aspirasi/ Kirim aspirasi, dasbor Lemusdik, kategori, gambar, ekspor, tindak lanjut
auth/ Sesi, login, throttle IP, lockout akun, RBAC izin.ts, guards, Google OIDC, kode email
beranda/ Hero sapaan, panel aksi cepat, antrean form/polling, banner hackathon
form/ Builder form 8 jenis pertanyaan, pendahuluan HTML, banner 4:1, rekap, template
hackathon/ Manajemen hackathon, bidang & kriteria, tim, submisi, nilai juri, rating bintang, rekap
impor/ Parser generik CSV/XLSX & importer Form, Polling, dan Aspirasi lama
konten/ Kepemilikan konten berbasis peran (kepemilikan.ts) & mesin siklus hidup (siklus.ts)
laporan/ Laporkan masalah (pembatasan 5/hari, jeda 30 detik, info perangkat ringkas)
notifikasi/ Notifikasi in-app, Web Push (after), antrean & kirim SMTP, pengingat & ringkasan harian
panduan/ Materi panduan dinamis per fitur yang dimiliki pengguna (`panduanUntuk`)
pengaturan/ Pengaturan global kunci-nilai (mis. sakelar tampil/sembunyi Hackathon)
polling/ Buat & kelola polling, pilih/ubah/batal pilihan, rekap SQL, template, ekspor
privasi/ Ketentuan Penggunaan Data berversi, persetujuan, mode hanya-baca, ekspor data, DAT-*
profil/ Ringkasan "Jejakmu" (aspirasi, form, polling yang diikuti)
lib/ Utilitas murni: db, pin, pin-rules, no-serdik, waktu WIB, target, tautan, result, cron-auth
ui/ Komponen bersama: AppShell, Sidebar, Topbar, BottomNav, Sheet, Konfirmasi, Icon (SVG)
prisma/ schema.prisma (39 model, 12 enum), 36 migrasi SQL, seed & seed-demo
scripts/ deploy-vps.sh, setup.ts, test-db.sh, buat-contoh-impor.ts, buat-contoh-unduhan.ts
tests/ unit/ (35), integration/ (60), e2e/ (21), helpers/, fixtures/

Aplikasi memisahkan secara tegas lapisan transport (src/app), lapisan otorisasi/bisnis (src/features), dan lapisan utilitas/basis data (src/lib & Prisma).

flowchart LR
  Browser["Browser / PWA"] -->|"HTTP + Cookie sv_session"| Proxy["src/proxy.ts (set x-pathname)"]
  Proxy --> Layout["Layout / Page di src/app"]
  Layout -->|"requireUser() / requireIzin()"| Guards["src/features/auth/guards.ts"]
  Browser -->|"Submit Form / Server Action"| Actions["actions.ts di src/app"]
  Actions -->|"Cek auth & read-only privasi"| Service["Service di src/features/*"]
  Service -->|"Cek izin ulang dari DB"| Izin["src/features/auth/izin.ts"]
  Service -->|"Validasi Zod + Transaksi + Row Lock"| DB[("PostgreSQL via Prisma 7")]
  Service -->|"Result ok / fail"| Actions
  1. Proxy (src/proxy.ts): Hanya menyalin pathname + search ke header permintaan x-pathname agar server guards dapat membentuk URL /masuk?next=<path>. Tidak ada logika autentikasi di proxy; seluruh pemeriksaan akses terjadi di server.
  2. Route & Layout (src/app/): Komponen server membaca parameter, memanggil requireUser() atau requireIzin(fitur) di layout dan page, lalu memanggil fungsi baca di service.
  3. Server Action (actions.ts): Memvalidasi sesi pengguna (requireUser/requireIzin/requireAdmin), memeriksa status persetujuan data (pesanHanyaBaca) pada aksi tulis peserta, merapikan/memotong batas panjang input mentah, memanggil service, lalu melakukan revalidatePath/refresh/redirect.
  4. Service (src/features/*): Memegang seluruh aturan bisnis, membaca ulang peran aktif dari database pada setiap mutasi, menjalankan validasi Zod, dan mengembalikan tipe Result<T> (ok(data) atau fail(code, message, fields)) alih-alih melempar exception untuk kondisi bisnis wajar. Kode galat baku meliputi FORBIDDEN, NOT_FOUND, VALIDATION, STATUS, TERKUNCI, TUTUP, SUDAH, LIMIT, JEDA, KONFLIK, PENUH, MUNDUR, BENTROK, SERI, BELUM, KODE, KONFIGURASI, KIRIM, SELF_ADMIN, SELF_DEACTIVATE, LAST_ADMIN, SISTEM, EMPTY.

5. Autentikasi, Otorisasi, dan Penanganan Redirect

Section titled “5. Autentikasi, Otorisasi, dan Penanganan Redirect”
  • Login Harian: No. Serdik (001–400) dan PIN 6 digit yang di-hash dengan Argon2id (@node-rs/argon2). Sesi disimpan sebagai token acak 32 byte (base64url) di cookie httpOnly sv_session, sementara di tabel sessions hanya tersimpan hash SHA-256-nya (token_hash). Masa berlaku sesi 30 hari dengan perpanjangan otomatis (sliding expiration) jika sisa masa aktif di bawah 15 hari, dan pembaruan lastSeenAt minimal setiap 5 menit.
  • Proteksi Brute-force: Menggunakan pola reserve-then-refund atomik sebelum verifikasi Argon2id: maksimal 20 percobaan gagal per 10 menit per IP (login_throttles) dan 5 percobaan gagal per siklus per akun sebelum akun dikunci 10 menit (lockedUntil). IP klien diambil dari x-real-ip (diisi Traefik dari koneksi TCP), lalu jatuh ke entri paling kanan x-forwarded-for.
  • Aktivasi Akun & Lupa PIN (/aktivasi): Pengguna memasukkan No. Serdik dan membuktikan kepemilikan email yang telah dicatat Admin untuk akun tersebut (bisa alamat P3MDI maupun email pribadi) melalui dua jalur:
    1. Google OAuth 2.0 / OIDC + PKCE: /api/auth/google/start menyimpan state, nonce, dan PKCE verifier di cookie sv_oauth (httpOnly, 10 menit, path /api/auth/google). Callback menukar code ke oauth2.googleapis.com/token via TLS, memverifikasi klaim iss, aud, nonce, exp, dan email_verified, lalu memanggil aktivasiGoogle().
    2. Kode Email 6 Digit: Mengirim OTP 6 digit (kode_email, hash SHA-256 userId:kode, berlaku 10 menit, maks 5 percobaan, maks 3 kali kirim per 15 menit) ke alamat yang tercatat. Setelah terbukti, akun dibuka kuncinya dan diberi sesi sementara dengan mustChangePin = true yang wajib melewati /ganti-pin.
  • Mode Uji (DEV_LOGIN=true): Memungkinkan penggantian akun dari header. Dinonaktifkan secara mutlak jika APP_ENV=production, VERCEL_ENV=production, atau jika DATABASE_URL mengarah ke PRODUCTION_DB_HOST.
  • Asal Publik & Keamanan Redirect: asalPermintaan() membaca x-forwarded-host dan x-forwarded-proto agar callback OAuth, same-origin check Web Push, dan redirect POST /keluar (303) memakai host publik di belakang Traefik. safeNext() memblokir path non-lokal (//, \, ://, karakter kontrol).

5.2 Otorisasi: Peran Dinamis & Kepemilikan Peran

Section titled “5.2 Otorisasi: Peran Dinamis & Kepemilikan Peran”
  • Model Peran: Tabel peran menyimpan peran sistem (kode = "ADMIN" dan kode = "LEMUSDIK", tidak dapat dinonaktifkan) serta peran dinamis lain yang dikelola Admin dengan empat flag izin: izinForm, izinPolling, izinDataUser, dan izinHackathon (peran non-sistem wajib memiliki minimal satu flag izin).
  • Single Source of Truth: Fungsi bisa(peran, fitur) di src/features/auth/izin.ts menentukan akses untuk 6 fitur: form, polling, dataUser, aspirasi, admin, dan hackathon.
  • Penjagaan Dua Lapis:
    1. Layout guard (requireIzin / requireAdmin) mengembalikan halaman 403 (src/app/forbidden.tsx) untuk rute tanpa izin.
    2. Service guard membaca ulang muatPeran(actorId) langsung dari database pada setiap aksi sehingga pencabutan atau penonaktifan peran berlaku seketika.
  • Kepemilikan Konten Berbasis Peran: Form, Polling, Template, dan Hackathon dimiliki oleh peran (peranId), bukan individu pembuatnya. Pengelola hanya melihat dan dapat mengubah konten milik peran yang ia pegang (Admin melihat semua). Upaya mengakses kode item milik peran lain dibalas NOT_FOUND (404) agar keberadaan konten peran lain tidak bocor.

6. Konsistensi Data, Konkurensi & Penguncian Baris

Section titled “6. Konsistensi Data, Konkurensi & Penguncian Baris”

Untuk mencegah race condition pada aksi bersamaan (klik ganda, pengisian bersamaan saat penutupan, atau perubahan status paralel), service menerapkan pessimistic row locking PostgreSQL dan optimistic conditional update:

sequenceDiagram
  participant S as Serdik (Submit Form / Pilih Polling / Nilai)
  participant P as Pengelola (Tutup / Ubah Skema / Hapus)
  participant DB as PostgreSQL

  par Transaksi Pengisian
    S->>DB: BEGIN + SELECT id, status, tenggat FROM public.forms/polls/hackathons FOR SHARE
    Note over DB: Menahan FOR UPDATE sampai pengisian selesai
    S->>DB: Cek ulang status efektif, target, & validasi skema
    S->>DB: INSERT form_responses / upsert poll_votes / rating
    S->>DB: COMMIT
  and Transaksi Manajemen
    P->>DB: BEGIN + SELECT id FROM public.forms/polls/hackathons FOR UPDATE
    Note over DB: Menunggu semua FOR SHARE aktif selesai
    P->>DB: Hitung ulang jawaban / cek status saat ini
    P->>DB: UPDATE status bersyarat (WHERE id = $1 AND status = $2) atau DELETE
    P->>DB: COMMIT
  end
  • Form & Polling (konten/siklus.ts): Tutup, sembunyikan, dan hapus konten memakai SELECT id FROM public.forms|polls WHERE id = $1::uuid FOR UPDATE sebelum memperbarui atau menghitung jawaban. Sebaliknya, pengiriman jawaban (submitForm), penandaan tautan luar (tandaiSelesai, batalkanTanda), dan pemungutan suara (pilih, batalPilih) mengambil FOR SHARE lalu memeriksa ulang status efektif, target, dan skema di dalam transaksi.
  • Penguncian Edit Otomatis: Setelah jawaban/suara pertama masuk, skema pertanyaan form, jenis form, kerahasiaan, dan target (atau pertanyaan, opsi, mode, jumlah pilihan, dan target pada polling) terkunci. Pengaturan anonim pada polling terkunci sejak status TERBIT.
  • Hackathon (hackathon/kelola.ts, tim.ts, nilai.ts): Perpindahan tahap panitia mengambil FOR UPDATE pada baris hackathons; pembentukan/perubahan tim mengambil FOR SHARE pada hackathons dan FOR UPDATE pada hackathon_tim; pemberian bintang dan nilai juri mengambil FOR SHARE pada hackathons.
  • Aspirasi (aspirasi/lemusdik.ts): Perubahan status memakai optimistic concurrency control (updateMany dengan where: { id, status: a.status }) sehingga dua pengurus yang mengubah status bersamaan tidak menimpa transisi satu sama lain (BENTROK).
  • Admin Set Advisory Lock (admin/users.ts): Penurunan/penonaktifan Admin menggunakan pg_advisory_xact_lock(724001) agar sistem tidak pernah berakhir tanpa Admin aktif (LAST_ADMIN).
  • Ringkasan Harian & Pengingat Panitia: Memakai pg_advisory_xact_lock(hashtext(kunci)) agar tumpang tindih eksekusi cron atau permintaan berurutan tidak memicu duplikasi.

7. Privasi, Notifikasi, Impor, Waktu, dan Tampilan

Section titled “7. Privasi, Notifikasi, Impor, Waktu, dan Tampilan”
  • Privasi & Persetujuan Data: Mendukung persetujuan berversi (VERSI_KETENTUAN), mode hanya-baca bila belum setuju atau saat persetujuan ditarik, ekspor seluruh data pribadi ke Excel (/profil/privasi/unduh), permintaan data DAT-XXXX, serta pemisahan tegas identitas pada Aspirasi Rahasia, Form Rahasia, dan Polling Anonim (lihat keamanan-dan-privasi.md).
  • Notifikasi Tiga Jalur (notifikasi/push.ts, email.ts, pengingat.ts, ringkasan.ts):
    1. Lonceng in-app: Dicatat di notifications dalam transaksi bisnis yang sama.
    2. Web Push: Dijadwalkan via after() setelah respons dikirim, membaca ulang baris notifikasi per id agar transaksi yang rollback tidak pernah terkirim. Langganan perangkat dipindah ke akun yang sedang login dan dihapus dari perangkat saat POST /keluar.
    3. Email SMTP: Kejadian prioritas (aspirasi, permintaan data, form/polling wajib, pengingat tahap 6 jam, dan ringkasan harian 07.00 WIB) masuk ke antrean email_keluar dan diproses oleh /api/cron/email (maksimal 10 email/putaran, batas waktu 20 detik, jeda 30 menit saat terkena rate limit 421/451/452). Kode OTP aktivasi/ganti email dikirim langsung (kirimLangsung).
  • Impor (features/impor/): Mendukung pratinjau dan impor massal CSV/XLSX hingga 2.000 baris (maks. 3 MB) untuk Form (Draf, Arsip diimpor, Template), Polling (Draf, Arsip diimpor, Template), dan Aspirasi lama (khusus pengelola, diimpor = true), serta impor Data Serdik di Admin (maks. 1.000 baris, maks. 1 MB dengan proteksi zip bomb).
  • Zona Waktu: Semua timestamp disimpan di PostgreSQL sebagai TIMESTAMPTZ(3) (UTC) dan diformat/diinput dalam WIB (Asia/Jakarta, UTC+7) via src/lib/time.ts. Status efektif form/polling (DRAF, BELUM_DIBUKA, TERBUKA, DITUTUP) dihitung secara dinamis terhadap waktu saat dibaca.
  • Tampilan & PWA: Antarmuka mobile-first dengan BottomNav (5 tab termasuk tombol emas Suarakan atau Mode Kelola via cookie sv_mode) di layar < 1024px, dan Sidebar navy 264 px di desktop >= 1024px. Navigasi bawah otomatis disembunyikan saat mengisi form (body:has([data-isi-form])). Manifest PWA (src/app/manifest.ts) dan Service Worker (public/sw.js) menangani ikon dan klik Web Push (lihat desain-sistem.md).