# Technical Architecture Document (TAD): IdeaBiz Guest Engagement Platform **Versi:** 1.0 **Status:** Approved **Author:** Mubaroki & Re-Write by Diana (AI) **Organisasi:** GMEDIA - PT Media Sarana Data --- ## 1. Arsitektur "Hub and Spoke" Platform ini mengadopsi model arsitektur "Hub and Spoke" terdistribusi untuk menjamin isolasi data klien enterprise (hospitality), kepatuhan terhadap regulasi privasi data lokal, serta efisiensi manajemen operasional terpusat dari GMEDIA. ``` +---------------------------------------+ | GMEDIA Central Cloud (HUB) | | - ideabiz-gep-hub-api (Laravel 12) | | - Central Licensing & Quota Engine | | - AI/LLM Proxy (9router.gmedia.dev) | | - Super Admin Dashboard (Vite SPA) | +-------------------+-------------------+ | +-------------------+-------------------+ | mTLS / Encrypted Heartbeat | v v +--------------------------+ +--------------------------+ | Client Node A (Shared) | | Client Node B (Dedicated)| | - Spoke API (Laravel 12) | | - Spoke API (Laravel 12) | | - DB PostgreSQL 16 | | - Dedicated DB PG 16 | | - Redis + Reverb Worker | | - Redis + Reverb Worker | | - Tenant Dashboard (SPA) | | - Tenant Dashboard (SPA) | | - Guest Portal Web (SPA) | | - Guest Portal Web (SPA) | +--------------------------+ +--------------------------+ ``` ### 1.1. The Hub (Infrastruktur Pusat GMEDIA) Infrastruktur terpusat yang dioperasikan pada Data Center GMEDIA (Yogyakarta & Jakarta): 1. **Hub API (`ideabiz-gep-hub-api`):** Layanan backend inti (Laravel 12) untuk manajemen workspace enterprise, pendaftaran lisensi, pemantauan status node (heartbeat), agregasi audit log terpusat, dan penagihan kuota token/kredit AI. 2. **Super Admin Dashboard (`ideabiz-gep-super-admin-dashboard`):** Dashboard berbasis web untuk tim NOC, Operasional, Support, dan Finance GMEDIA guna mengelola seluruh ekosistem klien, alokasi domain kustom, serta telemetri node. 3. **AI & LLM Gateway Proxy:** Gateway terpusat (`https://9router.gmedia.dev/v1`) yang bertugas mengarahkan kueri percakapan tamu, mengontrol batas pemakaian token (*Soft Limit* di 80%, *Hard Limit* di 100%), serta melakukan sensor awal PII sebelum diteruskan ke model LLM. 4. **Data Aggregator & Ingestion Warehouse:** Mengagregasi data telemetri operasional non-PII untuk pelaporan benchmark industri perhotelan dan optimasi respons asisten virtual. ### 1.2. The Spoke (Node Properti / Klien Tenant) Setiap properti hotel atau entitas bisnis berjalan sebagai Spoke yang terisolasi: 1. **Spoke API (`ideabiz-gep-api`):** Layanan backend inti (Laravel 12) yang mengelola seluruh logika bisnis lokal properti, mencakup katalog layanan, alur kerja (workflow) departemen, penugasan staf, sesi tamu kamar, serta penyimpanan data operasional. 2. **Tenant Dashboard (`ideabiz-gep-tenant-dashboard`):** Dashboard web khusus bagi klien/pelanggan properti (General Manager, Admin Properti, dan Kepala Departemen F&B, Housekeeping, Front Office, Engineering). 3. **Guest Portal Web (`ideabiz-gep-guest-portal`):** Antarmuka web ramah-mobile (PWA-ready) yang diakses tamu melalui pemindaian kode QR di kamar tanpa perlu menginstal aplikasi native. 4. **Mobile App (`ideabiz-gep-mobile-app`):** Aplikasi mobile terpadu berbasis React Native dengan antarmuka adaptif sesuai peran (Guest Mode vs Staff Task Execution Mode). ### 1.3. Mekanisme Heartbeat & Graceful Degradation Setiap Spoke wajib mengirimkan sinyal status (*Heartbeat*) ke Hub API setiap 60 detik. Data yang dikirim mencakup: - Identitas Workspace (`workspace_id` dan CID). - Jumlah transaksi dan kueri AI yang dieksekusi. - Status kesehatan kontainer aplikasi, basis data, dan antrean worker. Jika koneksi Spoke ke Hub terputus lebih dari 15 menit: - Fitur lokal (pemesanan via katalog reguler, penugasan staf via Reverb WebSocket) tetap berjalan normal (*High Availability*). - Fitur AI Concierge dialihkan ke fallback statis (katalog pencarian berbasis teks lokal) guna mencegah kueri tak tervalidasi. --- ## 2. Multi-Domain, SSL, & Custom Branding Gateway Sistem menggunakan Reverse Proxy Nginx / Caddy berkinerja tinggi sebagai gateway masuk: 1. **Host Header Routing:** Memetakan domain atau subdomain yang masuk (misal: `guest.royalambarrukmo.com` atau `royal-ambarrukmo.ideabiz.co.id`) ke `workspace_id` terkait. 2. **Automated SSL Lifecycle:** Penerbitan dan pembaruan sertifikat SSL/TLS secara otomatis melalui Let's Encrypt dengan enkripsi minimum TLS 1.3. 3. **Tenant Theme Bootstrap:** Reverse proxy mengarahkan request aplikasi web ke build statis SPA yang kemudian memuat konfigurasi visual properti (logo, warna primer, favicon) saat inisialisasi awal. --- ## 3. Spesifikasi Tech Stack Standar Mengikuti standar baku arsitektur web aplikasi IdeaBiz (`https://ideabiz.co.id/docs/arsitektur-sistem/ideabiz-app.html`), seluruh antarmuka web menggunakan pola **Client-Side Static SPA (Single Page Application)** berkinerja tinggi yang disajikan melalui kontainer web server Nginx: | Komponen Sistem | Teknologi Terpilih | Versi / Standar | Rationale Arsitektur | | :--- | :--- | :--- | :--- | | **Frontend Framework (Web)** | React + Vite | React 19 / Vite 8 (rolldown) / TypeScript 6 | Performa build instan, footprint memori minimal, kompatibilitas komponen ekosistem IdeaBiz. TypeScript 7 (compiler native) menyusul setelah didukung typescript-eslint. | | **State & Data Fetching** | TanStack Query | v5 (React Query) | Manajemen cache asinkron otomatis, deduping request, optimistic UI update. | | **Routing Web SPA** | TanStack Router | v1 | Type-safe route parameters, search params validation, seamless code-splitting. | | **UI Design System** | Tailwind CSS + shadcn/ui | Tailwind v4 (CSS-first `@theme`) / shadcn/ui 4 (Radix UI) | Keselarasan 100% dengan Figma IdeaBiz Token, aksesibilitas W3C/WCAG AA, modular tanpa dependensi runtime berat. Baseline browser Tailwind 4: iOS Safari 16.4+, Chrome 111+, Firefox 128+. | | **Iconography** | Remix Icon | v4.9 (CSS, self-hosted) | Konsistensi visual ikonografi seluruh dashboard GMEDIA IdeaBiz. Font Plus Jakarta Sans juga di-*self-host* (@fontsource) untuk FCP. | | **Package Manager & Runtime** | pnpm / Node.js | pnpm 10 / Node 22 LTS | Lockfile deterministik, instalasi cepat, satu versi runtime di CI dan VM. | | **Pengujian Frontend** | Vitest + Testing Library + MSW + Playwright | Vitest 5 / MSW 2 / Playwright 1.63 | Unit & komponen (jsdom), handler mock per API Card, E2E alur emas (docs/16). | | **Mode Mock (Sandbox Demo)** | MSW di browser | `VITE_API_MODE=mock` | Build demo berjalan tanpa backend (docs/12 ยง3); mode `live` memanggil Spoke API. | | **Form & Validation** | React Hook Form + Zod | Latest Stable | Validasi tipe data ketat pada sisi klien sebelum payload dikirimkan ke REST API. | | **Visualisasi Data** | Chart.js & Recharts | Latest Stable | Grafik performa staf, tren pesanan tamu, dan telemetri pemakaian kuota token. | | **Mobile Application** | React Native | Expo / RN 0.74+ | Single codebase untuk Android & iOS, antarmuka adaptif berbasis otentikasi peran (Guest vs Staff). | | **Backend Core (Hub & Spoke)** | Laravel Framework | Laravel 12 (Latest Stable) / PHP 8.4-FPM | Kemampuan tim rekayasa GMEDIA, ekosistem Eloquent ORM matang, arsitektur Ponytail zero-bloat. | | **Basis Data Utama** | PostgreSQL | PostgreSQL 16 | JSONB indexing untuk fleksibilitas konfigurasi hotel, integritas relasional ACID yang kokoh. | | **Cache & Message Broker** | Redis | Redis 7.2 (Alpine) | Session store berkecepatan tinggi, caching katalog layanan, dan antrean job worker. | | **Real-time WebSockets** | Laravel Reverb | Latest Stable | Notifikasi push instan tugas staf dan pembaruan status pesanan tamu dengan latensi < 100ms. | | **Container Engine** | Podman / Docker | Rootless Podman (Debian 13) | Isolasi lingkungan aman pada Data Center GMEDIA maupun VM dedicated klien. | --- ## 4. Design System & Brand Token SSoT Antarmuka web manajemen mengadopsi token desain Figma IdeaBiz (Node 301-3792): - **Font Utama:** `Plus Jakarta Sans` (Google Fonts) - **Primary Brand Color:** `#0B5AA3` (United Nation Blue) | Tint 10: `#F3F8FF` | Dark Shade: `#084377` - **Secondary / Accent Color:** `#EEA25A` (Sandy Brown) | Tint 10: `#FDF0E3` - **Neutral / Text Color:** `#1E1E1D` (Eerie Black) | Muted Text: `#767676` / `#878787` | Background: `#FAFAFA` - **Highlight / Cyan Accent:** `#02B5EE` (Cyan) | Soft Blue: `#EFF6FF` - **Border & Separator:** `#EDEDED` ### Arsitektur Whitelabel pada Sisi Pelanggan (Guest Portal & App) 1. **Dasar Komponen:** Seluruh markup struktur, grid, tombol, form, dan modal menggunakan komponen shadcn/ui standar IdeaBiz. 2. **Dynamic CSS Variables Injection:** Pada saat bootstrap, Guest Portal memanggil konfigurasi tema dari Spoke API (`GET /api/v1/workspace/theme`). Nilai konfigurasi diterapkan secara langsung ke root CSS: ```css :root { --brand-primary: #8B0000; /* Warna primer custom hotel */ --brand-primary-fg: #FFFFFF; --brand-secondary: #DAA520; /* Warna sekunder custom hotel */ --brand-accent: #F5DEB3; --brand-radius: 0.5rem; } ``` 3. **Fallback Graceful:** Jika properti tidak menetapkan warna kustom, sistem secara otomatis kembali ke palet warna default IdeaBiz (`#0B5AA3` dan `#EEA25A`). 4. **Identitas Manajemen Terkunci:** Tenant Dashboard (Klien Hotel) dan Super Admin Dashboard (GMEDIA) **tidak di-whitelabel** dan wajib selalu menampilkan identitas resmi IdeaBiz GMEDIA. --- ## 5. Integrasi RAG, AI Credits, & Fallback Resilience 1. **RAG Gateway:** Backend Spoke berkomunikasi dengan `ideabiz-rag-for-assistant` via REST API terenkripsi. 2. **Konversi Kuota AI Credits:** Penggunaan LLM dihitung dalam satuan *AI Credits* untuk menyederhanakan perhitungan bagi manajemen hotel (contoh: 1 kredit untuk FAQ dasar; 3 kredit untuk pemesanan kamar/eksekusi pesanan kompleks). 3. **Tingkat Kuota & Notifikasi:** - 80% Kuota Terpakai: Notifikasi peringatan terkirim via email ke admin properti dan dashboard banner. - 100% Kuota Terpakai: Sistem mengaktifkan *Limited Mode* (fitur AI proaktif dinonaktifkan, dialihkan ke pencarian katalog statis tanpa menyebabkan kegagalan layanan bagi tamu). --- ## 6. Workflow State Machine Alur tugas operasional dari permintaan tamu hingga penyelesaian oleh staf: ``` [Tamu: Pesan Layanan] | v [Status: PENDING] -----> (Auto-mapping via Service Category & Department) | v [Status: ASSIGNED] ----> (Push WebSocket via Reverb ke Tablet/HP Staf) | +-----> [Staf Klik "Accept"] | | | v | [Status: IN_PROGRESS] ---> (Tamu menerima update real-time) | | | v +-----> [Staf Klik "Done"] | v [Status: DONE] ----------> (Notifikasi selesai ke tamu + Rating) ``` --- ## 7. Keamanan & Otentikasi 1. **Tamu (Guest):** Menggunakan otentikasi *Passwordless Session Token* berbasis nomor kamar / kode reservasi dan nama belakang, dengan masa kedaluwarsa otomatis sesuai tanggal checkout. 2. **Tenant / Klien Properti (Admin Utama & Staf):** Menggunakan otentikasi **Passwordless Magic-Link** yang dikirimkan ke email terdaftar. - **Admin Utama Properti:** Alamat email Admin Utama (Primary Admin) diset dan dikonfigurasi langsung oleh GMEDIA melalui **Super Admin Dashboard** saat proses onboarding hotel. - **Undangan Staf:** Admin Utama yang telah terautentikasi dapat mengundang staf atau manajer departemen melalui dashboard, yang akan menerima email aktivasi berisikan magic-link aman. - Sesi terautentikasi menerbitkan token JWT berjangka pendek (15 menit) dengan refresh token HttpOnly dan hak akses RBAC departemen. 3. **Super Admin GMEDIA:** - Wajib menggunakan **Microsoft 365 / Entra ID (Azure AD) SSO dengan Two-Factor Authentication (2FA / MFA)** terbatas hanya untuk akun internal domain resmi `@gmedia.id`. - **Environment-Level Authorization Whitelist (`.env` Guard):** Setelah berhasil melewati validasi Microsoft 2FA, sistem Hub API memvalidasi email pengguna terhadap daftar whitelist pada variabel lingkungan: `SUPERADMIN_ALLOWED_EMAILS=akhmad.mubaroki@gmedia.id,another.admin@gmedia.id` - Jika email `@gmedia.id` tidak terdaftar dalam variabel `.env` tersebut, akses ditolak secara mutlak dengan kode HTTP 403 Forbidden. Penambahan admin internal baru dilakukan dengan menambahkan alamat email ke file `.env` tanpa migrasi database. 4. **Isolasi Data:** Pemisahan mutlak di level schema/database PostgreSQL pada dedicated node, serta enforcement `workspace_id` global scope pada shared node. 5. **Kepatuhan Privasi:** Mengikuti ketentuan UU No. 27 Tahun 2022 (UU PDP). Log chat yang mengandung identitas pribadi otomatis dianonimkan 30 hari pasca checkout.