Init

Docs/Phase-05-Data-Architecture.md

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