RayLab-Core/Docs/Phase-03-Layered-Architecture.md

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:

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

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

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.