RESTForge Playbook

Panduan onboarding praktis untuk mempelajari RESTForge dari nol hingga aplikasi full-stack berjalan di browser.

Repository ini berisi kumpulan skenario terstruktur yang membimbing developer melalui seluruh alur kerja RESTForge: instalasi, definisi schema, generate endpoint backend, hingga generate aplikasi frontend. Setiap skenario disusun sebagai modul mandiri yang dapat dieksekusi secara berurutan dari Skenario 1 sampai Skenario 13.

---

Ikhtisar (Overview)

RESTForge adalah platform code generator berbasis definition file (SDF, RDF, UDF) yang menghasilkan endpoint REST API dan aplikasi frontend secara otomatis. Playbook ini didesain sebagai jalur belajar resmi bagi developer yang baru pertama kali berinteraksi dengan toolchain RESTForge.

Target akhir playbook adalah kondisi sebagai berikut:

• Backend server RESTForge berjalan pada port 3000 dengan endpoint REST visitors aktif
• Aplikasi frontend berjalan pada port 8000 dan menampilkan data dari backend API
• Pemahaman menyeluruh atas siklus hidup definition file: SDF → database → RDF → endpoint → UDF → frontend

---

Daftar Skenario (Scenarios)

No	Judul Skenario	Output Utama
01	Persiapan Environment dan Instalasi Package	Struktur folder sandbox terbentuk, @restforgejs/platform terpasang
02	Inisialisasi Project dan Konfigurasi Database	File konfigurasi project dan koneksi database siap pakai
03	Pembuatan dan Validasi SDF	Schema Definition File ter-validasi sesuai spec handbook
04	Apply SDF ke Database dan Drift Detection	Tabel database ter-create sesuai SDF, drift terdeteksi
05	Pembuatan dan Validasi RDF	Resource Definition File ter-validasi
06	Generate Endpoint dan Jalankan Runtime Server	Endpoint REST API ter-generate, runtime server berjalan
07	Test Endpoint via Postman	Verifikasi endpoint GET/POST/PUT/DELETE melalui Postman
08	Migrasi RDF ke UDF dan Generate Aplikasi Frontend	UDF terbentuk, aplikasi frontend ter-generate
09	Menjalankan Aplikasi Frontend dan Verifikasi GET Visitors	Halaman visitors.html memuat data dari backend
10	Tabel visitor_categories dari SDF hingga Endpoint	Tabel visitor_categories ter-create, endpoint REST aktif
11	Revisi visitors dengan JOIN ke visitor_categories	Kolom FK category_id ditambah, endpoint visitors menampilkan category_name
12	Aplikasi Frontend Multi-Page visitor_categories dan visitors	Satu app multi-page (Categories + Visitors) dengan dropdown kategori dari endpoint lookup
13	Update UDF dan Generate Ulang Per-Page dan Penuh	Teknik regenerate per-page (--scope=form) dan penuh (--scope=app), termasuk penanganan index.html

Seluruh file skenario tersedia di folder scenarios/.

---

Struktur Folder (Folder Structure)

playbook/
├── scenarios/          Dokumentasi skenario onboarding (Skenario 1-13)
├── sandbox/            Workspace eksekusi untuk artefak hasil playbook
│   ├── backend/        Working directory untuk Skenario 1-7, 10-11 (akan dibuat saat eksekusi)
│   └── frontend/       Working directory untuk Skenario 8-9, 12-13 (akan dibuat saat eksekusi)
└── README.md           Dokumen ini

Folder sandbox/ sengaja di-ignore dari git agar setiap developer dapat mengeksekusi playbook secara independen tanpa konflik artefak. Detail isi sandbox dijelaskan pada sandbox/README.md.

---

Prasyarat (Prerequisite)

Item	Versi / Keterangan
Node.js dan npm	Versi LTS terbaru, dapat dipanggil via terminal
Database server	PostgreSQL atau MySQL (sesuai konfigurasi Skenario 2)
Postman	Untuk pengujian endpoint pada Skenario 7
Browser modern	Chrome, Edge, atau Firefox untuk verifikasi frontend pada Skenario 9
Akses internet	Koneksi aktif ke registry npm untuk download package

---

Cara Memulai (Getting Started)

1. Clone repository ini ke local machine.
2. Masuk ke folder hasil clone (root repo playbook). Seluruh artefak eksekusi akan tersimpan di folder sandbox/ pada root tersebut.

Tersedia tiga jalur onboarding, diurutkan dari yang paling cepat melihat hasil hingga yang paling mendalam. Pilih salah satu sesuai kebutuhan.

Opsi 1 — Fast Track

node fast-track.mjs

Jalur tercepat untuk melihat hasil project secara langsung. Konfigurasi diisi satu kali di awal, lalu seluruh sandbox dibangun otomatis hingga backend dan aplikasi frontend berjalan dan dapat dibuka di browser. Cocok untuk demo atau membangun ulang sandbox dengan cepat. Penjelasan lengkap pada bagian Tool Onboarding Otomatis.

Opsi 2 — Quick Start

node quick-start.mjs

