149 lines
7.0 KiB
Markdown
149 lines
7.0 KiB
Markdown
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. |