D
Pendahuluan

Overview

Konco adalah platform manajemen sewa akun iklan Facebook (Facebook Ads Whitelist) yang terdiri dari dua repo — dazo-whitelist (web app + billing) dan dazo-whitelist-api (dedicated Meta Marketing API engine). Laravel 10 + Livewire + Reverb.

Konco adalah platform terpadu untuk mengelola layanan sewa akun iklan Facebook (Facebook Ads Whitelist Service). Sistem ini dirancang untuk agensi dan media buyer dalam mengelola inventaris Business Manager (BM), akun iklan, kampanye, alokasi spend cap, tagihan/invoice, sistem tiket real-time, hingga struktur tim multi-user dengan hak akses granular.

Konco terdiri dari dua repository yang beroperasi sebagai satu produk:

RepoPeranStack
dazo-whitelistWeb app / SaaS — Member Portal, Admin Portal, billing, invoicing, team, tickets, Livewire UILaravel 10 + Livewire 2.x + Bootstrap 4 + CoreUI 5 + Reverb (WebSocket)
dazo-whitelist-apiDedicated Meta Marketing API engine — Facebook OAuth token lifecycle, Graph API v20.0, import massal BM/Ad Accounts, mutasi spend capLaravel 10 + Passport + facebook/php-business-sdk ^20.0 + Queue

Arsitektur ekosistem

text
┌────────────────────────────────────────────────────────────────────────┐
│                        DAZO-WHITELIST (Konco Web)                       │
│                      Frontend Web App / SaaS (Port 8000)                 │
│                                                                        │
│   • Member Portal (Ad Manager, Invoices, Team, Tickets, Topup)         │
│   • Admin Portal (Stock BM/Ads, Approvals, Users, System Configs)      │
│   • Multi-Guard Auth (admin / web) + Google 2FA                        │
│   • Livewire 2.x + CoreUI/Bootstrap + Laravel Reverb (WebSockets)      │
│   • Payment Gateway (MonitPay) + Billing & Invoicing (dompdf/Excel)    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                         REST API via GuzzleHTTP
               (RSA 2048-bit Signature + Passport Bearer Token)
                                    │
┌───────────────────────────────────▼────────────────────────────────────┐
│                      DAZO-WHITELIST-API (Port 8081)                     │
│                   Dedicated Meta Marketing API Engine                   │
│                                                                        │
│   • Facebook OAuth Token Lifecycle & Refresh Automation                │
│   • Facebook Graph / Marketing API SDK (v20.0) Integration             │
│   • BM & Ad Account Chunked Importer (Background Queue Jobs)           │
│   • Meta Graph Mutations (Budget, Status ACTIVE/PAUSED)                │
│   • Spend Cap Topup / Deduct / Withdraw / Transfer Balance             │
│   • Batch Insights Fetching & Partnership Verification                 │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                         Meta Graph API (v20.0)
                                    │
                                    ▼
                         🌐 FACEBOOK / META SERVERS

Hubungan antar repo:

  1. Separation of Concerns — dazo-whitelist berfokus pada UX, business logic, billing, role management, invoicing; dazo-whitelist-api berfokus pada koneksi intensif ke Facebook Graph API, manajemen access token jangka panjang, sinkronisasi stok akun massal, dan mutasi budget/status kampanye.
  2. Koneksi terstandar — dazo-whitelist memanggil endpoint API via wrapper class App\Src\MyApi dan App\Src\FacebookApi. Autentikasi memadukan Passport OAuth2 Bearer Token dengan tanda tangan digital RSA SHA-256 (x-client-key, x-timestamp, x-signature). Sistem auto-refresh token 401 transparan — bila token kedaluwarsa, client otomatis minta token baru dan mengulang request.
  3. Verifikasi signature di controller, bukan middleware — RSA diverifikasi di dalam ApplicationController::token & check. Middleware myapi hanya memvalidasi kecocokan header public-key dengan public_key user terautentikasi.

Stack teknologi

dazo-whitelist (Web App)

