# 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.