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.
1. Konteks Sistem (C4 Level 1 & 2)
Section titled “1. Konteks Sistem (C4 Level 1 & 2)”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
2. Tech Stack
Section titled “2. Tech Stack”| 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) |
3. Struktur Folder & Pemetaan 15 Domain
Section titled “3. Struktur Folder & Pemetaan 15 Domain”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-demoscripts/ deploy-vps.sh, setup.ts, test-db.sh, buat-contoh-impor.ts, buat-contoh-unduhan.tstests/ unit/ (35), integration/ (60), e2e/ (21), helpers/, fixtures/4. Arsitektur Berlapis dan Alur Request
Section titled “4. Arsitektur Berlapis dan Alur Request”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
- Proxy (
src/proxy.ts): Hanya menyalinpathname + searchke header permintaanx-pathnameagar server guards dapat membentuk URL/masuk?next=<path>. Tidak ada logika autentikasi di proxy; seluruh pemeriksaan akses terjadi di server. - Route & Layout (
src/app/): Komponen server membaca parameter, memanggilrequireUser()ataurequireIzin(fitur)di layout dan page, lalu memanggil fungsi baca di service. - 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 melakukanrevalidatePath/refresh/redirect. - Service (
src/features/*): Memegang seluruh aturan bisnis, membaca ulang peran aktif dari database pada setiap mutasi, menjalankan validasi Zod, dan mengembalikan tipeResult<T>(ok(data)ataufail(code, message, fields)) alih-alih melempar exception untuk kondisi bisnis wajar. Kode galat baku meliputiFORBIDDEN,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”5.1 Autentikasi & Sesi
Section titled “5.1 Autentikasi & Sesi”- 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 httpOnlysv_session, sementara di tabelsessionshanya 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 pembaruanlastSeenAtminimal 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 darix-real-ip(diisi Traefik dari koneksi TCP), lalu jatuh ke entri paling kananx-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:- Google OAuth 2.0 / OIDC + PKCE:
/api/auth/google/startmenyimpanstate,nonce, dan PKCEverifierdi cookiesv_oauth(httpOnly, 10 menit, path/api/auth/google). Callback menukarcodekeoauth2.googleapis.com/tokenvia TLS, memverifikasi klaimiss,aud,nonce,exp, danemail_verified, lalu memanggilaktivasiGoogle(). - Kode Email 6 Digit: Mengirim OTP 6 digit (
kode_email, hash SHA-256userId: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 denganmustChangePin = trueyang wajib melewati/ganti-pin.
- Google OAuth 2.0 / OIDC + PKCE:
- Mode Uji (
DEV_LOGIN=true): Memungkinkan penggantian akun dari header. Dinonaktifkan secara mutlak jikaAPP_ENV=production,VERCEL_ENV=production, atau jikaDATABASE_URLmengarah kePRODUCTION_DB_HOST. - Asal Publik & Keamanan Redirect:
asalPermintaan()membacax-forwarded-hostdanx-forwarded-protoagar callback OAuth, same-origin check Web Push, dan redirectPOST /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
peranmenyimpan peran sistem (kode = "ADMIN"dankode = "LEMUSDIK", tidak dapat dinonaktifkan) serta peran dinamis lain yang dikelola Admin dengan empat flag izin:izinForm,izinPolling,izinDataUser, danizinHackathon(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, danhackathon. - Penjagaan Dua Lapis:
- Layout guard (
requireIzin/requireAdmin) mengembalikan halaman 403 (src/app/forbidden.tsx) untuk rute tanpa izin. - Service guard membaca ulang
muatPeran(actorId)langsung dari database pada setiap aksi sehingga pencabutan atau penonaktifan peran berlaku seketika.
- Layout guard (
- 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 dibalasNOT_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 memakaiSELECT id FROM public.forms|polls WHERE id = $1::uuid FOR UPDATEsebelum memperbarui atau menghitung jawaban. Sebaliknya, pengiriman jawaban (submitForm), penandaan tautan luar (tandaiSelesai,batalkanTanda), dan pemungutan suara (pilih,batalPilih) mengambilFOR SHARElalu 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
anonimpada polling terkunci sejak statusTERBIT. - Hackathon (
hackathon/kelola.ts,tim.ts,nilai.ts): Perpindahan tahap panitia mengambilFOR UPDATEpada barishackathons; pembentukan/perubahan tim mengambilFOR SHAREpadahackathonsdanFOR UPDATEpadahackathon_tim; pemberian bintang dan nilai juri mengambilFOR SHAREpadahackathons. - Aspirasi (
aspirasi/lemusdik.ts): Perubahan status memakai optimistic concurrency control (updateManydenganwhere: { 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 menggunakanpg_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 dataDAT-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):- Lonceng in-app: Dicatat di
notificationsdalam transaksi bisnis yang sama. - Web Push: Dijadwalkan via
after()setelah respons dikirim, membaca ulang baris notifikasi peridagar transaksi yang rollback tidak pernah terkirim. Langganan perangkat dipindah ke akun yang sedang login dan dihapus dari perangkat saatPOST /keluar. - Email SMTP: Kejadian prioritas (aspirasi, permintaan data, form/polling wajib, pengingat tahap 6 jam, dan ringkasan harian 07.00 WIB) masuk ke antrean
email_keluardan 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).
- Lonceng in-app: Dicatat di
- Impor (
features/impor/): Mendukung pratinjau dan impor massal CSV/XLSX hingga 2.000 baris (maks. 3 MB) untuk Form (Draf, Arsipdiimpor, Template), Polling (Draf, Arsipdiimpor, 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) viasrc/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 cookiesv_mode) di layar< 1024px, danSidebarnavy 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).