Menjalankan seluruh skenario secara terpandu dengan konfirmasi pada tiap langkah. Setiap perintah dapat ditinjau sebelum dieksekusi, sehingga cocok bagi yang ingin berinteraksi secara minimal sambil mengikuti materi utama playbook.

Opsi 3 — Manual

Mengikuti dokumen skenario dari awal sampai akhir dan menjalankan tiap perintah secara manual. Jalur paling mendalam untuk memahami setiap detail siklus hidup definition file. Mulai dari scenarios/scenario-01-persiapan-dan-instalasi.md, lalu ikuti tiap skenario secara berurutan sampai Skenario 13.

---

Tool Onboarding Otomatis (Automated Onboarding Scripts)

Selain mengikuti skenario secara manual, repository ini menyediakan dua script Node.js di root project untuk menjalankan playbook secara otomatis: fast-track.mjs (paling cepat) dan quick-start.mjs (terpandu). Kedua script menulis artefak ke folder sandbox/ yang di-resolve relatif terhadap lokasi script, sehingga cukup dijalankan dari root repo hasil clone.

Prasyarat umum: Node.js, PostgreSQL yang dapat diakses, dan license key RESTForge. Untuk tahap frontend, restforge-designer perlu terpasang system-level.

fast-track.mjs — Mode Cepat (Fast Mode)

node fast-track.mjs

Pembangun sandbox lengkap dengan interaksi minimal. Script hanya meminta satu set input di awal (license dan parameter database), lalu menjalankan seluruh pipeline RESTForge secara otomatis tanpa konfirmasi per langkah hingga sandbox terbentuk penuh. Mode ini paling cepat untuk melihat hasil project secara langsung.

Input yang diminta (tekan Enter untuk memakai nilai default dalam kurung):

LICENSE (xxxx-xxxx-xxxx-xxxx):
DB_TYPE (postgresql):
DB_HOST (127.0.0.1):
DB_PORT (5432):
DB_USER (postgres):
DB_PASSWORD (postgres1234):
DB_NAME (dbsandbox):

Setelah input, script mengeksekusi rangkaian berikut secara otomatis: install package, init dan konfigurasi database, pembuatan tabel visitor_categories dan visitors (dengan relasi JOIN), generate endpoint REST, migrasi UDF, hingga generate aplikasi frontend multi-page. Tahap akhir membuka runtime server (port 3000) dan aplikasi frontend (port 8000) pada window CMD masing-masing, mengisi data contoh kategori, lalu menampilkan konfirmasi untuk membuka http://localhost:8000/index.html di browser.

Mode ini cocok untuk demo atau membangun ulang sandbox dengan cepat tanpa menelusuri tiap langkah. Hasil akhir setara dengan menyelesaikan seluruh skenario playbook.

quick-start.mjs — Mode Terpandu (Guided Mode)

node quick-start.mjs

Runner interaktif yang memandu seluruh skenario backend dan frontend secara berurutan, satu langkah pada satu waktu. Tiap langkah menampilkan ringkasan perintah lalu meminta konfirmasi Jalankan langkah ini sekarang? (y/N), sehingga setiap perintah dapat ditinjau sebelum dieksekusi. Mode ini cocok untuk berinteraksi secara minimal sambil mempelajari alur kerja RESTForge, karena seluruh proses terlihat per langkah.

Fitur:

• Pengisian config/db-connection.env secara interaktif (license dan database).

• Service (runtime server dan aplikasi frontend) selalu dibuka di window CMD baru.

• Deteksi port: bila port 3000 atau 8000 masih dipakai, ditawarkan menghentikan proses lama sebelum service baru dijalankan.

• Lompat ke skenario tertentu lalu lanjut sampai akhir:

  node quick-start.mjs --scenario=11

Perbandingan (Comparison)

Aspek	fast-track.mjs	quick-start.mjs
Interaksi	7 input di awal + 1 konfirmasi browser	Konfirmasi tiap langkah
Tujuan	Melihat hasil project dengan cepat	Belajar alur per langkah
Kontrol per langkah	Otomatis penuh	Penuh (dapat melewati langkah)
Hasil akhir	Sandbox full-stack	Sandbox full-stack

---

Konvensi (Conventions)

• Seluruh perintah CLI mengikuti pattern npx restforge <resource> <verb> [--flag=value]
• Reference resmi tersedia di RESTForge Handbook
• Definition file menggunakan format JSON dengan validasi schema bawaan
• Working directory aktif untuk eksekusi backend adalah playbook/sandbox/backend/ (relatif terhadap folder root project)
• Working directory aktif untuk eksekusi frontend adalah playbook/sandbox/frontend/ (relatif terhadap folder root project)

---

Referensi (Reference)

Topik	Sumber
RESTForge Handbook	https://github.com/restforge/handbook
Spec SDF	handbook/catalogs/sdf/
Spec RDF	handbook/catalogs/rdf/
Spec UDF	handbook/catalogs/udf/
CLI Reference	handbook/commands/

---

Lisensi (License)

Materi playbook dirilis sebagai dokumentasi pembelajaran internal RESTForge Systems. Hak cipta atas implementasi platform RESTForge mengikuti lisensi yang ditetapkan pada repository @restforgejs/platform.