Developer Onboarding & Environment Setup

1. System Requirements & Prerequisites

Before setting up the SML Web codebase locally, ensure your development workstation meets the following minimum requirements:

• Operating System: macOS 12+, Linux (Ubuntu 22.04+), or Windows 11 with WSL2 (Ubuntu).
• Node.js Runtime: v20.10.0 or v22.x LTS (Verify with node -v).
• Package Manager: npm v10.x+ (bundled with Node) or pnpm v9.x+.
• Database Engine: PostgreSQL v15.0+ (local service or Docker container).
• Git: v2.38+.

---

2. Step-by-Step Local Workspace Initialization

Step 1: Clone Repository & Install Dependencies

git clone https://github.com/eyd-v-skill/satenyamamaloesyeweb.git
cd satenyamamaloesyeweb
npm install

Step 2: Configure Environment Variables

Copy the example environment file and adjust keys for your local environment:

cp .env.example .env

---

3. Comprehensive Environment Variables Dictionary

Variable Name	Type	Default / Example Value	Description & Security Context
NODE_ENV	string	development	Runtime mode: development, production, or test.
PORT	number	3000	HTTP port for the Hono backend server.
FRONTEND_URL	string	http://localhost:5173	Canonical URL of the frontend (used for CORS & magic links).
DATABASE_URL	string	postgresql://user:pass@localhost:5432/smlweb_db	PostgreSQL TCP connection string for Prisma ORM.
JWT_SECRET	string	super_secret_jwt_key_min32chars	Secret key used to sign and verify JWT authentication tokens.
WADENO_API_KEY	string	wadeno_dev_secret_key	API key for authenticating with Wadeno WhatsApp Gateway.
WHATSAPP_API_URL	string	http://localhost:8080	Base URL of the Wadeno / GoWA WhatsApp Gateway service.
WHATSAPP_PROVIDER	string	HONOWA	WhatsApp provider engine mode (HONOWA or GOWA).
TURNSTILE_SECRET	string	0x4AAAAAA...	Cloudflare Turnstile secret key for captcha siteverify calls.
QBIZ_ENABLED	boolean	false	Enable/Disable automated QBiz Dynamic QRIS payment gateway.
QBIZ_BASE_URL	string	http://localhost:8000	Base API URL for QBiz payment service.
QBIZ_API_KEY	string	qbiz_api_key_xxx	Merchant API key issued by QBiz Gateway.
QBIZ_WEBHOOK_SECRET	string	qbiz_wh_sec_yyy	HMAC secret for verifying incoming payment callback webhooks.
STORAGE_TYPE	string	local	Media storage driver: local (disk storage) or r2 (Cloudflare R2).
R2_ENDPOINT	string	https://<account-id>.r2.cloudflarestorage.com	Cloudflare R2 S3-compatible API endpoint URL.
R2_BUCKET	string	smlweb-media	Target bucket name in Cloudflare R2 storage.
R2_PUBLIC_URL	string	https://assets.[DOMAIN_PRODUKSI]	Public CDN base URL for serving uploaded R2 assets.
VAPID_PUBLIC_KEY	string	BEl62...	Public VAPID key for Web Push browser subscriptions.
VAPID_PRIVATE_KEY	string	3K8z...	Private VAPID key for signing web push payloads.

---

4. Local Database Setup via Docker Compose

To quickly spin up a isolated PostgreSQL database instance locally:

# Launch PostgreSQL in detached container
docker-compose up -d postgres

# Run Prisma migrations to construct database schema
npx prisma migrate dev --name init

# Seed database with initial categories, settings, and default admin user
npx prisma db seed

---

5. Developer Command Reference

Command	Action	Output / Behavior
npm run dev	Starts Hono backend & Vite dev server concurrently	Live reload server on localhost:3000 & localhost:5173
npm run build	Compiles TypeScript backend & bundles React frontend	Outputs built assets to dist/ and frontend/dist/
npx prisma studio	Opens Prisma Studio GUI in browser	Interactive database inspection UI at localhost:5555
npx prisma migrate dev	Generates & executes new migration	Applies incremental schema changes to local PostgreSQL
npx prisma db seed	Executes prisma/seed.ts script	Injects initial categories, menus, and system settings