LapisanTeknologi
BackendLaravel 10.x (PHP ^8.1)
Frontend engineLivewire 2.10, Alpine.js, Blade
UI kitCoreUI 5.x, Bootstrap 4.x, Sass, Vite
RealtimeLaravel Reverb, Laravel Echo, Pusher JS
RBACSpatie Laravel Permission 5.9
PaymentMonitPay integration, Duitku SDK (route nonaktif)
Exportbarryvdh/laravel-dompdf, maatwebsite/excel
Facebook SDK lokalfacebook/graph-sdk ^5.1 (wrapper; Graph v20.0 dilayer oleh API engine)
DatabasePostgreSQL (default) / MySQL
Live supportCrisp Chat SDK
2FApragmarx/google2fa-laravel

dazo-whitelist-api (Backend Engine)

LapisanTeknologi
BackendLaravel 10.x (PHP ^8.1)
Meta SDKfacebook/php-business-sdk ^20.0
API authLaravel Passport 12.3 + RSA Key Validation
API docsDedoc Scramble (dedoc/scramble ^0.11)
Background jobsLaravel Queue Worker, Database Queue
HTTP clientGuzzleHTTP ^7.2
DatabaseMySQL / MariaDB

Modul bisnis

ModulCakupan
Ads ManagerHierarki Campaigns → Ad Sets → Ads, kontrol status ACTIVE/PAUSED, adjust budget, insight performa
Stock BM & Ad AccountsImport massal dari Facebook Graph API, monitoring limit kredit, timezone, currency, status kesehatan
Order & SubscriptionSiklus langganan sewa akun — reminder H-7/H-3/H-1, grace period 4 hari, auto-deactivation
Spend Cap & BalanceTop up spend cap via payment gateway, transfer balance antar-akun, withdraw/refund
Admin Request ApprovalWorkflow persetujuan: akun baru, topup, transfer, withdraw, refund, rename, share pixel
Billing & InvoiceRiwayat transaksi, download invoice PDF
Team & PermissionMulti-user workspace, roles & permissions granular per tim
Ticketing & Live ChatTiket bantuan + live chat real-time via Reverb + Crisp widget
Coupon & DiscountVoucher potongan harga dengan kuota, masa berlaku, target member
Schedule & MonitorCron harian/mingguan: reminder expiry, sync kampanye, monitor Meta, sync MonitPay

Konsep inti

KonsepRingkasan
UUID Primary KeySeluruh tabel utama memakai UUIDv4 via trait App\Traits\UUID — mencegah ID enumeration attack
Multi-Guard AuthGuard admin (admin portal) + guard web (member portal), keduanya wajib 2FA
RSA Handshakedazo-whitelist sign payload dengan private key → dazo-whitelist-api verify dengan public key di tabel applications → terbitkan Passport token
Siklus LanggananEXPIRED_BEFORE=7 (reminder), EXPIRED_AFTER=4 (grace); command cron:ads-expired tiap menit
Token Refresh LoopMyApi::request tangkap 401 → panggil get_token() (sign + tukar) → simpan di tabel configs → retry request original
Service LayerBusiness logic di app/Services/ (OrderService, PaymentService, AdminRequestService, TeamService, PermissionService, MonitpayService); controllers tetap thin

Yang TIDAK boleh diubah tanpa koordinasi

AreaLokasi
Payload RSA signatureApp\Src\MyApi::get_token (client) ↔ ApplicationController::token (server) — `implode(’
Header handshakex-client-key, x-timestamp, x-signature, Authorization: Bearer
Passport token storageTabel configs (kolom api_token) di dazo-whitelist
Public key clientstorage/rsa_keys/public_key.pem (client) ↔ kolom public_key di tabel applications (server)
Meta Graph versionFACEBOOK_GRAPH_VERSION=v20.0 (di API engine)

Langkah berikutnya

  • Baru mulai? Baca Setup Environment — dua file .env dan RSA keys wajib disiapkan.
  • Sudah punya env? Lanjut ke Local Development — urutan starting kedua service.
  • Akan deploy? Wajib baca Deployment — branch produksi adalah production, self-hosted runner.
  • Engineer baru direkomendasikan baca Auth & Security sebelum menyentuh komunikasi antar-service.
  • Butuh detail endpoint API engine? Lihat API Reference.