App & Routers

Inisialisasi server Elysia berisi konfigurasi plugin, middleware global, serta binding route. Di sinilah lifecycle request pertama kali dimulai. Route hanya bertugas memetakan HTTP method dan path ke handler yang sesuai. Di Elysia-Light, route dijaga tetap tipis dan tidak berisi logika bisnis.

Controller

Controller menjadi titik masuk utama untuk setiap request. Ia bertugas menerima input, melakukan validasi konteks, memanggil service yang relevan, dan menyusun response. Controller tidak menyimpan logika berat dan tidak berinteraksi langsung dengan database.

Controller Service

Controller service berisi logika bisnis yang spesifik terhadap use case endpoint. Service jenis ini hidup dekat dengan controller dan menangani alur bisnis, orchestration, serta keputusan proses tanpa mengetahui detail implementasi database.

Model

Model merepresentasikan struktur tabel, relasi database, serta akses data dasar. Model tidak mengetahui konteks request atau alur bisnis, dan hanya fokus pada representasi dan interaksi data.

Model Service

Model service berisi logika yang berkaitan langsung dengan data dan domain model. Service ini harus diregister pada model agar dapat dipanggil secara eksplisit dari controller. Dengan pemisahan ini, controller dapat membedakan mana service milik controller dan mana service milik model, serta menjaga batas tanggung jawab tetap jelas.

Cron

Cron digunakan untuk menjalankan proses terjadwal seperti sinkronisasi data, cleanup, reporting, atau scheduled business logic. Di Elysia-Light, cron dijalankan sebagai worker runtime terpisah sehingga eksekusinya tidak pernah mengganggu performa API utama.

Queue

Queue menangani proses asynchronous yang bersifat berat atau tidak perlu dijalankan secara real-time, seperti pengiriman email, notifikasi massal, proses antrean, atau processing logika berat. Dengan queue worker terisolasi, kegagalan atau antrean panjang tidak berdampak langsung pada request user.

Socket

Socket menangani kebutuhan real-time seperti notifikasi realtime, chat realtime, atau data streaming. Socket dijalankan sebagai service independen agar koneksi persistent dan scaling dapat dikontrol tanpa mempengaruhi HTTP server.

Database Migration

Migration digunakan untuk mengelola perubahan struktur database secara versioned dan terprediksi. Setiap perubahan skema dicatat sebagai source of truth, sehingga environment development, staging, dan production tetap konsisten.

Database Seeder

Seeder berfungsi untuk mengisi data awal atau data pendukung yang dibutuhkan sistem agar bisa berjalan dengan benar, seperti role, permission, atau konfigurasi default.

OLAP / Data Analytic Migration

OLAP / Data Analytic migration digunakan untuk kebutuhan data analitik dan reporting yang terpisah dari database transaksional. Dengan pemisahan ini, query berat untuk analisis tidak mengganggu performa sistem utama.

Email

Output email berisi template dan logic pengiriman email. Dengan pemisahan ini, perubahan format atau provider email tidak mempengaruhi core business logic.

Notifikasi

Notifikasi mencakup push notification, in-app notification, atau channel lain. Semua logic notifikasi ditempatkan terpusat agar konsisten dan mudah dikembangkan ke berbagai platform.

Jaga Route Tetap Tipis

Hindari menulis logika bisnis langsung di route. Gunakan controller dan service agar alur request mudah dipahami dan diuji.

Pisahkan Logika Bisnis

Semua proses penting sebaiknya berada di service. Dengan begitu, controller tetap bersih dan mudah dirawat.

Gunakan Middleware Secara Terukur

Middleware sangat kuat, tetapi jangan berlebihan. Gunakan hanya untuk kebutuhan lintas endpoint seperti auth, logging, dan validation.

Hindari Abstraksi Berlebihan

Elysia-Light mendorong abstraksi yang jelas dan eksplisit. Jika sebuah abstraction tidak menambah kejelasan, sebaiknya dihindari.

Konsisten Antar Modul

Gunakan struktur dan penamaan yang sama di setiap modul agar codebase mudah dipahami oleh seluruh tim.

Konsisten penamaan folder / file dengan prefix ketika sudah banyak.

Ketika jumlah modul dan file semakin besar, gunakan prefix atau grouping penamaan agar file mudah di-scan dan tidak membingungkan. Konsistensi penamaan lebih penting daripada singkat.

Jangan jadikan model sebagai tempat semua logic data

Model harus dijaga tetap tipis dan fokus pada representasi tabel, relasi, dan operasi data dasar. Jika membutuhkan logic data yang berat atau kompleks, simpan di model service. Model hanya memanggil service tersebut agar batas tanggung jawab tetap jelas dan mudah dirawat.

Aturan penggunaan migration

Migration dibagi menjadi dua jenis. Folder 0000_00 digunakan untuk migration tanpa versioning dan hanya dipakai pada fase awal development. Setelah sistem masuk production, semua migration wajib menggunakan folder versioning dengan format tahun_bulan. Di production, migration tanpa versioning tidak boleh digunakan.

Aturan penamaan tabel database

Penamaan tabel wajib menggunakan prefix berdasarkan nama modul atau tabel parent. Contoh: product, product_category,product_has_product_category, product_stock,product_stock_adjustment. Aturan ini menjaga keterbacaan skema dan mencegah konflik penamaan di database berskala besar.

Gunakan utility secara terukur

Utility tidak boleh diubah secara sembarangan. Perubahan utility berisiko mempengaruhi banyak bagian sistem. Elysia-Light menyediakan utility besar yang bersifat over-processing dan utility kecil yang ringan. Jika membutuhkan fleksibilitas tinggi atau performa maksimal, prioritaskan utility kecil daripada memodifikasi utility besar.

Aturan penggunaan blueprint

Jika blueprint masih dapat mengakomodasi kebutuhan fitur seperti CRUD dasar tanpa logika rumit, gunakan blueprint tanpa modifikasi kode. Jika blueprint mengakomodasi struktur dasarnya tetapi di dalamnya terdapat logika kompleks, generate dari blueprint lalu hapus marker blueprint dan sesuaikan kodenya. Jika blueprint sama sekali tidak mengakomodasi kebutuhan fitur, seperti transaksi non-CRUD atau alur bisnis kompleks, jangan gunakan blueprint.

Gunakan seeder untuk master dan data utama

Seeder wajib dibuat untuk mempermudah testing dan simulasi sistem. Selalu pisahkan seeder untuk data master dan data utama, dan sediakan beberapa variasi data agar proses development dan debugging lebih realistis.

Pindahkan logika berat ke queue

Jika sebuah API memiliki logika yang sangat berat, memakan waktu lama, atau tidak perlu dieksekusi secara synchronous, pindahkan logika tersebut ke queue agar request API tetap cepat dan stabil.

Jangan satukan instance app dengan jobs worker di production

Di environment production, API server dan jobs worker sebaiknya dijalankan sebagai proses terpisah. Hal ini menjaga stabilitas sistem, memudahkan scaling independen, dan mencegah failure pada worker menjatuhkan aplikasi utama.