Init
This commit is contained in:
Mr. Rayyan
@@ -0,0 +1,208 @@
|
||||
# RayLab Core Phase 1 --- Module Design
|
||||
|
||||
## Tujuan
|
||||
|
||||
Fase 1 mendefinisikan pembagian modul pada RayLab Core. Setiap modul
|
||||
memiliki tanggung jawab yang jelas (Single Responsibility Principle),
|
||||
mudah dikembangkan secara independen, dan berkomunikasi melalui service
|
||||
atau interface yang telah ditentukan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Prinsip Desain
|
||||
|
||||
- Modular dan mudah dikembangkan.
|
||||
- Loose coupling, high cohesion.
|
||||
- Setiap modul memiliki domain bisnis yang jelas.
|
||||
- Antar modul tidak mengakses database modul lain secara langsung.
|
||||
- Komunikasi dilakukan melalui service, interface, atau event jika
|
||||
diperlukan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Daftar Modul
|
||||
|
||||
## 1. Core System
|
||||
|
||||
Tanggung jawab:
|
||||
|
||||
- Bootstrap aplikasi
|
||||
- Dependency Injection
|
||||
- Configuration
|
||||
- Logging
|
||||
- Health Check
|
||||
- Global Middleware
|
||||
- Exception Filter
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 2. Identity
|
||||
|
||||
Mengelola identitas pengguna.
|
||||
|
||||
Fitur:
|
||||
|
||||
- User
|
||||
- Profile
|
||||
- Session
|
||||
- Authentication (implementasi pada fase berikutnya)
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 3. Authorization
|
||||
|
||||
Mengelola hak akses.
|
||||
|
||||
Fitur:
|
||||
|
||||
- Group
|
||||
- Role
|
||||
- Permission
|
||||
- Domain Access
|
||||
- Resource Access
|
||||
- Special Access
|
||||
|
||||
Hierarki:
|
||||
|
||||
``` text
|
||||
User
|
||||
↓
|
||||
Group
|
||||
↓
|
||||
Role
|
||||
↓
|
||||
Permission
|
||||
↓
|
||||
Domain Access
|
||||
↓
|
||||
Resource Access
|
||||
↓
|
||||
Special Access
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 4. Registry
|
||||
|
||||
Pusat registrasi aplikasi dan layanan.
|
||||
|
||||
Mengelola:
|
||||
|
||||
- Application
|
||||
- Service
|
||||
- Domain
|
||||
- Adapter
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 5. Configuration
|
||||
|
||||
Menyimpan konfigurasi yang dapat diubah saat runtime.
|
||||
|
||||
Contoh:
|
||||
|
||||
- Theme
|
||||
- Timezone
|
||||
- Upload Limit
|
||||
- Default Language
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 6. Dashboard
|
||||
|
||||
Menyediakan data untuk dashboard RayLab.
|
||||
|
||||
Dashboard tidak menyimpan business logic, hanya menggabungkan data dari
|
||||
modul lain.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 7. Health
|
||||
|
||||
Monitoring internal.
|
||||
|
||||
Contoh:
|
||||
|
||||
- Database
|
||||
- Redis
|
||||
- Storage
|
||||
- Adapter
|
||||
- Service Status
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 8. Adapter
|
||||
|
||||
Lapisan integrasi layanan eksternal.
|
||||
|
||||
Contoh adapter:
|
||||
|
||||
- Nextcloud
|
||||
- Jellyfin
|
||||
- Immich
|
||||
- Minecraft
|
||||
- Future integrations
|
||||
|
||||
Semua komunikasi eksternal harus melalui Adapter.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 9. Storage
|
||||
|
||||
Mengelola storage logis.
|
||||
|
||||
Contoh:
|
||||
|
||||
- Storage
|
||||
- Volume
|
||||
- Quota
|
||||
- Path Mapping
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 10. Media
|
||||
|
||||
Media Manager berada di RayLab Core.
|
||||
|
||||
Tanggung jawab:
|
||||
|
||||
- Membuat struktur folder otomatis
|
||||
- Mengelola folder private/shared
|
||||
- Memindahkan media saat perubahan visibilitas
|
||||
- Mengubah permission
|
||||
- Memicu refresh library Jellyfin
|
||||
- Audit media
|
||||
|
||||
Jellyfin hanya membaca media, bukan mengelolanya.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## 11. Audit
|
||||
|
||||
Mencatat seluruh aktivitas penting sistem.
|
||||
|
||||
Contoh:
|
||||
|
||||
- Login
|
||||
- Perubahan permission
|
||||
- Pembuatan user
|
||||
- Penghapusan group
|
||||
- Perubahan konfigurasi
|
||||
- Aktivitas adapter
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Aturan Antar Modul
|
||||
|
||||
- Tidak ada modul yang mengakses repository modul lain secara
|
||||
langsung.
|
||||
- Semua business logic berada pada modul pemilik domain.
|
||||
- Integrasi dilakukan melalui service atau adapter.
|
||||
- Setiap modul harus dapat diuji secara mandiri.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Hasil Akhir Fase 1
|
||||
|
||||
Setelah fase ini selesai, RayLab Core memiliki struktur modular yang
|
||||
menjadi fondasi untuk seluruh pengembangan berikutnya.
|
||||
@@ -0,0 +1,218 @@
|
||||
# RayLab Core Phase 2 --- Domain Model
|
||||
|
||||
## Tujuan
|
||||
|
||||
Fase 2 mendefinisikan domain bisnis yang dimiliki RayLab Core beserta
|
||||
hubungan antar domain. Domain model menjadi dasar implementasi entity,
|
||||
service, API, dan database.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Prinsip Domain
|
||||
|
||||
- Domain mewakili konsep bisnis, bukan tabel database.
|
||||
- Setiap domain memiliki tanggung jawab yang jelas.
|
||||
- Domain saling berinteraksi melalui service, bukan akses langsung ke
|
||||
data domain lain.
|
||||
- Seluruh aturan bisnis berada pada domain terkait.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Domain Utama
|
||||
|
||||
## Identity
|
||||
|
||||
Mengelola identitas pengguna.
|
||||
|
||||
### Entity
|
||||
|
||||
- User
|
||||
- Profile
|
||||
- Session
|
||||
|
||||
### Tanggung Jawab
|
||||
|
||||
- Identitas pengguna
|
||||
- Informasi profil
|
||||
- Status sesi
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Authorization
|
||||
|
||||
Mengelola hak akses sistem.
|
||||
|
||||
### Entity
|
||||
|
||||
- Group
|
||||
- Role
|
||||
- Permission
|
||||
- Domain Access
|
||||
- Resource Access
|
||||
- Special Access
|
||||
|
||||
### Model IAM
|
||||
|
||||
``` text
|
||||
User
|
||||
↓
|
||||
Group
|
||||
↓
|
||||
Role
|
||||
↓
|
||||
Permission
|
||||
↓
|
||||
Domain Access
|
||||
↓
|
||||
Resource Access
|
||||
↓
|
||||
Special Access
|
||||
```
|
||||
|
||||
### Penjelasan
|
||||
|
||||
**Group** adalah identitas organisasi utama.
|
||||
|
||||
**Role** merupakan kumpulan tanggung jawab.
|
||||
|
||||
**Permission** mendefinisikan aksi yang diizinkan.
|
||||
|
||||
**Domain Access** menentukan aplikasi atau domain yang dapat diakses.
|
||||
|
||||
**Resource Access** menentukan objek di dalam aplikasi yang boleh
|
||||
digunakan.
|
||||
|
||||
**Special Access** merupakan override khusus untuk user tertentu tanpa
|
||||
mengubah group atau role.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Registry
|
||||
|
||||
Entity:
|
||||
|
||||
- Application
|
||||
- Service
|
||||
- Domain
|
||||
- Adapter
|
||||
|
||||
Berfungsi sebagai katalog seluruh layanan RayLab.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Configuration
|
||||
|
||||
Entity:
|
||||
|
||||
- Setting
|
||||
- Setting Category
|
||||
|
||||
Digunakan untuk konfigurasi yang dapat diubah saat runtime.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Storage
|
||||
|
||||
Entity:
|
||||
|
||||
- Storage
|
||||
- Volume
|
||||
- Quota
|
||||
|
||||
Mengelola penyimpanan logis dan alokasi kapasitas.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Media
|
||||
|
||||
Entity:
|
||||
|
||||
- Library
|
||||
- Folder Template
|
||||
- Folder Mapping
|
||||
- Folder Permission
|
||||
|
||||
Media Manager mengendalikan struktur media, sedangkan Jellyfin hanya
|
||||
membaca media yang telah disiapkan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Audit
|
||||
|
||||
Entity:
|
||||
|
||||
- Audit Log
|
||||
- Audit Category
|
||||
- Audit Target
|
||||
|
||||
Mencatat seluruh aktivitas penting sistem.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Health
|
||||
|
||||
Entity:
|
||||
|
||||
- Health Check
|
||||
- Service Status
|
||||
|
||||
Digunakan untuk memantau kesehatan layanan internal.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## System
|
||||
|
||||
Entity:
|
||||
|
||||
- Job
|
||||
- Notification
|
||||
|
||||
Digunakan untuk proses internal seperti background job dan notifikasi.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Relasi Antar Domain
|
||||
|
||||
``` text
|
||||
Identity
|
||||
│
|
||||
└── Authorization
|
||||
|
||||
Authorization
|
||||
│
|
||||
├── Registry
|
||||
├── Media
|
||||
├── Storage
|
||||
└── Dashboard
|
||||
|
||||
Registry
|
||||
│
|
||||
└── Adapter
|
||||
|
||||
Semua Domain
|
||||
│
|
||||
└── Audit
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Aturan Domain
|
||||
|
||||
- Domain hanya memiliki satu tanggung jawab utama.
|
||||
- Tidak ada duplikasi data antar domain.
|
||||
- Setiap domain memiliki service sendiri.
|
||||
- Entity hanya mewakili data dan aturan dasar domain.
|
||||
- Komunikasi lintas domain dilakukan melalui service.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Hasil Akhir Fase 2
|
||||
|
||||
Pada akhir fase ini RayLab Core memiliki model domain yang menjadi acuan
|
||||
untuk:
|
||||
|
||||
- Desain database
|
||||
- Layered Architecture
|
||||
- API
|
||||
- Implementasi modul
|
||||
- Pengembangan fitur di masa depan
|
||||
@@ -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.
|
||||
@@ -0,0 +1,311 @@
|
||||
# RayLab Core Phase 4 --- Technical Foundation
|
||||
|
||||
## Tujuan
|
||||
|
||||
Fase 4 menetapkan fondasi teknis RayLab Core. Dokumen ini mendefinisikan
|
||||
teknologi, konvensi pengembangan, dan standar implementasi yang akan
|
||||
digunakan secara konsisten pada seluruh modul.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tujuan Akhir
|
||||
|
||||
Project dapat dijalankan dengan satu perintah:
|
||||
|
||||
``` bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
Kemudian endpoint health dapat diakses:
|
||||
|
||||
``` text
|
||||
GET /health
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
``` json
|
||||
{
|
||||
"status": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Technology Stack
|
||||
|
||||
## Backend Framework
|
||||
|
||||
**NestJS**
|
||||
|
||||
Alasan:
|
||||
|
||||
- Modular architecture
|
||||
- Dependency Injection
|
||||
- Guard, Middleware, Interceptor
|
||||
- Swagger integration
|
||||
- Testing support
|
||||
- Sangat cocok untuk aplikasi enterprise.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Programming Language
|
||||
|
||||
**TypeScript**
|
||||
|
||||
Keuntungan:
|
||||
|
||||
- Type safety
|
||||
- Maintainability
|
||||
- IDE support
|
||||
- Konsisten dengan NestJS
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Database
|
||||
|
||||
**PostgreSQL**
|
||||
|
||||
Digunakan sebagai database utama RayLab Core.
|
||||
|
||||
Semua data aplikasi disimpan di PostgreSQL.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## ORM
|
||||
|
||||
**Prisma**
|
||||
|
||||
Keuntungan:
|
||||
|
||||
- Type-safe query
|
||||
- Migration
|
||||
- Schema management
|
||||
- Autocomplete
|
||||
- Maintainable
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Cache
|
||||
|
||||
**Redis**
|
||||
|
||||
Digunakan untuk:
|
||||
|
||||
- Session
|
||||
- Cache
|
||||
- Rate limiting
|
||||
- Queue (apabila diperlukan)
|
||||
|
||||
Redis bukan penyimpanan data utama.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## API Documentation
|
||||
|
||||
**Swagger (OpenAPI)**
|
||||
|
||||
Seluruh endpoint wajib memiliki dokumentasi.
|
||||
|
||||
Minimal mencakup:
|
||||
|
||||
- Summary
|
||||
- Description
|
||||
- Request DTO
|
||||
- Response DTO
|
||||
- Error Response
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Validation
|
||||
|
||||
Menggunakan:
|
||||
|
||||
- class-validator
|
||||
- class-transformer
|
||||
|
||||
Seluruh request divalidasi sebelum masuk business logic.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Logging
|
||||
|
||||
Menggunakan:
|
||||
|
||||
**Pino**
|
||||
|
||||
Target:
|
||||
|
||||
- Structured Logging
|
||||
- Performance
|
||||
- Mudah diintegrasikan dengan monitoring.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Testing
|
||||
|
||||
Standar pengujian:
|
||||
|
||||
### Unit Test
|
||||
|
||||
- Jest
|
||||
|
||||
### Integration Test
|
||||
|
||||
- Jest
|
||||
|
||||
### End-to-End Test
|
||||
|
||||
- Playwright
|
||||
|
||||
Standar ini mengikuti roadmap pengujian RayLab.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Containerization
|
||||
|
||||
Seluruh aplikasi dijalankan menggunakan Docker.
|
||||
|
||||
Container utama:
|
||||
|
||||
- raylab-core
|
||||
- postgres-raylab
|
||||
- redis
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Configuration
|
||||
|
||||
Konfigurasi menggunakan:
|
||||
|
||||
- .env
|
||||
- NestJS Config Module
|
||||
|
||||
Business logic tidak boleh mengakses process.env secara langsung.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Coding Convention
|
||||
|
||||
## Dependency Injection
|
||||
|
||||
Semua dependency menggunakan Dependency Injection NestJS.
|
||||
|
||||
Tidak diperbolehkan:
|
||||
|
||||
``` typescript
|
||||
new UserRepository();
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Naming Convention
|
||||
|
||||
Folder:
|
||||
|
||||
``` text
|
||||
users
|
||||
groups
|
||||
authorization
|
||||
registry
|
||||
```
|
||||
|
||||
Class:
|
||||
|
||||
``` text
|
||||
UserService
|
||||
UsersController
|
||||
UserRepository
|
||||
CreateUserDto
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## UUID
|
||||
|
||||
Seluruh entity menggunakan UUID v7 sebagai primary key.
|
||||
|
||||
Tidak menggunakan integer auto increment.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## API Versioning
|
||||
|
||||
Semua endpoint menggunakan format:
|
||||
|
||||
``` text
|
||||
/api/v1/
|
||||
```
|
||||
|
||||
Perubahan besar menggunakan versi API baru.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Standard Response
|
||||
|
||||
### Success
|
||||
|
||||
``` json
|
||||
{
|
||||
"success": true,
|
||||
"data": {},
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
|
||||
### Error
|
||||
|
||||
``` json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "USER_NOT_FOUND",
|
||||
"message": "User not found"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Development Convention
|
||||
|
||||
Seluruh modul wajib mengikuti aturan berikut.
|
||||
|
||||
- Satu module mewakili satu domain bisnis.
|
||||
- Tidak ada query database di Controller.
|
||||
- Tidak ada business logic di Frontend.
|
||||
- Integrasi eksternal hanya melalui Adapter.
|
||||
- Seluruh endpoint memiliki DTO.
|
||||
- Seluruh endpoint memiliki validasi.
|
||||
- Seluruh endpoint memiliki dokumentasi Swagger.
|
||||
- Seluruh perubahan penting menghasilkan Audit Log.
|
||||
- Seluruh modul dapat diuji secara mandiri.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Struktur Project
|
||||
|
||||
``` text
|
||||
raylab-core/
|
||||
|
||||
├── src/
|
||||
├── prisma/
|
||||
├── docs/
|
||||
├── tests/
|
||||
├── scripts/
|
||||
├── docker/
|
||||
├── package.json
|
||||
├── docker-compose.yml
|
||||
└── README.md
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Hasil Akhir Fase 4
|
||||
|
||||
Setelah fase ini selesai, RayLab Core memiliki fondasi teknis yang
|
||||
konsisten, modern, dan siap digunakan sebagai dasar implementasi seluruh
|
||||
modul pada fase berikutnya.
|
||||
|
||||
Dokumen ini menjadi acuan resmi untuk pemilihan teknologi, standar
|
||||
coding, struktur project, dan konvensi pengembangan RayLab Core.
|
||||
@@ -0,0 +1,310 @@
|
||||
# RayLab Core Phase 5 --- Data Architecture
|
||||
|
||||
## Tujuan
|
||||
|
||||
Fase 5 mendefinisikan arsitektur data RayLab Core. Fokus fase ini adalah
|
||||
bagaimana seluruh domain saling berhubungan pada tingkat penyimpanan
|
||||
data, sekaligus menetapkan standar desain database yang akan digunakan
|
||||
oleh seluruh modul.
|
||||
|
||||
> Dokumen ini membahas arsitektur data, bukan implementasi tabel secara
|
||||
> rinci.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Prinsip Data Architecture
|
||||
|
||||
RayLab Core menggunakan prinsip berikut:
|
||||
|
||||
- Database merepresentasikan domain bisnis.
|
||||
- Tidak ada duplikasi data antar domain.
|
||||
- Setiap domain memiliki kepemilikan data (data ownership).
|
||||
- Seluruh perubahan struktur database dilakukan melalui migration.
|
||||
- Integritas data lebih diutamakan daripada kemudahan implementasi.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Pembagian Database Schema
|
||||
|
||||
Agar database tetap terstruktur, PostgreSQL dibagi menjadi beberapa
|
||||
schema.
|
||||
|
||||
## identity
|
||||
|
||||
Mengelola identitas pengguna.
|
||||
|
||||
Entity utama:
|
||||
|
||||
- users
|
||||
- profiles
|
||||
- sessions
|
||||
- user_groups
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## authorization
|
||||
|
||||
Mengelola hak akses.
|
||||
|
||||
Entity utama:
|
||||
|
||||
- groups
|
||||
- roles
|
||||
- permissions
|
||||
- role_permissions
|
||||
- group_roles
|
||||
- special_access
|
||||
- domain_access
|
||||
- resource_access
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## registry
|
||||
|
||||
Mengelola registrasi aplikasi dan layanan.
|
||||
|
||||
Entity utama:
|
||||
|
||||
- applications
|
||||
- services
|
||||
- domains
|
||||
- adapters
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## configuration
|
||||
|
||||
Mengelola konfigurasi runtime.
|
||||
|
||||
Entity utama:
|
||||
|
||||
- settings
|
||||
- setting_categories
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## storage
|
||||
|
||||
Mengelola penyimpanan logis.
|
||||
|
||||
Entity utama:
|
||||
|
||||
- storages
|
||||
- volumes
|
||||
- quotas
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## media
|
||||
|
||||
Digunakan oleh Media Manager.
|
||||
|
||||
Entity utama:
|
||||
|
||||
- libraries
|
||||
- folder_templates
|
||||
- folder_permissions
|
||||
- folder_mappings
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## audit
|
||||
|
||||
Menyimpan riwayat aktivitas.
|
||||
|
||||
Entity utama:
|
||||
|
||||
- audit_logs
|
||||
- audit_categories
|
||||
- audit_targets
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## system
|
||||
|
||||
Digunakan oleh sistem internal.
|
||||
|
||||
Entity utama:
|
||||
|
||||
- jobs
|
||||
- notifications
|
||||
- health_checks
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Hubungan Antar Domain
|
||||
|
||||
``` text
|
||||
Identity
|
||||
│
|
||||
└──── Authorization
|
||||
│
|
||||
├──── Registry
|
||||
├──── Storage
|
||||
├──── Media
|
||||
└──── Configuration
|
||||
|
||||
Semua Domain
|
||||
│
|
||||
▼
|
||||
Audit
|
||||
```
|
||||
|
||||
Audit menerima aktivitas dari seluruh domain.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Standar Primary Key
|
||||
|
||||
Seluruh entity menggunakan:
|
||||
|
||||
- UUID v7
|
||||
|
||||
Keuntungan:
|
||||
|
||||
- Sulit ditebak
|
||||
- Konsisten
|
||||
- Cocok untuk sistem terdistribusi
|
||||
- Performa indeks lebih baik dibanding UUID v4
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Standar Timestamp
|
||||
|
||||
Seluruh entity memiliki minimal:
|
||||
|
||||
``` text
|
||||
created_at
|
||||
updated_at
|
||||
deleted_at
|
||||
```
|
||||
|
||||
Jika diperlukan juga memiliki:
|
||||
|
||||
``` text
|
||||
created_by
|
||||
updated_by
|
||||
deleted_by
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Soft Delete
|
||||
|
||||
Data penting tidak langsung dihapus.
|
||||
|
||||
Sebaliknya menggunakan:
|
||||
|
||||
``` text
|
||||
deleted_at
|
||||
```
|
||||
|
||||
Keuntungan:
|
||||
|
||||
- Audit lebih mudah
|
||||
- Restore data memungkinkan
|
||||
- Riwayat tetap terjaga
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Metadata
|
||||
|
||||
Entity yang memerlukan fleksibilitas dapat memiliki kolom:
|
||||
|
||||
``` text
|
||||
metadata (JSONB)
|
||||
```
|
||||
|
||||
Contoh:
|
||||
|
||||
``` json
|
||||
{
|
||||
"theme": "dark",
|
||||
"avatar": "/avatars/user.png"
|
||||
}
|
||||
```
|
||||
|
||||
JSONB digunakan hanya untuk data yang bersifat dinamis, bukan untuk
|
||||
relasi utama.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Naming Convention
|
||||
|
||||
## Schema
|
||||
|
||||
Menggunakan huruf kecil.
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
identity
|
||||
authorization
|
||||
audit
|
||||
```
|
||||
|
||||
## Table
|
||||
|
||||
Menggunakan bentuk jamak.
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
users
|
||||
roles
|
||||
permissions
|
||||
```
|
||||
|
||||
## Column
|
||||
|
||||
Menggunakan snake_case.
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
created_at
|
||||
updated_at
|
||||
display_name
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Migration Strategy
|
||||
|
||||
Seluruh perubahan struktur database wajib menggunakan Prisma Migration.
|
||||
|
||||
Tidak diperbolehkan:
|
||||
|
||||
- Mengubah tabel langsung di production.
|
||||
- Mengedit struktur database secara manual.
|
||||
- Menghapus migration yang sudah digunakan.
|
||||
|
||||
Migration menjadi sumber kebenaran (single source of truth) untuk
|
||||
struktur database.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Integritas Data
|
||||
|
||||
Beberapa prinsip yang harus dijaga:
|
||||
|
||||
- Foreign key digunakan pada seluruh relasi penting.
|
||||
- Constraint digunakan untuk menjaga validitas data.
|
||||
- Unique index diterapkan pada data yang harus unik.
|
||||
- Cascade delete hanya digunakan jika benar-benar diperlukan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Hasil Akhir Fase 5
|
||||
|
||||
Pada akhir fase ini RayLab Core memiliki:
|
||||
|
||||
- Standar arsitektur database.
|
||||
- Pembagian schema berdasarkan domain.
|
||||
- Aturan relasi data.
|
||||
- Standar UUID, timestamp, dan soft delete.
|
||||
- Strategi migration.
|
||||
- Konvensi penamaan database.
|
||||
|
||||
Dokumen ini menjadi acuan resmi ketika mulai membuat Prisma Schema dan
|
||||
migration pada tahap implementasi.
|
||||
@@ -0,0 +1,289 @@
|
||||
# RayLab Core Phase 6 --- API Architecture
|
||||
|
||||
## Tujuan
|
||||
|
||||
Fase 6 mendefinisikan standar API RayLab Core sebagai kontrak komunikasi
|
||||
untuk seluruh aplikasi dalam ekosistem RayLab.
|
||||
|
||||
API harus konsisten, mudah dipahami, terdokumentasi, dan stabil untuk
|
||||
jangka panjang.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Prinsip API
|
||||
|
||||
Seluruh API RayLab Core mengikuti prinsip berikut:
|
||||
|
||||
- RESTful
|
||||
- Stateless
|
||||
- Versioned
|
||||
- Consistent
|
||||
- Predictable
|
||||
- Self Documented
|
||||
- API First
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Base URL
|
||||
|
||||
Seluruh endpoint menggunakan format:
|
||||
|
||||
``` text
|
||||
/api/v1/
|
||||
```
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
/api/v1/users
|
||||
/api/v1/groups
|
||||
/api/v1/domains
|
||||
/api/v1/applications
|
||||
/api/v1/media
|
||||
/api/v1/storage
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# HTTP Method
|
||||
|
||||
Method Fungsi
|
||||
-------- ------------------------------------------
|
||||
GET Membaca data
|
||||
POST Membuat data
|
||||
PATCH Memperbarui sebagian data
|
||||
PUT Mengganti seluruh data (jika diperlukan)
|
||||
DELETE Soft delete
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Resource-Oriented API
|
||||
|
||||
Contoh endpoint User:
|
||||
|
||||
``` http
|
||||
GET /api/v1/users
|
||||
GET /api/v1/users/{id}
|
||||
POST /api/v1/users
|
||||
PATCH /api/v1/users/{id}
|
||||
DELETE /api/v1/users/{id}
|
||||
```
|
||||
|
||||
Nested resource:
|
||||
|
||||
``` text
|
||||
/users/{id}/groups
|
||||
/users/{id}/sessions
|
||||
/groups/{id}/roles
|
||||
/domains/{id}/resources
|
||||
```
|
||||
|
||||
Action endpoint:
|
||||
|
||||
``` text
|
||||
/users/{id}/reset-password
|
||||
/users/{id}/special-access
|
||||
/users/{id}/groups
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Standard Response
|
||||
|
||||
## Success
|
||||
|
||||
``` json
|
||||
{
|
||||
"success": true,
|
||||
"data": {},
|
||||
"meta": {
|
||||
"requestId": "...",
|
||||
"timestamp": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error
|
||||
|
||||
``` json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": "USER_NOT_FOUND",
|
||||
"message": "User not found"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Semua endpoint wajib menggunakan format yang sama.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Pagination
|
||||
|
||||
Request:
|
||||
|
||||
``` text
|
||||
GET /users?page=1&limit=20
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
``` json
|
||||
{
|
||||
"success": true,
|
||||
"data": [],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 125,
|
||||
"totalPages": 7
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Filtering
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
/users?group=Owner
|
||||
/applications?status=online
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Sorting
|
||||
|
||||
``` text
|
||||
/users?sort=name
|
||||
/users?sort=-createdAt
|
||||
```
|
||||
|
||||
Tanda minus (`-`) berarti urutan menurun (descending).
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Search
|
||||
|
||||
``` text
|
||||
/users?search=ray
|
||||
```
|
||||
|
||||
Pencarian dilakukan melalui query parameter, bukan endpoint terpisah.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# API Versioning
|
||||
|
||||
Versi API menjadi bagian dari URL.
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
/api/v1/
|
||||
/api/v2/
|
||||
```
|
||||
|
||||
Perubahan besar tidak boleh merusak kompatibilitas client lama.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Public API dan Internal API
|
||||
|
||||
## Public API
|
||||
|
||||
Digunakan oleh:
|
||||
|
||||
- Web Admin
|
||||
- Android
|
||||
- CLI
|
||||
- Future Client
|
||||
|
||||
## Internal API
|
||||
|
||||
Digunakan oleh:
|
||||
|
||||
- Background Job
|
||||
- Scheduler
|
||||
- Adapter
|
||||
- Internal Service
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
/internal/jobs
|
||||
/internal/sync
|
||||
```
|
||||
|
||||
Internal API tidak boleh diekspos ke publik.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Request ID
|
||||
|
||||
Setiap request memiliki Request ID unik.
|
||||
|
||||
Header:
|
||||
|
||||
``` text
|
||||
X-Request-ID
|
||||
```
|
||||
|
||||
Request ID digunakan untuk:
|
||||
|
||||
- Audit
|
||||
- Logging
|
||||
- Debugging
|
||||
- Distributed tracing
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Idempotency
|
||||
|
||||
Operasi tertentu mendukung:
|
||||
|
||||
``` text
|
||||
Idempotency-Key
|
||||
```
|
||||
|
||||
Hal ini mencegah duplikasi request akibat retry jaringan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Dokumentasi API
|
||||
|
||||
Seluruh endpoint harus didokumentasikan menggunakan Swagger (OpenAPI).
|
||||
|
||||
Minimal mencakup:
|
||||
|
||||
- Summary
|
||||
- Description
|
||||
- Request DTO
|
||||
- Response DTO
|
||||
- Error Response
|
||||
|
||||
Tidak boleh ada endpoint tanpa dokumentasi.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Aturan API
|
||||
|
||||
- Tidak ada endpoint tanpa versioning.
|
||||
- Tidak ada endpoint tanpa validasi DTO.
|
||||
- Tidak ada endpoint tanpa dokumentasi.
|
||||
- Seluruh endpoint menghasilkan response yang konsisten.
|
||||
- Controller tidak berisi business logic.
|
||||
- Error menggunakan kode yang konsisten.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Hasil Akhir Fase 6
|
||||
|
||||
Pada akhir fase ini RayLab Core memiliki standar API yang menjadi
|
||||
kontrak komunikasi resmi untuk seluruh aplikasi dalam ekosistem RayLab.
|
||||
|
||||
Dokumen ini menjadi acuan implementasi Controller, DTO, Service,
|
||||
dokumentasi Swagger, dan integrasi seluruh client dengan RayLab Core.
|
||||
@@ -0,0 +1,249 @@
|
||||
# RayLab Core Phase 7 --- Project Structure
|
||||
|
||||
## Tujuan
|
||||
|
||||
Fase 7 mendefinisikan struktur repository, organisasi source code, serta
|
||||
standar penempatan file pada RayLab Core. Tujuannya adalah memastikan
|
||||
seluruh kode memiliki pola yang konsisten sehingga mudah dipelihara,
|
||||
dikembangkan, dan dipahami.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Prinsip
|
||||
|
||||
- Struktur mengikuti domain bisnis.
|
||||
- Setiap module berdiri sendiri.
|
||||
- Konfigurasi dipisahkan dari business logic.
|
||||
- Dokumentasi menjadi bagian dari repository.
|
||||
- Mudah diskalakan tanpa mengubah struktur dasar.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Struktur Repository
|
||||
|
||||
``` text
|
||||
raylab-core/
|
||||
│
|
||||
├── docs/
|
||||
├── docker/
|
||||
├── prisma/
|
||||
├── scripts/
|
||||
├── tests/
|
||||
├── src/
|
||||
├── .env.example
|
||||
├── .gitignore
|
||||
├── docker-compose.yml
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Struktur Source Code
|
||||
|
||||
``` text
|
||||
src/
|
||||
│
|
||||
├── main.ts
|
||||
├── app.module.ts
|
||||
├── common/
|
||||
├── config/
|
||||
├── modules/
|
||||
├── adapters/
|
||||
└── shared/
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Common
|
||||
|
||||
Berisi komponen yang digunakan lintas modul.
|
||||
|
||||
Contoh:
|
||||
|
||||
- Guards
|
||||
- Filters
|
||||
- Interceptors
|
||||
- Middleware
|
||||
- Logger
|
||||
- Exceptions
|
||||
- Decorators
|
||||
- Pipes
|
||||
- Utilities
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Config
|
||||
|
||||
Berisi konfigurasi aplikasi.
|
||||
|
||||
Contoh:
|
||||
|
||||
- Database
|
||||
- Redis
|
||||
- JWT
|
||||
- Environment
|
||||
- Swagger
|
||||
|
||||
Seluruh konfigurasi diakses melalui ConfigService.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Modules
|
||||
|
||||
Setiap domain memiliki module sendiri.
|
||||
|
||||
``` text
|
||||
modules/
|
||||
├── identity/
|
||||
├── authorization/
|
||||
├── registry/
|
||||
├── configuration/
|
||||
├── storage/
|
||||
├── media/
|
||||
├── audit/
|
||||
├── dashboard/
|
||||
└── health/
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Struktur Internal Module
|
||||
|
||||
``` text
|
||||
identity/
|
||||
│
|
||||
├── controllers/
|
||||
├── services/
|
||||
├── domain/
|
||||
├── repositories/
|
||||
├── dto/
|
||||
├── entities/
|
||||
├── interfaces/
|
||||
├── mappers/
|
||||
├── events/
|
||||
└── identity.module.ts
|
||||
```
|
||||
|
||||
Seluruh file yang berkaitan dengan satu domain berada dalam module yang
|
||||
sama.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Adapters
|
||||
|
||||
Seluruh integrasi eksternal ditempatkan pada folder adapters.
|
||||
|
||||
``` text
|
||||
adapters/
|
||||
├── nextcloud/
|
||||
├── jellyfin/
|
||||
├── immich/
|
||||
├── minecraft/
|
||||
└── ...
|
||||
```
|
||||
|
||||
Adapter tidak menyimpan business logic.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Prisma
|
||||
|
||||
``` text
|
||||
prisma/
|
||||
├── schema.prisma
|
||||
├── migrations/
|
||||
└── seed.ts
|
||||
```
|
||||
|
||||
Seluruh perubahan database dilakukan melalui migration.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tests
|
||||
|
||||
``` text
|
||||
tests/
|
||||
├── unit/
|
||||
├── integration/
|
||||
└── e2e/
|
||||
```
|
||||
|
||||
Pengujian dipisahkan berdasarkan jenisnya.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Dokumentasi
|
||||
|
||||
``` text
|
||||
docs/
|
||||
├── architecture/
|
||||
├── adr/
|
||||
├── api/
|
||||
├── modules/
|
||||
└── guides/
|
||||
```
|
||||
|
||||
Dokumentasi menjadi bagian dari source repository dan diperbarui
|
||||
bersamaan dengan perubahan kode.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Naming Convention
|
||||
|
||||
## Folder
|
||||
|
||||
Menggunakan huruf kecil.
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
identity
|
||||
authorization
|
||||
media
|
||||
```
|
||||
|
||||
## File
|
||||
|
||||
Menggunakan nama yang deskriptif.
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
create-user.dto.ts
|
||||
user.repository.ts
|
||||
users.controller.ts
|
||||
```
|
||||
|
||||
## Class
|
||||
|
||||
Menggunakan PascalCase.
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
UsersController
|
||||
CreateUserDto
|
||||
UserRepository
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Aturan Penempatan Kode
|
||||
|
||||
- Controller hanya berada di folder controllers.
|
||||
- DTO hanya berada di folder dto.
|
||||
- Entity hanya berada di folder entities.
|
||||
- Repository hanya berada di folder repositories.
|
||||
- Business logic berada di services dan domain.
|
||||
- Integrasi eksternal berada di adapters.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Hasil Akhir Fase 7
|
||||
|
||||
Pada akhir fase ini, RayLab Core memiliki struktur repository dan
|
||||
organisasi kode yang baku. Setiap developer dapat mengetahui lokasi
|
||||
suatu komponen tanpa perlu menebak, sehingga pengembangan jangka panjang
|
||||
tetap konsisten dan mudah dipelihara.
|
||||
@@ -0,0 +1,267 @@
|
||||
# RayLab Core Phase 8 --- Development Workflow
|
||||
|
||||
## Tujuan
|
||||
|
||||
Fase 8 mendefinisikan alur kerja pengembangan (Development Workflow)
|
||||
RayLab Core agar proses implementasi, pengujian, review, dan rilis
|
||||
dilakukan secara konsisten.
|
||||
|
||||
Dokumen ini menjadi standar kerja untuk seluruh pengembangan RayLab
|
||||
Core.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Prinsip
|
||||
|
||||
- Seluruh perubahan dapat dilacak.
|
||||
- Setiap fitur dikembangkan secara terpisah.
|
||||
- Kualitas kode lebih penting daripada kecepatan.
|
||||
- Otomatisasi digunakan sebanyak mungkin.
|
||||
- Dokumentasi diperbarui bersamaan dengan perubahan kode.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Development Lifecycle
|
||||
|
||||
``` text
|
||||
Requirement
|
||||
│
|
||||
▼
|
||||
Architecture
|
||||
│
|
||||
▼
|
||||
Issue / Task
|
||||
│
|
||||
▼
|
||||
Implementation
|
||||
│
|
||||
▼
|
||||
Unit Test
|
||||
│
|
||||
▼
|
||||
Integration Test
|
||||
│
|
||||
▼
|
||||
End-to-End Test
|
||||
│
|
||||
▼
|
||||
Code Review
|
||||
│
|
||||
▼
|
||||
Merge
|
||||
│
|
||||
▼
|
||||
Release
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Git Workflow
|
||||
|
||||
## Branch Utama
|
||||
|
||||
``` text
|
||||
main
|
||||
```
|
||||
|
||||
Selalu berisi kode yang stabil.
|
||||
|
||||
## Branch Pengembangan
|
||||
|
||||
Gunakan branch terpisah untuk setiap pekerjaan.
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
feature/identity
|
||||
feature/media-manager
|
||||
feature/api-users
|
||||
|
||||
fix/login-session
|
||||
fix/storage-permission
|
||||
|
||||
refactor/authorization
|
||||
|
||||
docs/api-architecture
|
||||
```
|
||||
|
||||
Satu branch hanya menangani satu tujuan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Commit Convention
|
||||
|
||||
Format commit:
|
||||
|
||||
``` text
|
||||
type(scope): description
|
||||
```
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
feat(identity): add user service
|
||||
fix(media): resolve folder permission bug
|
||||
docs(api): update endpoint documentation
|
||||
refactor(registry): simplify adapter registration
|
||||
test(users): add integration test
|
||||
```
|
||||
|
||||
Jenis commit:
|
||||
|
||||
- feat
|
||||
- fix
|
||||
- docs
|
||||
- refactor
|
||||
- test
|
||||
- chore
|
||||
- ci
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Pull Request Checklist
|
||||
|
||||
Sebelum merge:
|
||||
|
||||
- Kode berhasil dikompilasi.
|
||||
- Unit test lulus.
|
||||
- Integration test lulus.
|
||||
- E2E test lulus (jika relevan).
|
||||
- Dokumentasi diperbarui.
|
||||
- Migration ditinjau.
|
||||
- Tidak ada perubahan yang tidak terkait.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Testing Strategy
|
||||
|
||||
## Unit Test
|
||||
|
||||
Menguji business logic secara terisolasi.
|
||||
|
||||
Tool:
|
||||
|
||||
- Jest
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Integration Test
|
||||
|
||||
Menguji interaksi antar modul.
|
||||
|
||||
Tool:
|
||||
|
||||
- Jest
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## End-to-End Test
|
||||
|
||||
Menguji perilaku sistem dari sudut pandang pengguna.
|
||||
|
||||
Tool:
|
||||
|
||||
- Playwright
|
||||
|
||||
Standar ini mengikuti proses pengujian RayLab yang telah ditetapkan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Code Review
|
||||
|
||||
Fokus review:
|
||||
|
||||
- Kesesuaian dengan arsitektur.
|
||||
- Kualitas business logic.
|
||||
- Keamanan.
|
||||
- Konsistensi penamaan.
|
||||
- Keterbacaan kode.
|
||||
- Dampak terhadap modul lain.
|
||||
|
||||
Review tidak hanya memeriksa apakah kode berjalan, tetapi juga apakah
|
||||
kode sesuai dengan standar RayLab Core.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Database Workflow
|
||||
|
||||
Perubahan database:
|
||||
|
||||
1. Ubah `schema.prisma`.
|
||||
2. Buat migration.
|
||||
3. Jalankan migration pada lingkungan pengembangan.
|
||||
4. Perbarui dokumentasi jika diperlukan.
|
||||
|
||||
Perubahan langsung pada database produksi tidak diperbolehkan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Documentation Workflow
|
||||
|
||||
Setiap perubahan yang memengaruhi arsitektur, API, atau modul harus
|
||||
diikuti dengan pembaruan dokumentasi.
|
||||
|
||||
Area dokumentasi:
|
||||
|
||||
- Architecture
|
||||
- API
|
||||
- Module
|
||||
- ADR
|
||||
- Guide
|
||||
|
||||
Dokumentasi menjadi bagian dari proses pengembangan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Release Workflow
|
||||
|
||||
``` text
|
||||
Development
|
||||
│
|
||||
▼
|
||||
Testing
|
||||
│
|
||||
▼
|
||||
Review
|
||||
│
|
||||
▼
|
||||
Tag Release
|
||||
│
|
||||
▼
|
||||
Docker Build
|
||||
│
|
||||
▼
|
||||
Deployment
|
||||
```
|
||||
|
||||
Setiap rilis menggunakan tag versi yang jelas.
|
||||
|
||||
Contoh:
|
||||
|
||||
``` text
|
||||
v1.0.0
|
||||
v1.1.0
|
||||
v2.0.0
|
||||
```
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Definition of Done
|
||||
|
||||
Sebuah pekerjaan dianggap selesai apabila:
|
||||
|
||||
- Implementasi selesai.
|
||||
- Seluruh test lulus.
|
||||
- Tidak ada error linting.
|
||||
- Dokumentasi diperbarui.
|
||||
- Migration tersedia (jika diperlukan).
|
||||
- Telah melalui code review.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Hasil Akhir Fase 8
|
||||
|
||||
Pada akhir fase ini RayLab Core memiliki standar workflow pengembangan
|
||||
yang mencakup implementasi, pengujian, review, dokumentasi, dan proses
|
||||
rilis. Workflow ini menjadi pedoman agar seluruh pengembangan tetap
|
||||
konsisten, berkualitas, dan mudah dipelihara dalam jangka panjang.
|
||||
@@ -0,0 +1,249 @@
|
||||
# RayLab Core Phase 9 --- Implementation Roadmap
|
||||
|
||||
## Tujuan
|
||||
|
||||
Fase 9 mendefinisikan urutan implementasi RayLab Core berdasarkan
|
||||
prioritas, dependensi, dan nilai bisnis. Roadmap ini menjadi acuan resmi
|
||||
agar pengembangan dilakukan secara bertahap dan terstruktur.
|
||||
|
||||
> Fokus fase ini adalah **urutan implementasi**, bukan rincian kode.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Prinsip Roadmap
|
||||
|
||||
- Bangun fondasi sebelum fitur.
|
||||
- Implementasikan modul berdasarkan dependensi.
|
||||
- Setiap fase menghasilkan sistem yang dapat dijalankan dan diuji.
|
||||
- Hindari membangun fitur yang belum memiliki fondasi.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 1 --- Core Foundation
|
||||
|
||||
Tujuan:
|
||||
|
||||
- Bootstrap NestJS
|
||||
- Konfigurasi Docker
|
||||
- PostgreSQL
|
||||
- Prisma
|
||||
- Redis
|
||||
- Logging
|
||||
- Config Module
|
||||
- Health Check
|
||||
- Swagger
|
||||
|
||||
Target:
|
||||
|
||||
- Project dapat dijalankan.
|
||||
- Health endpoint tersedia.
|
||||
- Database dan Redis terhubung.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 2 --- Identity
|
||||
|
||||
Implementasi:
|
||||
|
||||
- User
|
||||
- Profile
|
||||
- Session
|
||||
- User Repository
|
||||
- User Service
|
||||
- CRUD User
|
||||
|
||||
Target:
|
||||
|
||||
- Pengguna dapat dikelola melalui API.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 3 --- Authorization
|
||||
|
||||
Implementasi:
|
||||
|
||||
- Group
|
||||
- Role
|
||||
- Permission
|
||||
- Domain Access
|
||||
- Resource Access
|
||||
- Special Access
|
||||
|
||||
Target:
|
||||
|
||||
- Model IAM RayLab Core berfungsi.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 4 --- Registry
|
||||
|
||||
Implementasi:
|
||||
|
||||
- Application Registry
|
||||
- Service Registry
|
||||
- Domain Registry
|
||||
- Adapter Registry
|
||||
|
||||
Target:
|
||||
|
||||
- Seluruh aplikasi dan layanan dapat didaftarkan dan ditemukan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 5 --- Configuration
|
||||
|
||||
Implementasi:
|
||||
|
||||
- Runtime Settings
|
||||
- Setting Categories
|
||||
- Configuration API
|
||||
|
||||
Target:
|
||||
|
||||
- Konfigurasi dapat diubah tanpa mengubah kode aplikasi.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 6 --- Storage
|
||||
|
||||
Implementasi:
|
||||
|
||||
- Storage
|
||||
- Volume
|
||||
- Quota
|
||||
- Path Mapping
|
||||
|
||||
Target:
|
||||
|
||||
- Penyimpanan logis dapat dikelola secara terpusat.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 7 --- Media Manager
|
||||
|
||||
Implementasi:
|
||||
|
||||
- Folder Template
|
||||
- Folder Mapping
|
||||
- Folder Permission
|
||||
- Folder Provisioning
|
||||
- Media Relocation
|
||||
- Jellyfin Refresh Trigger
|
||||
|
||||
Target:
|
||||
|
||||
- Media Manager menjadi pengelola utama struktur media.
|
||||
- Jellyfin hanya bertindak sebagai media server.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 8 --- Audit
|
||||
|
||||
Implementasi:
|
||||
|
||||
- Audit Log
|
||||
- Audit Category
|
||||
- Audit Target
|
||||
|
||||
Target:
|
||||
|
||||
- Seluruh aktivitas penting sistem tercatat.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 9 --- Dashboard
|
||||
|
||||
Implementasi:
|
||||
|
||||
- Dashboard API
|
||||
- Statistik
|
||||
- Ringkasan sistem
|
||||
- Widget
|
||||
|
||||
Target:
|
||||
|
||||
- Dashboard dapat mengambil data dari seluruh modul.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 10 --- Health & Monitoring
|
||||
|
||||
Implementasi:
|
||||
|
||||
- Health Check
|
||||
- Service Status
|
||||
- Dependency Status
|
||||
- Adapter Status
|
||||
|
||||
Target:
|
||||
|
||||
- Kondisi sistem dapat dipantau melalui API.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 11 --- External Adapter
|
||||
|
||||
Implementasi:
|
||||
|
||||
- Nextcloud Adapter
|
||||
- Jellyfin Adapter
|
||||
- Immich Adapter
|
||||
- Adapter lain sesuai kebutuhan
|
||||
|
||||
Target:
|
||||
|
||||
- Integrasi eksternal menggunakan standar Adapter Layer.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahap 12 --- Optimization
|
||||
|
||||
Implementasi:
|
||||
|
||||
- Performance tuning
|
||||
- Caching
|
||||
- Query optimization
|
||||
- Background job optimization
|
||||
|
||||
Target:
|
||||
|
||||
- Sistem siap untuk penggunaan jangka panjang.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Definition of Complete
|
||||
|
||||
Sebuah tahap dianggap selesai apabila:
|
||||
|
||||
- Seluruh fitur pada tahap tersebut selesai.
|
||||
- Unit Test lulus.
|
||||
- Integration Test lulus.
|
||||
- Dokumentasi diperbarui.
|
||||
- API terdokumentasi.
|
||||
- Migration tersedia jika diperlukan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Deliverable
|
||||
|
||||
Pada akhir roadmap, RayLab Core memiliki:
|
||||
|
||||
- Fondasi teknis yang stabil.
|
||||
- Identity & Authorization terintegrasi.
|
||||
- Registry dan Configuration.
|
||||
- Storage dan Media Manager.
|
||||
- Audit.
|
||||
- Dashboard API.
|
||||
- Health Monitoring.
|
||||
- Adapter Framework.
|
||||
- Dokumentasi lengkap.
|
||||
- Standar pengembangan yang konsisten.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Hasil Akhir Fase 9
|
||||
|
||||
Dokumen ini menjadi acuan resmi urutan implementasi RayLab Core sehingga
|
||||
setiap modul dibangun berdasarkan fondasi yang telah tersedia,
|
||||
mengurangi risiko perubahan besar di kemudian hari dan menjaga
|
||||
konsistensi arsitektur selama pengembangan.
|
||||
@@ -0,0 +1,221 @@
|
||||
# RayLab Core Phase 10 --- Deployment & Operations
|
||||
|
||||
## Tujuan
|
||||
|
||||
Fase 10 mendefinisikan standar deployment dan operasional RayLab Core
|
||||
agar sistem dapat berjalan stabil, aman, mudah dipelihara, serta siap
|
||||
digunakan sebagai layanan 24/7 pada infrastruktur RayLab.
|
||||
|
||||
Dokumen ini menjadi acuan implementasi lingkungan produksi maupun
|
||||
pengembangan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Prinsip Operasional
|
||||
|
||||
- Infrastructure as Code.
|
||||
- Docker sebagai standar deployment.
|
||||
- Zero manual configuration di production.
|
||||
- Monitoring dan observability menjadi bagian dari sistem.
|
||||
- Backup dan recovery harus dipersiapkan sejak awal.
|
||||
- Deployment harus dapat diulang (repeatable).
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Environment
|
||||
|
||||
RayLab Core memiliki beberapa lingkungan:
|
||||
|
||||
- Development
|
||||
- Testing
|
||||
- Staging (opsional)
|
||||
- Production
|
||||
|
||||
Setiap environment memiliki konfigurasi yang terpisah.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Container Architecture
|
||||
|
||||
Komponen utama:
|
||||
|
||||
``` text
|
||||
raylab-core
|
||||
postgres-raylab
|
||||
redis
|
||||
```
|
||||
|
||||
Komponen pendukung:
|
||||
|
||||
``` text
|
||||
nginx-proxy-manager
|
||||
cloudflared / gateway
|
||||
homepage
|
||||
uptime-kuma
|
||||
```
|
||||
|
||||
Semua service berada pada Docker Network yang telah ditentukan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Deployment Workflow
|
||||
|
||||
``` text
|
||||
Git
|
||||
│
|
||||
▼
|
||||
Build
|
||||
│
|
||||
▼
|
||||
Test
|
||||
│
|
||||
▼
|
||||
Docker Image
|
||||
│
|
||||
▼
|
||||
Deployment
|
||||
│
|
||||
▼
|
||||
Health Check
|
||||
```
|
||||
|
||||
Deployment baru dianggap berhasil apabila health check lulus.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Configuration Management
|
||||
|
||||
- Gunakan `.env` untuk konfigurasi.
|
||||
- Secret tidak boleh di-hardcode.
|
||||
- Konfigurasi dibaca melalui Config Module.
|
||||
- File `.env.example` disediakan untuk dokumentasi.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Logging
|
||||
|
||||
Semua log menggunakan format terstruktur.
|
||||
|
||||
Minimal mencatat:
|
||||
|
||||
- Timestamp
|
||||
- Request ID
|
||||
- Level
|
||||
- Module
|
||||
- Message
|
||||
- Error (jika ada)
|
||||
|
||||
Log aplikasi dipisahkan dari log container.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Monitoring
|
||||
|
||||
Monitoring dilakukan menggunakan layanan RayLab:
|
||||
|
||||
- Uptime Kuma
|
||||
- Grafana
|
||||
- Prometheus
|
||||
|
||||
Metrik yang dipantau:
|
||||
|
||||
- CPU
|
||||
- RAM
|
||||
- Disk
|
||||
- Response Time
|
||||
- Error Rate
|
||||
- Health Endpoint
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Health Check
|
||||
|
||||
Setiap service menyediakan endpoint:
|
||||
|
||||
``` text
|
||||
GET /health
|
||||
```
|
||||
|
||||
Health check minimal memverifikasi:
|
||||
|
||||
- Database
|
||||
- Redis
|
||||
- Internal Service
|
||||
- Adapter penting
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Backup Strategy
|
||||
|
||||
Backup dilakukan secara berkala untuk:
|
||||
|
||||
- PostgreSQL
|
||||
- Docker Volume
|
||||
- Konfigurasi
|
||||
- Dokumentasi
|
||||
- Migration
|
||||
|
||||
Backup disimpan pada media penyimpanan terpisah sesuai strategi RayLab.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Disaster Recovery
|
||||
|
||||
Prosedur pemulihan minimal mencakup:
|
||||
|
||||
1. Restore database.
|
||||
2. Restore konfigurasi.
|
||||
3. Restore volume.
|
||||
4. Jalankan container.
|
||||
5. Verifikasi health check.
|
||||
|
||||
Targetnya adalah waktu pemulihan yang cepat dan terdokumentasi.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Security Baseline
|
||||
|
||||
Deployment harus memenuhi standar minimum:
|
||||
|
||||
- HTTPS
|
||||
- Secret melalui environment
|
||||
- Tidak mengekspos port yang tidak diperlukan
|
||||
- Container berjalan dengan hak akses minimum jika memungkinkan
|
||||
- Update dependency secara berkala
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Maintenance
|
||||
|
||||
Aktivitas rutin:
|
||||
|
||||
- Update dependency
|
||||
- Update Docker image
|
||||
- Review log
|
||||
- Review backup
|
||||
- Verifikasi monitoring
|
||||
- Verifikasi dokumentasi
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Operational Checklist
|
||||
|
||||
Sebelum production:
|
||||
|
||||
- Docker berjalan normal.
|
||||
- Health check lulus.
|
||||
- Backup aktif.
|
||||
- Monitoring aktif.
|
||||
- Logging aktif.
|
||||
- Dokumentasi diperbarui.
|
||||
- Migration terbaru diterapkan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Hasil Akhir Fase 10
|
||||
|
||||
Pada akhir fase ini RayLab Core memiliki standar deployment dan
|
||||
operasional yang konsisten untuk lingkungan pengembangan maupun
|
||||
produksi. Seluruh proses deployment, monitoring, backup, logging, dan
|
||||
pemeliharaan terdokumentasi sehingga sistem siap dijalankan sebagai
|
||||
layanan inti ekosistem RayLab.
|
||||
@@ -0,0 +1,205 @@
|
||||
# RayLab Core Phase 11 --- Scaling Strategy
|
||||
|
||||
## Tujuan
|
||||
|
||||
Fase 11 mendefinisikan strategi pengembangan jangka panjang RayLab Core
|
||||
agar mampu berkembang dari sistem yang melayani kebutuhan pribadi
|
||||
menjadi platform yang dapat menangani lebih banyak aplikasi, pengguna,
|
||||
layanan, dan integrasi tanpa perlu mengubah arsitektur dasarnya.
|
||||
|
||||
Dokumen ini menjadi acuan untuk menjaga skalabilitas teknis maupun
|
||||
organisasi proyek.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Prinsip Skalabilitas
|
||||
|
||||
- Bangun untuk kebutuhan saat ini, rancang untuk kebutuhan masa depan.
|
||||
- Modular sebelum distributed.
|
||||
- Scale up terlebih dahulu, scale out bila diperlukan.
|
||||
- Hindari premature optimization.
|
||||
- Pertahankan kompatibilitas ke belakang (backward compatibility) jika
|
||||
memungkinkan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Tahapan Skalabilitas
|
||||
|
||||
## Tahap 1 --- Single Server
|
||||
|
||||
Karakteristik:
|
||||
|
||||
- Satu instance RayLab Core.
|
||||
- Satu PostgreSQL.
|
||||
- Satu Redis.
|
||||
- Docker Compose.
|
||||
|
||||
Cocok untuk homelab dan pengembangan awal.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Tahap 2 --- Multi Service
|
||||
|
||||
Mulai memisahkan layanan pendukung.
|
||||
|
||||
Contoh:
|
||||
|
||||
- Database terpisah.
|
||||
- Monitoring terpisah.
|
||||
- Backup terpisah.
|
||||
- Worker background.
|
||||
|
||||
Tujuan:
|
||||
|
||||
Mengurangi coupling antar layanan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
## Tahap 3 --- Horizontal Scaling
|
||||
|
||||
Jika beban meningkat:
|
||||
|
||||
- Menjalankan beberapa instance RayLab Core.
|
||||
- Menggunakan reverse proxy atau load balancer.
|
||||
- Session dipindahkan ke Redis.
|
||||
- Stateless API menjadi syarat utama.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Modular Growth
|
||||
|
||||
Modul baru harus dapat ditambahkan tanpa mengubah modul yang sudah ada.
|
||||
|
||||
Contoh:
|
||||
|
||||
- AI
|
||||
- Notification
|
||||
- Billing
|
||||
- Home Automation
|
||||
- Marketplace Adapter
|
||||
|
||||
Integrasi dilakukan melalui service dan adapter yang sudah ada.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Adapter Expansion
|
||||
|
||||
Seluruh integrasi eksternal mengikuti pola Adapter.
|
||||
|
||||
Contoh:
|
||||
|
||||
- Nextcloud
|
||||
- Jellyfin
|
||||
- Immich
|
||||
- Gitea
|
||||
- Forgejo
|
||||
- Home Assistant
|
||||
- Ollama
|
||||
- Future services
|
||||
|
||||
Tidak ada business logic di dalam adapter.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Database Scaling
|
||||
|
||||
Strategi bertahap:
|
||||
|
||||
1. Optimasi query.
|
||||
2. Indexing.
|
||||
3. Connection pooling.
|
||||
4. Read replica (jika diperlukan).
|
||||
5. Sharding hanya jika benar-benar dibutuhkan.
|
||||
|
||||
Perubahan dilakukan bertahap berdasarkan kebutuhan nyata.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Storage Scaling
|
||||
|
||||
Storage harus mendukung penambahan kapasitas tanpa mengubah business
|
||||
logic.
|
||||
|
||||
Contoh:
|
||||
|
||||
- HDD tambahan.
|
||||
- NAS.
|
||||
- Object Storage (masa depan).
|
||||
|
||||
Storage Layer menjadi abstraksi terhadap media penyimpanan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# API Evolution
|
||||
|
||||
Strategi pengembangan API:
|
||||
|
||||
- Gunakan versioning.
|
||||
- Hindari breaking changes.
|
||||
- Tandai endpoint lama sebagai deprecated.
|
||||
- Dokumentasikan seluruh perubahan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Performance Strategy
|
||||
|
||||
Fokus optimasi:
|
||||
|
||||
- Query database.
|
||||
- Caching Redis.
|
||||
- Background Job.
|
||||
- Lazy Loading.
|
||||
- Pagination.
|
||||
- Batch Processing.
|
||||
|
||||
Optimasi dilakukan berdasarkan hasil monitoring.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Observability
|
||||
|
||||
Seiring pertumbuhan sistem:
|
||||
|
||||
- Logging terstruktur.
|
||||
- Metrics.
|
||||
- Health Check.
|
||||
- Audit.
|
||||
- Distributed tracing (jika diperlukan).
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Maintainability
|
||||
|
||||
Setiap modul harus:
|
||||
|
||||
- Memiliki dokumentasi.
|
||||
- Memiliki test.
|
||||
- Mengikuti coding convention.
|
||||
- Mengikuti layered architecture.
|
||||
|
||||
Refactoring dilakukan secara bertahap tanpa mengubah kontrak publik.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Long-Term Vision
|
||||
|
||||
RayLab Core dirancang agar dapat berkembang menjadi platform yang
|
||||
mendukung:
|
||||
|
||||
- Banyak aplikasi.
|
||||
- Banyak pengguna.
|
||||
- Banyak domain.
|
||||
- Banyak adapter.
|
||||
- Banyak layanan.
|
||||
|
||||
Dengan tetap mempertahankan satu pusat Identity & Access Management dan
|
||||
satu standar arsitektur.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Hasil Akhir Fase 11
|
||||
|
||||
Pada akhir fase ini, RayLab Core memiliki strategi skalabilitas yang
|
||||
jelas untuk pertumbuhan jangka panjang. Arsitektur yang telah dibangun
|
||||
pada fase-fase sebelumnya dapat diperluas tanpa perubahan mendasar
|
||||
sehingga sistem tetap modular, konsisten, dan mudah dipelihara.
|
||||
@@ -0,0 +1,129 @@
|
||||
# RayLab Core Phase 12 --- Future Vision & Evolution
|
||||
|
||||
## Tujuan
|
||||
|
||||
Fase 12 mendokumentasikan visi jangka panjang RayLab Core sebagai
|
||||
platform inti ekosistem RayLab. Dokumen ini menjadi panduan arah
|
||||
pengembangan di masa depan tanpa mengubah prinsip arsitektur yang telah
|
||||
ditetapkan.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Visi
|
||||
|
||||
RayLab Core dirancang sebagai pusat pengelolaan identitas, otorisasi,
|
||||
konfigurasi, penyimpanan, media, dan integrasi untuk seluruh layanan
|
||||
dalam ekosistem RayLab.
|
||||
|
||||
Prinsip utamanya adalah membangun platform yang modular, dapat
|
||||
diperluas, terdokumentasi, dan mudah dipelihara.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Sasaran Jangka Panjang
|
||||
|
||||
- Menjadi pusat Identity & Access Management (IAM).
|
||||
- Menjadi registry seluruh aplikasi RayLab.
|
||||
- Menjadi pusat konfigurasi layanan.
|
||||
- Menjadi pengelola storage dan media.
|
||||
- Menjadi fondasi integrasi seluruh aplikasi internal.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Evolusi Modul
|
||||
|
||||
Modul yang dapat ditambahkan di masa depan antara lain:
|
||||
|
||||
- Notification Center
|
||||
- Workflow Engine
|
||||
- Scheduler
|
||||
- AI Integration
|
||||
- Home Automation
|
||||
- Billing
|
||||
- Analytics
|
||||
- Search Service
|
||||
|
||||
Modul baru harus mengikuti standar Layered Architecture dan tidak
|
||||
mengubah kontrak modul yang sudah ada.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Evolusi Adapter
|
||||
|
||||
Adapter baru dapat ditambahkan untuk layanan seperti:
|
||||
|
||||
- Home Assistant
|
||||
- Ollama
|
||||
- Forgejo
|
||||
- GitHub
|
||||
- S3 Compatible Storage
|
||||
- MQTT Broker
|
||||
- Sistem pihak ketiga lainnya
|
||||
|
||||
Seluruh integrasi dilakukan melalui Adapter Layer agar business logic
|
||||
tetap independen.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Ekosistem RayLab
|
||||
|
||||
RayLab Core diharapkan menjadi fondasi bagi berbagai aplikasi, seperti:
|
||||
|
||||
- Dashboard
|
||||
- Warung Management
|
||||
- File Management
|
||||
- Media Management
|
||||
- Monitoring
|
||||
- Wiki
|
||||
- Mobile Applications
|
||||
- Future Services
|
||||
|
||||
Semua aplikasi menggunakan standar autentikasi dan otorisasi yang sama.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Standar Evolusi
|
||||
|
||||
Perubahan besar harus:
|
||||
|
||||
- Didokumentasikan melalui Architecture Decision Record (ADR).
|
||||
- Menjaga kompatibilitas jika memungkinkan.
|
||||
- Memiliki migration path yang jelas.
|
||||
- Disertai pembaruan dokumentasi dan pengujian.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Continuous Improvement
|
||||
|
||||
Pengembangan dilakukan secara berkelanjutan melalui:
|
||||
|
||||
- Refactoring berkala.
|
||||
- Peningkatan performa.
|
||||
- Evaluasi keamanan.
|
||||
- Penyempurnaan dokumentasi.
|
||||
- Otomatisasi deployment dan pengujian.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Success Criteria
|
||||
|
||||
RayLab Core dianggap berhasil apabila:
|
||||
|
||||
- Mudah dikembangkan.
|
||||
- Mudah diintegrasikan.
|
||||
- Mudah dipelihara.
|
||||
- Memiliki dokumentasi yang lengkap.
|
||||
- Memiliki kualitas kode yang konsisten.
|
||||
- Menjadi fondasi yang stabil bagi seluruh aplikasi RayLab.
|
||||
|
||||
------------------------------------------------------------------------
|
||||
|
||||
# Penutup
|
||||
|
||||
Fase ini tidak mendefinisikan fitur baru, melainkan arah pengembangan
|
||||
jangka panjang. Setiap evolusi RayLab Core harus tetap berpegang pada
|
||||
prinsip modularitas, konsistensi, keamanan, dokumentasi, dan
|
||||
maintainability yang telah ditetapkan sejak fase awal.
|
||||
|
||||
Dengan demikian, RayLab Core dapat berkembang seiring kebutuhan tanpa
|
||||
kehilangan stabilitas arsitekturnya.
|
||||
@@ -0,0 +1,149 @@
|
||||
Ringkasan
|
||||
|
||||
Dokumen ini menjelaskan struktur folder proyek, alur kerja (workflow) pengembangan, dan bagaimana data diproses dari UI sampai ke penyimpanan (data flow). Tujuan: memberi panduan onboarding cepat untuk developer agar konsisten dengan arsitektur RayLab Core.
|
||||
|
||||
1. Struktur Folder (penjelasan)
|
||||
|
||||
```text Docs/Structure-Workflow-DataFlow.md
|
||||
raylab-core/
|
||||
├── docker/ # Docker compose, konfigurasi container
|
||||
├── prisma/ # Prisma schema, migrations, seed
|
||||
├── docs/ # Dokumentasi proyek (arsitektur, ADR, panduan)
|
||||
├── scripts/ # Script helper (migrate, seed, build)
|
||||
├── src/ # Source code aplikasi
|
||||
│ ├── main.ts # Bootstrap aplikasi
|
||||
│ ├── app.module.ts # Root module (dependensi utama)
|
||||
│ ├── common/ # Guards, filters, interceptors, middleware, logger, utils
|
||||
│ ├── config/ # ConfigModule, ConfigService (env parsing)
|
||||
│ ├── modules/ # Domain modules (identity, authorization, media, ...)
|
||||
│ │ ├── identity/ # Example: controllers/, services/, repositories/, dto/, entities/
|
||||
│ │ └── ...
|
||||
│ ├── adapters/ # External integrations (Nextcloud, Jellyfin, Immich)
|
||||
│ └── shared/ # Shared services (PrismaService, event bus, constants)
|
||||
├── tests/ # Unit, integration, e2e
|
||||
├── .env.example
|
||||
├── docker-compose.yml
|
||||
└── README.md
|
||||
```
|
||||
|
||||
Penjelasan singkat folder penting:
|
||||
- src/modules: setiap module merepresentasikan domain bisnis. Contoh: identity, authorization, registry. Module berisi subfolder terstruktur: controllers, services, domain, repositories, dto, entities, interfaces, events.
|
||||
- src/common: komponen yang dipakai lintas module, seperti exception filters, authentication guards, middleware request-id, logging interceptor.
|
||||
- src/adapters: semua integrasi eksternal hanya lewat adapter (no business logic). Adapter expose interface yang dipakai application service.
|
||||
- src/shared: service bersama seperti PrismaService (DB client), event bus, constant classes.
|
||||
- prisma/: schema prisma, migrations — migration menjadi sumber kebenaran struktur DB.
|
||||
|
||||
2. Development Workflow (Ringkas)
|
||||
|
||||
- Branching:
|
||||
- main: selalu stabil dan dapat direlease
|
||||
- feature/*, fix/*, refactor/* untuk pekerjaan terpisah
|
||||
- Commit convention: type(scope): description (feat, fix, docs, test, refactor)
|
||||
- PR checklist: build ok, unit tests ok, integration tests ok, dokumentasi diupdate, migration tersedia jika perlu
|
||||
- CI Pipeline: lint → test → build → prisma migrate (dry-run) → docker build
|
||||
- Release: tag versi (semver), build docker image, deploy via docker compose / orchestrator
|
||||
|
||||
3. Request & Data Flow — dari UI sampai Database
|
||||
|
||||
Langkah umum (singkat):
|
||||
|
||||
UI (web/mobile/cli)
|
||||
↓ (HTTP request JSON + headers)
|
||||
API Gateway / Reverse Proxy (optional)
|
||||
↓
|
||||
NestJS Controller (src/modules/.../controllers)
|
||||
- Validasi ringan (DTO + Pipes)
|
||||
- Mapping request → DTO
|
||||
- Menambahkan metadata (requestId, auth user)
|
||||
↓
|
||||
Application Service (src/modules/.../services)
|
||||
- Implementasi use-case / orchestration
|
||||
- Koordinasi Domain Services, Repositories, Adapters
|
||||
- Menjalankan transaksi jika perlu
|
||||
- Men-trigger audit/event/background job
|
||||
↓
|
||||
Domain Service / Domain Logic (src/modules/.../domain atau services)
|
||||
- Semua aturan bisnis utama ditempatkan di sini
|
||||
- Validasi domain, rules, invariants
|
||||
↓
|
||||
Repository (src/modules/.../repositories)
|
||||
- Akses database (Prisma client) — Save, Find, Update, Delete
|
||||
- Tidak ada business logic berat di sini
|
||||
↓
|
||||
Database (PostgreSQL)
|
||||
|
||||
Respon balik mengikuti format standar API (success/error)
|
||||
|
||||
Contoh alur lebih rinci (Create User):
|
||||
1. UI POST /api/v1/users {email, displayName, password}
|
||||
2. Controller menerima request, Pipe class-validator validasi DTO
|
||||
3. Controller memanggil UserService.create(createUserDto, ctx)
|
||||
4. UserService melakukan business logic: cek duplikasi email (via UserRepository), hash password (di service), mempersiapkan data user
|
||||
5. UserService memanggil UserRepository.create(data)
|
||||
6. Repository menggunakan PrismaClient untuk menyimpan ke tabel identity.users
|
||||
7. Setelah sukses, UserService men-trigger AuditService.log(...) dan mengembalikan DTO respon
|
||||
8. Controller membungkus respon ke format standar dan mengembalikan ke client
|
||||
|
||||
4. Non-blocking / Side Effects
|
||||
|
||||
- Audit: dipicu oleh Application Service setelah perubahan penting; bisa synchronous atau pushed ke queue
|
||||
- Events: domain events dapat dipublish ke event bus (in-memory atau Redis) untuk worker/background processing
|
||||
- Background Jobs: proses berat (email, refresh library, thumbnail generation) diproses oleh worker (BullMQ/Redis)
|
||||
- Cache: gunakan Redis untuk session, rate-limiting, cache query hasil expensive
|
||||
|
||||
5. Error Handling & Observability
|
||||
|
||||
- Request ID: middleware menambahkan X-Request-ID jika belum ada; dipakai di log dan audit
|
||||
- Structured logging: Pino dengan fields {timestamp, level, module, requestId, message}
|
||||
- Error response standard:
|
||||
|
||||
```json Docs/Structure-Workflow-DataFlow.md
|
||||
{
|
||||
"success": false,
|
||||
"error": { "code": "USER_NOT_FOUND", "message": "User not found" }
|
||||
}
|
||||
```
|
||||
|
||||
- Success response standard:
|
||||
|
||||
```json Docs/Structure-Workflow-DataFlow.md
|
||||
{
|
||||
"success": true,
|
||||
"data": {},
|
||||
"meta": { "requestId": "...", "timestamp": "..." }
|
||||
}
|
||||
```
|
||||
|
||||
- Monitoring: expose /health yang memeriksa koneksi DB, Redis, adapter penting. Integrasikan metrics untuk Prometheus/Grafana.
|
||||
|
||||
6. Best Practices & Rules
|
||||
|
||||
- Controller tipis: hanya validasi + mapping + panggil service
|
||||
- Business logic hanya di Domain/Service
|
||||
- Repository hanya query DB (Prisma)
|
||||
- Adapter untuk komunikasi eksternal tanpa business logic
|
||||
- Semua perubahan DB melalui migration (Prisma Migrate)
|
||||
- Gunakan DTO + class-validator untuk input validation
|
||||
- Gunakan UUID v7 untuk primary key, timestamps created_at/updated_at/deleted_at
|
||||
- Soft delete: gunakan deleted_at
|
||||
- Semua endpoint harus terdokumentasi di Swagger/OpenAPI
|
||||
|
||||
7. Contoh file lokasi logis untuk use-case "Create User"
|
||||
|
||||
- src/modules/identity/controllers/users.controller.ts (HTTP layer)
|
||||
- src/modules/identity/dto/create-user.dto.ts (validation)
|
||||
- src/modules/identity/services/user.service.ts (application service)
|
||||
- src/modules/identity/domain/user.domain.ts (domain rules)
|
||||
- src/modules/identity/repositories/user.repository.ts (prisma queries)
|
||||
- src/shared/prisma.service.ts (prisma client)
|
||||
- src/common/middleware/request-id.middleware.ts (request id)
|
||||
- src/modules/audit/services/audit.service.ts (audit logging)
|
||||
|
||||
Penutup
|
||||
|
||||
Dokumen ini menjadi ringkasan teknis untuk struktur kode dan alur data. Jika Anda ingin, saya bisa:
|
||||
- Menggenerate file contoh (controller/service/repository/dto) untuk use-case Create User sesuai struktur di atas.
|
||||
- Membuat diagram sequence (plantuml) untuk alur request.
|
||||
- Menambahkan template middleware, audit service, dan contoh Prisma model untuk User.
|
||||
|
||||
Pilih aksi selanjutnya jika ingin saya buatkan implementasi contoh secara otomatis.
|
||||
Reference in New Issue
Block a user