RayLab-Core/Docs/Structure-Workflow-DataFlow.md

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)

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

9. 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:

{
  "success": false,
  "error": { "code": "USER_NOT_FOUND", "message": "User not found" }
}

• Success response standard:

{
  "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.