From 3efac50f395b90bb1ce02c256d6be88e0583b39f Mon Sep 17 00:00:00 2001 From: "Mr. Rayyan" <60314224+RayyanHermanto@users.noreply.github.com> Date: Thu, 30 Jul 2026 09:41:42 +0700 Subject: [PATCH] Init --- .gitignore | 1 + Docs/Phase-01-Module-Design.md | 208 ++++++++++++ Docs/Phase-02-Domain-Model.md | 218 ++++++++++++ Docs/Phase-03-Layered-Architecture.md | 237 +++++++++++++ Docs/Phase-04-Technical-Foundation.md | 311 ++++++++++++++++++ Docs/Phase-05-Data-Architecture.md | 310 +++++++++++++++++ Docs/Phase-06-API-Architecture.md | 289 ++++++++++++++++ Docs/Phase-07-Project-Structure.md | 249 ++++++++++++++ Docs/Phase-08-Development-Workflow.md | 267 +++++++++++++++ Docs/Phase-09-Implementation-Roadmap.md | 249 ++++++++++++++ Docs/Phase-10-Deployment-Operations.md | 221 +++++++++++++ Docs/Phase-11-Scaling-Strategy.md | 205 ++++++++++++ Docs/Phase-12-Future-Vision-Evolution.md | 129 ++++++++ Docs/Structure-Workflow-DataFlow.md | 149 +++++++++ Initial-Structure-and-TODO.md | 1 + docker/docker-compose.yml | 12 + package.json | 56 ++++ prisma/migrations/.gitkeep | 0 prisma/schema.prisma | 10 + prisma/seed.ts | 1 + scripts/.gitkeep | 0 src/adapters/.gitkeep | 0 src/adapters/immich/.gitkeep | 0 src/adapters/jellyfin/.gitkeep | 0 src/adapters/nextcloud/.gitkeep | 0 src/app.module.ts | 1 + src/common/.gitkeep | 0 src/common/auth/.gitkeep | 0 src/common/filters/.gitkeep | 0 src/common/guards/.gitkeep | 0 src/common/interceptors/.gitkeep | 0 src/common/logger/.gitkeep | 0 src/common/middleware/.gitkeep | 0 src/common/utils/.gitkeep | 0 src/config/.gitkeep | 0 src/config/config.module.ts | 1 + src/config/config.service.ts | 1 + src/main.ts | 1 + src/modules/.gitkeep | 0 src/modules/audit/.gitkeep | 0 src/modules/authorization/.gitkeep | 0 src/modules/configuration/.gitkeep | 0 src/modules/dashboard/.gitkeep | 0 src/modules/health/.gitkeep | 0 src/modules/identity/.gitkeep | 0 src/modules/identity/controllers/.gitkeep | 0 .../identity/controllers/users.controller.ts | 20 ++ src/modules/identity/domain/.gitkeep | 0 src/modules/identity/dto/.gitkeep | 0 src/modules/identity/dto/create-user.dto.ts | 1 + src/modules/identity/dto/update-user.dto.ts | 1 + src/modules/identity/entities/.gitkeep | 0 src/modules/identity/entities/user.entity.ts | 9 + src/modules/identity/events/.gitkeep | 0 src/modules/identity/identity.module.ts | 1 + src/modules/identity/interfaces/.gitkeep | 0 .../identity/interfaces/iuser.service.ts | 3 + src/modules/identity/mappers/.gitkeep | 0 src/modules/identity/repositories/.gitkeep | 0 .../identity/repositories/user.repository.ts | 26 ++ src/modules/identity/services/.gitkeep | 0 src/modules/identity/services/user.service.ts | 16 + src/modules/media/.gitkeep | 0 src/modules/registry/.gitkeep | 0 src/modules/storage/.gitkeep | 0 src/shared/.gitkeep | 0 src/shared/prisma.service.ts | 13 + tests/e2e/.gitkeep | 0 tests/integration/.gitkeep | 0 tests/unit/.gitkeep | 0 70 files changed, 3217 insertions(+) create mode 100644 .gitignore create mode 100644 Docs/Phase-01-Module-Design.md create mode 100644 Docs/Phase-02-Domain-Model.md create mode 100644 Docs/Phase-03-Layered-Architecture.md create mode 100644 Docs/Phase-04-Technical-Foundation.md create mode 100644 Docs/Phase-05-Data-Architecture.md create mode 100644 Docs/Phase-06-API-Architecture.md create mode 100644 Docs/Phase-07-Project-Structure.md create mode 100644 Docs/Phase-08-Development-Workflow.md create mode 100644 Docs/Phase-09-Implementation-Roadmap.md create mode 100644 Docs/Phase-10-Deployment-Operations.md create mode 100644 Docs/Phase-11-Scaling-Strategy.md create mode 100644 Docs/Phase-12-Future-Vision-Evolution.md create mode 100644 Docs/Structure-Workflow-DataFlow.md create mode 100644 Initial-Structure-and-TODO.md create mode 100644 docker/docker-compose.yml create mode 100644 package.json create mode 100644 prisma/migrations/.gitkeep create mode 100644 prisma/schema.prisma create mode 100644 prisma/seed.ts create mode 100644 scripts/.gitkeep create mode 100644 src/adapters/.gitkeep create mode 100644 src/adapters/immich/.gitkeep create mode 100644 src/adapters/jellyfin/.gitkeep create mode 100644 src/adapters/nextcloud/.gitkeep create mode 100644 src/app.module.ts create mode 100644 src/common/.gitkeep create mode 100644 src/common/auth/.gitkeep create mode 100644 src/common/filters/.gitkeep create mode 100644 src/common/guards/.gitkeep create mode 100644 src/common/interceptors/.gitkeep create mode 100644 src/common/logger/.gitkeep create mode 100644 src/common/middleware/.gitkeep create mode 100644 src/common/utils/.gitkeep create mode 100644 src/config/.gitkeep create mode 100644 src/config/config.module.ts create mode 100644 src/config/config.service.ts create mode 100644 src/main.ts create mode 100644 src/modules/.gitkeep create mode 100644 src/modules/audit/.gitkeep create mode 100644 src/modules/authorization/.gitkeep create mode 100644 src/modules/configuration/.gitkeep create mode 100644 src/modules/dashboard/.gitkeep create mode 100644 src/modules/health/.gitkeep create mode 100644 src/modules/identity/.gitkeep create mode 100644 src/modules/identity/controllers/.gitkeep create mode 100644 src/modules/identity/controllers/users.controller.ts create mode 100644 src/modules/identity/domain/.gitkeep create mode 100644 src/modules/identity/dto/.gitkeep create mode 100644 src/modules/identity/dto/create-user.dto.ts create mode 100644 src/modules/identity/dto/update-user.dto.ts create mode 100644 src/modules/identity/entities/.gitkeep create mode 100644 src/modules/identity/entities/user.entity.ts create mode 100644 src/modules/identity/events/.gitkeep create mode 100644 src/modules/identity/identity.module.ts create mode 100644 src/modules/identity/interfaces/.gitkeep create mode 100644 src/modules/identity/interfaces/iuser.service.ts create mode 100644 src/modules/identity/mappers/.gitkeep create mode 100644 src/modules/identity/repositories/.gitkeep create mode 100644 src/modules/identity/repositories/user.repository.ts create mode 100644 src/modules/identity/services/.gitkeep create mode 100644 src/modules/identity/services/user.service.ts create mode 100644 src/modules/media/.gitkeep create mode 100644 src/modules/registry/.gitkeep create mode 100644 src/modules/storage/.gitkeep create mode 100644 src/shared/.gitkeep create mode 100644 src/shared/prisma.service.ts create mode 100644 tests/e2e/.gitkeep create mode 100644 tests/integration/.gitkeep create mode 100644 tests/unit/.gitkeep diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3c3629e --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules diff --git a/Docs/Phase-01-Module-Design.md b/Docs/Phase-01-Module-Design.md new file mode 100644 index 0000000..880e243 --- /dev/null +++ b/Docs/Phase-01-Module-Design.md @@ -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. diff --git a/Docs/Phase-02-Domain-Model.md b/Docs/Phase-02-Domain-Model.md new file mode 100644 index 0000000..549c84b --- /dev/null +++ b/Docs/Phase-02-Domain-Model.md @@ -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 diff --git a/Docs/Phase-03-Layered-Architecture.md b/Docs/Phase-03-Layered-Architecture.md new file mode 100644 index 0000000..45e7bb8 --- /dev/null +++ b/Docs/Phase-03-Layered-Architecture.md @@ -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. diff --git a/Docs/Phase-04-Technical-Foundation.md b/Docs/Phase-04-Technical-Foundation.md new file mode 100644 index 0000000..6c42035 --- /dev/null +++ b/Docs/Phase-04-Technical-Foundation.md @@ -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. diff --git a/Docs/Phase-05-Data-Architecture.md b/Docs/Phase-05-Data-Architecture.md new file mode 100644 index 0000000..e5a9976 --- /dev/null +++ b/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. diff --git a/Docs/Phase-06-API-Architecture.md b/Docs/Phase-06-API-Architecture.md new file mode 100644 index 0000000..a843b1c --- /dev/null +++ b/Docs/Phase-06-API-Architecture.md @@ -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. diff --git a/Docs/Phase-07-Project-Structure.md b/Docs/Phase-07-Project-Structure.md new file mode 100644 index 0000000..b171fd3 --- /dev/null +++ b/Docs/Phase-07-Project-Structure.md @@ -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. diff --git a/Docs/Phase-08-Development-Workflow.md b/Docs/Phase-08-Development-Workflow.md new file mode 100644 index 0000000..f14fea5 --- /dev/null +++ b/Docs/Phase-08-Development-Workflow.md @@ -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. diff --git a/Docs/Phase-09-Implementation-Roadmap.md b/Docs/Phase-09-Implementation-Roadmap.md new file mode 100644 index 0000000..ee3fba6 --- /dev/null +++ b/Docs/Phase-09-Implementation-Roadmap.md @@ -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. diff --git a/Docs/Phase-10-Deployment-Operations.md b/Docs/Phase-10-Deployment-Operations.md new file mode 100644 index 0000000..6a2dfdd --- /dev/null +++ b/Docs/Phase-10-Deployment-Operations.md @@ -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. diff --git a/Docs/Phase-11-Scaling-Strategy.md b/Docs/Phase-11-Scaling-Strategy.md new file mode 100644 index 0000000..586dc7a --- /dev/null +++ b/Docs/Phase-11-Scaling-Strategy.md @@ -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. diff --git a/Docs/Phase-12-Future-Vision-Evolution.md b/Docs/Phase-12-Future-Vision-Evolution.md new file mode 100644 index 0000000..9c713bf --- /dev/null +++ b/Docs/Phase-12-Future-Vision-Evolution.md @@ -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. diff --git a/Docs/Structure-Workflow-DataFlow.md b/Docs/Structure-Workflow-DataFlow.md new file mode 100644 index 0000000..aacfa45 --- /dev/null +++ b/Docs/Structure-Workflow-DataFlow.md @@ -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. \ No newline at end of file diff --git a/Initial-Structure-and-TODO.md b/Initial-Structure-and-TODO.md new file mode 100644 index 0000000..76c3860 --- /dev/null +++ b/Initial-Structure-and-TODO.md @@ -0,0 +1 @@ +// REMOVED: file content deleted per user request diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml new file mode 100644 index 0000000..bfad804 --- /dev/null +++ b/docker/docker-compose.yml @@ -0,0 +1,12 @@ +# placeholder docker-compose (to be filled later) +version: '3.8' +services: + app: + image: node:18 + command: echo "replace with actual service" + + postgres: + image: postgres:15 + + redis: + image: redis:7 diff --git a/package.json b/package.json new file mode 100644 index 0000000..d8b9082 --- /dev/null +++ b/package.json @@ -0,0 +1,56 @@ +{ + "name": "raylab-core", + "version": "0.1.0", + "private": true, + "description": "RayLab Core - Identity & Platform services", + "author": "RayLab", + "license": "MIT", + "engines": { + "node": ">=18.0.0" + }, + "scripts": { + "start": "node dist/main.js", + "start:dev": "ts-node-dev --respawn --pretty --transpile-only src/main.ts", + "build": "tsc -p tsconfig.json", + "lint": "eslint . --ext .ts", + "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"", + "test": "jest", + "test:watch": "jest --watch", + "prisma:generate": "prisma generate", + "prisma:migrate": "prisma migrate dev", + "prisma:studio": "prisma studio", + "prisma:seed": "ts-node prisma/seed.ts" + }, + "dependencies": { + "@nestjs/common": "^10.0.0", + "@nestjs/core": "^10.0.0", + "@nestjs/platform-express": "^10.0.0", + "@nestjs/config": "^3.0.0", + "@nestjs/swagger": "^6.0.0", + "class-transformer": "^0.5.1", + "class-validator": "^0.14.0", + "reflect-metadata": "^0.1.13", + "rxjs": "^7.8.0", + "swagger-ui-express": "^4.6.3", + "@prisma/client": "^5.0.0", + "pino": "^8.0.0", + "dotenv": "^16.0.0" + }, + "devDependencies": { + "@types/node": "^20.0.0", + "@types/swagger-ui-express": "^4.1.4", + "typescript": "^5.1.0", + "ts-node": "^10.9.1", + "ts-node-dev": "^2.0.0", + "prisma": "^5.0.0", + "eslint": "^8.0.0", + "@typescript-eslint/parser": "^6.0.0", + "@typescript-eslint/eslint-plugin": "^6.0.0", + "prettier": "^2.8.0", + "jest": "^29.0.0", + "ts-jest": "^29.0.0", + "@types/jest": "^29.0.0", + "supertest": "^6.3.0", + "@types/supertest": "^2.0.12" + } +} diff --git a/prisma/migrations/.gitkeep b/prisma/migrations/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/prisma/schema.prisma b/prisma/schema.prisma new file mode 100644 index 0000000..4561d42 --- /dev/null +++ b/prisma/schema.prisma @@ -0,0 +1,10 @@ +// Prisma schema placeholder +// Define models in implementation phase +generator client { + provider = "prisma-client-js" +} + +datasource db { + provider = "postgresql" + url = env("DATABASE_URL") +} diff --git a/prisma/seed.ts b/prisma/seed.ts new file mode 100644 index 0000000..6107de9 --- /dev/null +++ b/prisma/seed.ts @@ -0,0 +1 @@ +// prisma seed placeholder diff --git a/scripts/.gitkeep b/scripts/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/adapters/.gitkeep b/src/adapters/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/adapters/immich/.gitkeep b/src/adapters/immich/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/adapters/jellyfin/.gitkeep b/src/adapters/jellyfin/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/adapters/nextcloud/.gitkeep b/src/adapters/nextcloud/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/app.module.ts b/src/app.module.ts new file mode 100644 index 0000000..ea5bc5a --- /dev/null +++ b/src/app.module.ts @@ -0,0 +1 @@ +// placeholder app.module.ts diff --git a/src/common/.gitkeep b/src/common/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/common/auth/.gitkeep b/src/common/auth/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/common/filters/.gitkeep b/src/common/filters/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/common/guards/.gitkeep b/src/common/guards/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/common/interceptors/.gitkeep b/src/common/interceptors/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/common/logger/.gitkeep b/src/common/logger/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/common/middleware/.gitkeep b/src/common/middleware/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/common/utils/.gitkeep b/src/common/utils/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/config/.gitkeep b/src/config/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/config/config.module.ts b/src/config/config.module.ts new file mode 100644 index 0000000..7bc6f22 --- /dev/null +++ b/src/config/config.module.ts @@ -0,0 +1 @@ +// placeholder config.module.ts diff --git a/src/config/config.service.ts b/src/config/config.service.ts new file mode 100644 index 0000000..07d48b3 --- /dev/null +++ b/src/config/config.service.ts @@ -0,0 +1 @@ +// placeholder config.service.ts diff --git a/src/main.ts b/src/main.ts new file mode 100644 index 0000000..be7e1f9 --- /dev/null +++ b/src/main.ts @@ -0,0 +1 @@ +// placeholder main.ts diff --git a/src/modules/.gitkeep b/src/modules/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/audit/.gitkeep b/src/modules/audit/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/authorization/.gitkeep b/src/modules/authorization/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/configuration/.gitkeep b/src/modules/configuration/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/dashboard/.gitkeep b/src/modules/dashboard/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/health/.gitkeep b/src/modules/health/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/identity/.gitkeep b/src/modules/identity/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/identity/controllers/.gitkeep b/src/modules/identity/controllers/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/identity/controllers/users.controller.ts b/src/modules/identity/controllers/users.controller.ts new file mode 100644 index 0000000..cd2f311 --- /dev/null +++ b/src/modules/identity/controllers/users.controller.ts @@ -0,0 +1,20 @@ +import { Controller, Get, Param } from '@nestjs/common'; +import { ApiTags, ApiOperation } from '@nestjs/swagger'; +import { UserService } from '../services/user.service'; + +@ApiTags('users') +@Controller('api/v1/users') +export class UsersController { + constructor(private readonly userService: UserService) {} + + @Get(':id') + @ApiOperation({ summary: 'Get user by id' }) + async findById(@Param('id') id: string) { + const data = await this.userService.findById(id); + return { + success: true, + data, + meta: {}, + }; + } +} diff --git a/src/modules/identity/domain/.gitkeep b/src/modules/identity/domain/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/identity/dto/.gitkeep b/src/modules/identity/dto/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/identity/dto/create-user.dto.ts b/src/modules/identity/dto/create-user.dto.ts new file mode 100644 index 0000000..76c3860 --- /dev/null +++ b/src/modules/identity/dto/create-user.dto.ts @@ -0,0 +1 @@ +// REMOVED: file content deleted per user request diff --git a/src/modules/identity/dto/update-user.dto.ts b/src/modules/identity/dto/update-user.dto.ts new file mode 100644 index 0000000..76c3860 --- /dev/null +++ b/src/modules/identity/dto/update-user.dto.ts @@ -0,0 +1 @@ +// REMOVED: file content deleted per user request diff --git a/src/modules/identity/entities/.gitkeep b/src/modules/identity/entities/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/identity/entities/user.entity.ts b/src/modules/identity/entities/user.entity.ts new file mode 100644 index 0000000..ddd4e55 --- /dev/null +++ b/src/modules/identity/entities/user.entity.ts @@ -0,0 +1,9 @@ +export class UserEntity { + id: string; + email: string; + displayName: string; + metadata?: Record; + createdAt: Date; + updatedAt: Date; + deletedAt?: Date | null; +} diff --git a/src/modules/identity/events/.gitkeep b/src/modules/identity/events/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/identity/identity.module.ts b/src/modules/identity/identity.module.ts new file mode 100644 index 0000000..76c3860 --- /dev/null +++ b/src/modules/identity/identity.module.ts @@ -0,0 +1 @@ +// REMOVED: file content deleted per user request diff --git a/src/modules/identity/interfaces/.gitkeep b/src/modules/identity/interfaces/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/identity/interfaces/iuser.service.ts b/src/modules/identity/interfaces/iuser.service.ts new file mode 100644 index 0000000..4665547 --- /dev/null +++ b/src/modules/identity/interfaces/iuser.service.ts @@ -0,0 +1,3 @@ +export interface IUserService { + findById(id: string): Promise; +} diff --git a/src/modules/identity/mappers/.gitkeep b/src/modules/identity/mappers/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/identity/repositories/.gitkeep b/src/modules/identity/repositories/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/identity/repositories/user.repository.ts b/src/modules/identity/repositories/user.repository.ts new file mode 100644 index 0000000..3a86965 --- /dev/null +++ b/src/modules/identity/repositories/user.repository.ts @@ -0,0 +1,26 @@ +import { Injectable } from '@nestjs/common'; +import { PrismaService } from '../../../shared/prisma.service'; + +@Injectable() +export class UserRepository { + constructor(private readonly prisma: PrismaService) {} + + async findById(id: string) { + const user = await this.prisma.user.findUnique({ + where: { id }, + }); + + if (!user) return null; + + // map DB fields (snake_case) to camelCase entity + return { + id: user.id, + email: user.email, + displayName: (user as any).display_name ?? (user as any).displayName ?? null, + metadata: (user as any).metadata ?? {}, + createdAt: (user as any).created_at ?? (user as any).createdAt, + updatedAt: (user as any).updated_at ?? (user as any).updatedAt, + deletedAt: (user as any).deleted_at ?? (user as any).deletedAt, + }; + } +} diff --git a/src/modules/identity/services/.gitkeep b/src/modules/identity/services/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/identity/services/user.service.ts b/src/modules/identity/services/user.service.ts new file mode 100644 index 0000000..5437616 --- /dev/null +++ b/src/modules/identity/services/user.service.ts @@ -0,0 +1,16 @@ +import { Injectable, NotFoundException } from '@nestjs/common'; +import { UserRepository } from '../repositories/user.repository'; +import { IUserService } from '../interfaces/iuser.service'; + +@Injectable() +export class UserService implements IUserService { + constructor(private readonly userRepository: UserRepository) {} + + async findById(id: string) { + const user = await this.userRepository.findById(id); + if (!user) { + throw new NotFoundException('User not found'); + } + return user; + } +} diff --git a/src/modules/media/.gitkeep b/src/modules/media/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/registry/.gitkeep b/src/modules/registry/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/modules/storage/.gitkeep b/src/modules/storage/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/shared/.gitkeep b/src/shared/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/shared/prisma.service.ts b/src/shared/prisma.service.ts new file mode 100644 index 0000000..bb6565f --- /dev/null +++ b/src/shared/prisma.service.ts @@ -0,0 +1,13 @@ +import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common'; +import { PrismaClient } from '@prisma/client'; + +@Injectable() +export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy { + async onModuleInit() { + await this.$connect(); + } + + async onModuleDestroy() { + await this.$disconnect(); + } +} diff --git a/tests/e2e/.gitkeep b/tests/e2e/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/integration/.gitkeep b/tests/integration/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/tests/unit/.gitkeep b/tests/unit/.gitkeep new file mode 100644 index 0000000..e69de29