Skip to main content

Datacore Extension Turbo Monorepo

⚠️ Wajib: package manager pnpm dan Node.js minimal v22 (disarankan 22.x). Versi lebih rendah (mis. 16) akan gagal karena ketergantungan crypto.randomUUID/lib lainnya.

1. Instalasi (wajib duluan)​

pnpm install

Pastikan .env terisi sebelum menjalankan atau build Docker.

2. Apps & Fungsi​

  • api: REST API utama (NestJS) untuk fitur CMMS/DMS/core.
  • docs: Portal dokumentasi (Docusaurus) untuk markdown project docs.
  • worker-issue: Issue generator (CDC → schedule/check → publish issue).
  • worker-common: Worker utilitas (KV cache generator, submission publisher, workflow-email stub).
  • worker-etl: Worker ETL state-handler (consume NATS/MQTT, trigger workflow submission).
  • worker-workflow: Worker cross-workflow (service khusus lintas workflow).
  • packages/lib: Library bersama (auth, client, database, service, util) dipakai semua app.

3. Topologi (wireframe)​

 External Clients (HTTP)
          |
          v
   +-------------+
   |    API      |  REST, Swagger
   | (apps/api)  |  uses packages/lib
   +------+------+-----------------------+
          |                              |
   DB / HTTP clients              NATS / Streams
          |                              |
          |                              |
          |                     +-----------------------+
          |                     | (producers/feeds)     |
          |                     +-----------+-----------+
          |                                 |
          |                                 v
   +------+---------------------------------+---------------------------+
   |              Workers (mandiri, subscribe/produce)                  |
   | +------------+  +----------------+  +----------------------+       |
   | | worker-    |  | worker-common  |  | worker-etl           |  ...  |
   | | issue      |  | (kv cache,     |  | (state-handler, ETL) |       |
   | | (ingest,   |  | submission pub)|  +----------------------+       |
   | | schedule)  |  +----------------+                                 |
   | +------------+                                                    |
   +-------------------------------------------------------------------+
                     Semua worker & API memakai packages/lib

4. Struktur Folder​

apps/
  api/
  documentation/
  worker-issue/
  worker-common/
  worker-etl/
  worker-workflow/
packages/
  lib/               # shared library
  • App baru: buat di apps/<nama-app>/src, tambah tsconfig.json extend root, package.json untuk skrip dev/build/docker, dan alias di tsconfig.json root jika perlu.
  • Shared kode taruh di packages/lib agar tidak saling import antar app secara langsung.

5. Standar Dokumentasi Context (Wajib)​

  • Setiap context wajib punya folder docs dan minimal 1 file markdown.
  • Portal apps/documentation hanya mengindeks file .md/.mdx yang ada di dalam folder bernama docs.
  • Pola menu docs:
    • apps: nama app > nama context
    • packages/lib: menu memakai nama parent tepat di atas folder docs (nama context)

5.1 Lokasi folder docs​

Untuk context di app:

apps/<nama-app>/src/<nama-context>/docs/

Untuk context di packages/lib:

packages/lib/src/.../<nama-context>/docs/

5.2 Isi minimum per context​

Di dalam docs/, minimal harus ada:

  • STRUCTURE-RULES.md (aturan struktur folder, boundaries, naming).
  • index.md atau <context>-system-behavior.md (alur utama/behavior).

Jika context terkait business flow/data model, tambahkan:

  • prd.md (tujuan, scope, alur bisnis, acceptance criteria).
  • erd.md (entitas, relasi, constraint penting).

5.3 Checklist kualitas dokumen​

  • Jelaskan tujuan context dan tanggung jawab utamanya.
  • Jelaskan input/output, trigger, dan alur eksekusi.
  • Jelaskan dependency penting (DB, NATS, API eksternal, scheduler).
  • Jelaskan error handling, edge case, dan asumsi penting.
  • Sertakan link/path kode utama yang relevan.
  • Gunakan flowchart Mermaid minimal 1 diagram untuk alur utama.
  • Jelaskan payload input dan output dalam bentuk tabel.

5.4 Standar penomoran dokumen (baku)​

  • Judul dokumen: # <Title> (tanpa angka).
  • Bab utama: ## 1. <Nama Bab>, ## 2. <Nama Bab>, dst.
  • Sub-bab: ### 1.1 <Nama Sub-bab>, ### 1.2 <Nama Sub-bab>, dst.
  • Turunan berikutnya: #### 1.1.1 <Nama Sub-sub-bab> bila diperlukan.
  • Nomor harus konsisten dan berurutan.

5.5 Ready Prompt: System Behavior​

Gunakan prompt ini untuk menghasilkan dokumentasi system behavior langsung dari kode yang ada: Setiap context dokumentasi wajib memiliki dua dokumen utama:

  • STRUCTURE-RULES.md
  • <context>-system-behavior.md
