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.