Init

2026-07-30 09:41:42 +07:00
parent aef8e412a8
commit 3efac50f39
70 changed files with 3217 additions and 0 deletions
@@ -0,0 +1,237 @@
+# RayLab Core Phase 3 --- Layered Architecture
+
+## Tujuan
+
+Fase 3 menetapkan standar arsitektur kode RayLab Core agar seluruh modul
+memiliki pola implementasi yang konsisten, mudah dipelihara, mudah
+diuji, dan mudah dikembangkan.
+
+------------------------------------------------------------------------
+
+# Filosofi
+
+Setiap request mengikuti alur yang sama:
+
+``` text
+HTTP Request
+      │
+      ▼
+Controller
+      │
+      ▼
+Application Service
+      │
+      ▼
+Domain Service
+      │
+      ▼
+Repository
+      │
+      ▼
+Database
+```
+
+Setiap layer hanya boleh berinteraksi dengan layer yang berada tepat di
+bawahnya.
+
+------------------------------------------------------------------------
+
+# Layer 1 --- Controller
+
+Tanggung jawab:
+
+-   Menerima HTTP Request
+-   Validasi dasar
+-   Memanggil Application Service
+-   Mengembalikan HTTP Response
+
+Tidak boleh:
+
+-   Mengakses database
+-   Menyimpan business logic
+-   Memanggil layanan eksternal secara langsung
+
+------------------------------------------------------------------------
+
+# Layer 2 --- Application Service
+
+Application Service mengimplementasikan use case.
+
+Contoh:
+
+-   Create User
+-   Update User
+-   Delete User
+-   Assign Group
+-   Grant Special Access
+-   Create Domain
+
+Tanggung jawab:
+
+-   Mengatur alur bisnis
+-   Mengoordinasikan Domain Service, Repository, dan Adapter
+-   Menjalankan transaksi bila diperlukan
+
+------------------------------------------------------------------------
+
+# Layer 3 --- Domain Service
+
+Seluruh aturan bisnis ditempatkan di layer ini.
+
+Contoh:
+
+-   Owner tidak boleh dihapus
+-   Group default tidak boleh dihapus
+-   Validasi Domain Access
+-   Validasi Permission
+-   Validasi Resource Access
+
+Business rule tidak boleh berada di Controller.
+
+------------------------------------------------------------------------
+
+# Layer 4 --- Repository
+
+Repository bertanggung jawab terhadap akses data.
+
+Fungsi utama:
+
+-   Save
+-   Find
+-   Update
+-   Delete
+-   Query
+
+Repository tidak mengetahui HTTP maupun business logic.
+
+------------------------------------------------------------------------
+
+# Layer 5 --- Database
+
+Menggunakan PostgreSQL dengan Prisma sebagai ORM.
+
+Seluruh akses database dilakukan melalui Repository.
+
+------------------------------------------------------------------------
+
+# Adapter Layer
+
+Integrasi dengan layanan eksternal dilakukan melalui Adapter.
+
+Contoh:
+
+-   Nextcloud Adapter
+-   Jellyfin Adapter
+-   Immich Adapter
+-   Minecraft Adapter
+
+Application Service tidak boleh memanggil API eksternal secara langsung.
+
+------------------------------------------------------------------------
+
+# Contoh Alur Create User
+
+``` text
+POST /users
+      │
+      ▼
+UsersController
+      │
+      ▼
+CreateUserService
+      │
+      ├─────────────┐
+      ▼             ▼
+UserDomain     GroupDomain
+      │
+      ▼
+UserRepository
+      │
+      ▼
+PostgreSQL
+      │
+      ▼
+Media Adapter
+      │
+      ▼
+Audit Service
+      │
+      ▼
+HTTP Response
+```
+
+------------------------------------------------------------------------
+
+# Dependency Rule
+
+  Layer                 Boleh Memanggil
+  --------------------- -------------------------------------
+  Controller            Application Service
+  Application Service   Domain Service, Repository, Adapter
+  Domain Service        Entity
+  Repository            Prisma
+  Adapter               External API
+  Entity                Tidak memanggil layer lain
+
+Dependensi selalu mengarah ke bawah.
+
+------------------------------------------------------------------------
+
+# Struktur Folder
+
+``` text
+src/
+│
+├── modules/
+│   ├── users/
+│   │   ├── controllers/
+│   │   ├── services/
+│   │   ├── domain/
+│   │   ├── repositories/
+│   │   ├── dto/
+│   │   ├── entities/
+│   │   └── users.module.ts
+│   │
+│   ├── groups/
+│   ├── authorization/
+│   ├── registry/
+│   ├── media/
+│   ├── storage/
+│   └── audit/
+│
+├── adapters/
+│   ├── nextcloud/
+│   ├── jellyfin/
+│   ├── immich/
+│   └── ...
+│
+├── common/
+│   ├── auth/
+│   ├── guards/
+│   ├── filters/
+│   ├── middleware/
+│   ├── logger/
+│   └── utils/
+│
+├── prisma/
+└── main.ts
+```
+
+------------------------------------------------------------------------
+
+# Aturan Implementasi
+
+1.  Business logic tidak boleh berada di Controller.
+2.  Frontend tidak boleh menyimpan business logic.
+3.  Integrasi eksternal wajib melalui Adapter.
+4.  Semua akses database melalui Repository.
+5.  Setiap modul harus dapat diuji secara mandiri.
+6.  Setiap layer memiliki satu tanggung jawab utama.
+
+------------------------------------------------------------------------
+
+# Hasil Akhir Fase 3
+
+Setelah fase ini selesai, RayLab Core memiliki standar implementasi yang
+konsisten untuk seluruh modul sehingga pengembangan jangka panjang
+menjadi lebih mudah, terstruktur, dan mudah dipelihara.