Kamu adalah software engineer yang sedang membuat dokumentasi teknis berbasis source code.

Tugas:
1) Analisis context di path: <CONTEXT_PATH>
2) Baca service utama, module, consumer/handler, DTO/type, util penting, dan test (jika ada)
3) Buat dokumentasi file: <OUTPUT_DOC_PATH>
4) Jangan mengarang behavior; semua isi harus bisa ditelusuri ke kode

Format dokumen yang wajib:
- Title
- 1. System Behavior
- 1.1 Tujuan Context
- 1.2 Scope
- 2. Komponen Utama (kelas/fungsi + peran)
- 3. Alur System Behavior (happy path, step-by-step)
- 4. Flowchart (Mermaid) -> minimal 1 diagram
- 5. Trigger & Input (API/event/scheduler + payload penting)
- 5.1 Detail Input (tabel)
- 6. Output & Side Effects (DB update, publish event, external call)
- 6.1 Detail Output (tabel)
- 7. Error Handling
- 8. Edge Cases
- 9. Dependency & Integrasi
- 10. Data Model yang relevan (ringkas, referensi ke ERD/entitas)
- 11. Referensi Kode (path file yang dipakai)

Aturan:
- Bahasa Indonesia, teknis, ringkas, tidak marketing.
- Sertakan path file konkret untuk tiap poin penting.
- Jika ada asumsi, tulis eksplisit sebagai asumsi.
- Jika ada gap/ambigu, buat section "Open Questions".
- Judul utama wajib `# <Title>` tanpa angka.
- Penomoran heading wajib konsisten (contoh: `## 1...`, `### 1.1...`).
- Jika context punya input/output, wajib jelaskan dalam tabel terpisah.
- Setiap context wajib punya `STRUCTURE-RULES.md` dan `<context>-system-behavior.md`.
- Jika salah satu belum ada, buat/lengkapi dulu sebelum finalisasi dokumentasi.

Contoh nilai placeholder:

  • <CONTEXT_PATH>: apps/worker-workflow/src/cross-workflow
  • <OUTPUT_DOC_PATH>: apps/worker-workflow/src/cross-workflow/docs/cross-workflow-system-behavior.md

6. Menjalankan Dev​

Jalankan per app:

pnpm --filter api dev
pnpm --filter docs start
pnpm --filter worker-issue dev
pnpm --filter worker-common dev
pnpm --filter worker-etl dev
pnpm --filter worker-workflow dev

7. Build​

  • Build semua lewat Turbo (task runner monorepo): pnpm run docker:build otomatis menjalankan build per app (butuh pnpm install lebih dulu).
  • Build per app (tanpa Docker):
pnpm --filter api build
pnpm --filter docs build
pnpm --filter worker-issue build
pnpm --filter worker-common build
pnpm --filter worker-etl build
pnpm --filter worker-workflow build

8. Build Docker​

  • Tag pola: mvdevops/datacore-ext-${PROJECT}:${npm_package_name}${npm_package_version}
    • PROJECT diambil dari .env (default mv jika tidak ada).
  • Build semua: pnpm run docker:build (root).
  • Build satu app:
pnpm --filter api docker:build
pnpm --filter docs docker:build
pnpm --filter worker-issue docker:build
pnpm --filter worker-common docker:build
pnpm --filter worker-etl docker:build
pnpm --filter worker-workflow docker:build
  • Push semua: pnpm run docker:push

9. Environment​

  • File .env di root, contoh:
PROJECT=sma    # mempengaruhi nama image docker
PORT=4600
... (DB, NATS, dsb)
  • Root skrip docker:build/docker:push memuat .env via dotenv-cli; pastikan variabel yang dibutuhkan (mis. PROJECT) terisi.
  • Runtime env untuk API/worker tetap mengikuti konfigurasi Nest/TypeORM/NATS sesuai kebutuhan masing-masing app.

10. Instalasi​

pnpm install

11. Lint & Format​

  • Linter/formatter: Biome (sudah ada di devDependencies).
  • Periksa: pnpm lint (cek apps, packages)
  • Perbaiki otomatis: pnpm lint:fix
  • Jika Biome belum terpasang global: sudah disediakan via pnpm, cukup pnpm install lalu jalankan perintah di atas.

12. Catatan​

  • DevDependencies wajib ter-install (typescript, dotenv-cli, dll) sebelum build/docker.
  • Jaga pemisahan: app hanya mengimpor dari packages/lib atau alias path masing-masing app; hindari impor silang antar app.
  • Monorepo orchestration memakai Turbo (turbo.json, pnpm run turbo), dokumentasi: https://turbo.build
  • Framework NestJS, dokumentasi: https://docs.nestjs.com