# Email Management System ## Project Overview Email Management System adalah aplikasi web berbasis Node.js yang digunakan untuk mengelola akun email cPanel tanpa harus membuka halaman cPanel. Seluruh operasi dilakukan menggunakan cPanel UAPI melalui HTTPS. Aplikasi ini dirancang untuk mengelola puluhan ribu akun email dengan performa tinggi dan UI yang modern. Target Hosting: - Biznet Gio NEO Web Hosting - Node.js Application - cPanel UAPI - LiteSpeed --- # Technology Stack Backend - Node.js 22 LTS - Express.js Frontend - Bootstrap 5 - AdminLTE 3 View Engine - EJS Library - axios - dotenv - express-session - express-validator - multer - exceljs - bcrypt - helmet - compression - morgan - cookie-parser Database - SQLite Reason SQLite hanya digunakan untuk: - user login - role - audit log - application settings Seluruh data email tetap berasal dari cPanel API. --- # Project Goals Aplikasi ini harus menggantikan fungsi Email Account pada cPanel. User tidak perlu membuka cPanel lagi. Semua operasi dilakukan dari aplikasi ini. --- # Features ## Authentication - Login - Logout - Session Login - Remember Login Role - Super Admin - Admin - Operator --- ## Dashboard Menampilkan - Total Email - Total Storage - Used Storage - Free Storage Chart - Email Created Today - Email Created This Month Recent Activity --- ## Email Management ### List Email Features - Search - Pagination - Sort - Filter Columns - Email - Domain - Quota - Used - Status - Action --- ### Create Email Field Email Password Quota Domain Validation - Email tidak boleh duplicate - Password minimal 8 karakter Menggunakan Email::add_pop --- ### Delete Email Konfirmasi sebelum delete. Menggunakan Email::delete_pop --- ### Reset Password Menggunakan Email::passwd_pop --- ### Change Quota Menggunakan Email::edit_pop_quota --- ### Detail Email Menampilkan Email Quota Usage Created --- # Bulk Import Upload Excel Format email,password,quota Contoh bayu,Password123,2048 abi,Password123,1024 Progress Bar Success Failed Retry --- # Export Excel Export seluruh akun email. --- # Activity Log Simpan Tanggal User IP Action Status Description --- # Settings Konfigurasi cPanel URL Username API Token Default Domain Default Quota --- # cPanel API Semua request menggunakan UAPI. List Email /execute/Email/list_pops Create /execute/Email/add_pop Delete /execute/Email/delete_pop Password /execute/Email/passwd_pop Quota /execute/Email/edit_pop_quota Gunakan Authorization Header cpanel USERNAME:APITOKEN Semua endpoint dibungkus dalam service layer. Jangan memanggil axios langsung dari controller. --- # Folder Structure ``` email-manager/ │ ├── app.js ├── package.json ├── .env.example ├── README.md │ ├── config/ │ app.js │ database.js │ cpanel.js │ ├── routes/ │ auth.js │ dashboard.js │ email.js │ setting.js │ ├── controllers/ │ authController.js │ dashboardController.js │ emailController.js │ settingController.js │ ├── services/ │ cpanelService.js │ ├── middleware/ │ auth.js │ role.js │ ├── models/ │ User.js │ Log.js │ Setting.js │ ├── views/ │ auth/ │ dashboard/ │ email/ │ setting/ │ ├── public/ │ css/ │ js/ │ img/ │ ├── uploads/ ├── logs/ └── database/ app.db ``` --- # MVC Rules Gunakan MVC. Controller Tidak boleh berisi query database. Controller hanya menerima request. Semua business logic berada pada service. Database hanya boleh diakses dari model. --- # Coding Style Gunakan async/await Jangan gunakan callback. Gunakan ES Module. Semua function diberi komentar JSDoc. Gunakan try/catch. Gunakan logger. Tidak boleh ada duplicate code. --- # UI Rules Responsive Bootstrap 5 AdminLTE Sidebar Navbar Dark Mode Loading Spinner Toast Notification SweetAlert2 Progress Bar --- # Security Gunakan Helmet CSRF Session Rate Limit Input Validation XSS Protection Password Hash Environment Variable Jangan pernah hardcode API Token. --- # Performance Support 50.000+ akun email Search < 1 detik Pagination Server Side Compression Cache Lazy Load --- # Future Features - Bulk Reset Password - Bulk Delete - Multi Domain - API Token Management - Webhook - Email Usage Report - Email Activity Dashboard - Scheduler - Backup Settings --- # Installation npm install --ignore-scripts (`--ignore-scripts` avoids a third-party dependency's own broken `postinstall` script; see "Deployment ke cPanel" below for why this matters on shared hosting too, not just locally.) Copy .env.example menjadi .env Isi konfigurasi CPANEL_URL= CPANEL_USERNAME= CPANEL_APITOKEN= DOMAIN= PORT=3000 Salin aset front-end (Bootstrap/AdminLTE/Chart.js/SweetAlert2/Font Awesome) ke `public/vendor/` npm run assets Buat skema database + akun Super Admin pertama (opsional — `app.js` juga melakukan ini otomatis saat start) npm run migrate && npm run seed Atau jalankan keempat langkah di atas sekaligus dengan npm run setup Jalankan npm start --- # Development Rules For Claude Claude harus menghasilkan project production-ready. Semua source code harus clean. Semua route harus dipisahkan. Semua controller dipisahkan. Semua service dipisahkan. Semua model dipisahkan. Semua view dipisahkan. Jangan membuat project monolithic. Gunakan arsitektur MVC. Gunakan reusable component. Seluruh komunikasi dengan cPanel harus melalui service layer. Semua response menggunakan JSON untuk endpoint API. Semua halaman menggunakan Bootstrap 5 + AdminLTE. Code harus mudah dikembangkan menjadi SaaS di masa depan. Jangan menghasilkan placeholder atau TODO. Semua fitur yang didefinisikan pada README harus diimplementasikan sepenuhnya. --- # Deployment ke cPanel Ya, project ini bisa langsung di-deploy ke cPanel yang menyediakan fitur **"Setup Node.js App"** (Node.js Selector, berbasis Passenger + LiteSpeed) — seperti Biznet Gio NEO Web Hosting yang disebut di awal dokumen ini. Build lokal dan hasil akhir di cPanel menjalankan source code yang sama persis; yang membedakan hanyalah beberapa folder yang sengaja di-generate ulang di server (lihat "Yang TIDAK perlu ikut dipindahkan" di bawah), bukan dikirim dari komputer lokal. ## Persyaratan di cPanel 1. Fitur **Setup Node.js App** aktif, dengan **Node.js 22 LTS (atau lebih baru)** tersedia di selector. 2. Akses **Terminal** cPanel (biasanya tersedia walau tanpa SSH penuh) — dibutuhkan untuk menjalankan perintah `npm run setup` sekali di awal. 3. **cPanel API Token** dari akun cPanel yang akan dikelola emailnya: *Security → Manage API Tokens → Create*. Token inilah yang diisi ke `CPANEL_APITOKEN`. 4. Domain/subdomain untuk mengakses aplikasi, misalnya `mail-admin.domainanda.com`. ## Langkah-langkah 1. **Upload source code** ke server — via Git Version Control cPanel, upload ZIP + extract di File Manager, atau `git clone`/`rsync` lewat Terminal. Yang perlu diupload hanyalah source code (lihat daftar exclude di `.gitignore`); folder `node_modules/`, `public/vendor/`, dan `database/*.db` tidak perlu ikut. 2. Buka **Setup Node.js App → Create Application**: - Node.js version: 22.x (paling baru yang tersedia) - Application mode: `Production` - Application root: folder tempat source code diupload - Application URL: subdomain/path yang diinginkan - Application startup file: `app.js` 3. Klik **Create**. Salin `.env.example` menjadi `.env` di Application root, isi semua variabel — terutama `CPANEL_URL`, `CPANEL_USERNAME`, `CPANEL_APITOKEN`, `DOMAIN`, `SESSION_SECRET`, `APP_ENCRYPTION_KEY` (generate dengan `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`), serta `ADMIN_EMAIL`/`ADMIN_PASSWORD` untuk akun Super Admin pertama. Pastikan `CPANEL_MOCK=false` di server produksi. 4. Buka halaman Setup Node.js App tersebut, salin perintah **"Enter to the virtual environment"** yang ditampilkan cPanel, jalankan di Terminal, lalu masuk ke folder aplikasi dan jalankan: ``` npm run setup ``` Perintah ini menjalankan `npm install --ignore-scripts` (menghindari script `postinstall` milik dependency pihak ketiga yang kadang gagal di shared hosting), lalu menyalin aset Bootstrap/AdminLTE/Chart.js/SweetAlert2/Font Awesome ke `public/vendor/`, lalu migrasi database dan pembuatan akun Super Admin pertama. Catatan: `app.js` sendiri sudah otomatis menjalankan migrasi skema & bootstrap Super Admin pertama setiap kali start (aman dijalankan berulang), tapi langkah penyalinan aset front-end **harus** dilakukan manual sekali karena tidak dijalankan otomatis saat start. 5. Pastikan folder `database/`, `logs/`, dan `uploads/` dapat ditulis oleh user aplikasi (umumnya otomatis, karena kepemilikan file mengikuti akun cPanel Anda). 6. Klik **Restart** pada halaman Setup Node.js App. 7. Akses Application URL, login dengan `ADMIN_EMAIL`/`ADMIN_PASSWORD` dari `.env`, lalu segera buat user Super Admin baru dengan password sendiri di menu Manajemen User dan ganti/nonaktifkan akun default tersebut. ## Yang TIDAK perlu ikut dipindahkan dari local - `node_modules/` — install ulang di server via `npm run setup`. Jangan copy dari komputer lokal (risiko ketidakcocokan platform/arsitektur). - `public/vendor/` — dihasilkan ulang oleh `npm run assets` (bagian dari `npm run setup`), bukan disalin manual. - `database/*.db` — biarkan kosong, akan otomatis dibuat + diisi akun Super Admin pertama saat aplikasi pertama kali start di server. Data uji coba di local tidak relevan untuk production. - `.env` — jangan pernah commit/upload file `.env` yang sama dengan local; isi ulang dengan kredensial cPanel & secret yang sesungguhnya untuk server tersebut. ## Catatan tambahan - Progress bar Bulk Import menggunakan polling HTTP biasa (bukan streaming/SSE), sehingga tetap kompatibel dengan reverse proxy LiteSpeed yang membuffer response. - Jika hosting membatasi modul native Node.js, aplikasi ini sudah didesain untuk tidak butuh satupun (SQLite pakai modul bawaan `node:sqlite`, hashing password pakai `bcryptjs` murni JavaScript) — lihat `docs/architecture.md` untuk detail keputusan teknis ini.