Selamat datang di workshop DevFest Cloud Surabaya 2026!

Dalam workshop langsung ini, Anda akan membangun NusaRoute AI, sebuah platform logistik cerdas berbasis Agentic AI yang dirancang untuk mengeliminasi hambatan operasional (operational drag) pada pengiriman last-mile di wilayah perkotaan padat, dengan studi kasus nyata di Kota Surabaya.

Apa yang Akan Anda Pelajari & Bangun?

  1. Agentic Multimodal AI: Menggunakan Google Gemini 3.6 Flash untuk menganalisis foto kemacetan jalan dan rekaman suara (voice note) kurir menjadi data terstruktur (JSON).
  2. Google Maps Platform & Komputasi Spasial: Mengintegrasikan Directions API, visualisasi polyline rute pengalihan di peta interaktif, dan validasi geofencing 200 meter berbasis formula matematis Haversine.
  3. Cloud Firestore Real-Time Database: Mengatur database NoSQL real-time di region Jakarta (asia-southeast2) dengan sinkronisasi instan via WebSocket onSnapshot.
  4. Algoritma Spasial & Resiliensi: Menerapkan heuristik Nearest-Neighbor TSP ($O(n^2)$), Exponential Backoff, dan Graceful Shutdown pada Cloud Run.
  5. Trifecta Serverless Deployment: Men-deploy backend container ke Google Cloud Run dan frontend React 18 PWA ke Firebase Hosting.

Mengapa Agentic AI, Bukan Sekadar Chatbot?

Chatbot konvensional bersifat pasif: menunggu pertanyaan pengguna lalu membalas dengan teks. Sebaliknya, Agentic AI bekerja proaktif sebagai autonomous digital co-worker dengan siklus 4 tahap:

Spektrum Evolusi AI: Di Mana Posisi Agentic AI?

Untuk memahami posisi teknologi ini, perhatikan bagaimana paradigma AI berevolusi:

Kategori AI

Karakteristik Utama

Contoh Kasus

Keterbatasan

Rule-Based (Sistem Pakar)

Logika kaku berbasis aturan if-else

Sistem tilang elektronik statis

Gagal beradaptasi jika kondisi lapangan di luar skenario aturan yang ditentukan (rule breakdown).

Predictive ML

Prediksi angka/kategori dari data historis

Estimasi waktu tempuh (ETA) rata-rata

Tidak bisa bernalar dan tidak memahami foto atau suara.

Generative AI (Chatbot)

Menghasilkan teks/gambar berdasarkan prompt

Chatbot customer service

Bersifat pasif; hanya menjawab saat ditanya, tidak bisa aksi nyata.

Agentic AI (NusaRoute)

Otonom, memiliki persepsi, nalar, & aksi

Asisten navigasi otonom Surabaya

Bekerja proaktif mengambil keputusan & mengeksekusi API tanpa intervensi.

4 Pilar yang Membuktikan NusaRoute AI adalah Agentic AI:

  1. Persepsi (Perception): Membaca foto jalanan macet dan audio suara kurir secara in-memory di RAM.
  2. Penalaran (Reasoning): Gemini 3.6 Flash mengevaluasi ancaman, menentukan aksi (REROUTE), dan menghitung menit delay.
  3. Aksi (Tool Use / Action): AI memiliki β€˜tangan dan kaki' untuk memanggil Google Maps Directions API dan memperbarui status di Cloud Firestore.
  4. Otonomi (Autonomous Daemon): Daemon autonomous-agent.ts berjalan otomatis setiap 3 menit di background Cloud Run tanpa perlu dipicu klik manual oleh manusia.

Sebelum memulai praktikum, pastikan lingkungan kerja dan alat-alat esensial berikut telah siap di laptop Anda.

1. Checklist Prasyarat Alat (Tooling Checklist)

Untuk mengikuti workshop hands-on ini secara maksimal, Anda memerlukan alat-alat berikut:

Alat / Tool

Versi Minimum

Deskripsi & Peran

Tautan Unduh / Panduan

Google Antigravity IDE (Disarankan)

Versi Terbaru

Editor berkemampuan Agentic AI buatan Google DeepMind dengan autonomous agent, workspace terintegrasi, dan inspeksi kode langsung. (Dapat juga menggunakan VS Code)

antigravity.google / code.visualstudio.com

Google Cloud CLI (gcloud)

Versi 450.0.0+

Tool baris perintah resmi untuk autentikasi GCP, enable API, pengelolaan IAM, dan deploy Cloud Run.

cloud.google.com/sdk/docs/install

Node.js & NPM

Node 18+ (LTS) / NPM 9+

Runtime JavaScript/TypeScript untuk backend Express 5 dan frontend React 18 / Vite.

nodejs.org

Git

Versi 2.30+

Tool version control untuk mengunduh kode starter dan sinkronisasi berkas.

git-scm.com

Gemini API Key

-

Kunci API gratis untuk model Gemini 3.6 Flash.

aistudio.google.com

2. Panduan Instalasi Cepat Tooling

A. Verifikasi Node.js dan Git

Buka terminal (PowerShell, Command Prompt, atau Terminal macOS/Linux) dan jalankan:

node -v   # Harus v18.0.0 atau lebih baru (misal: v20.x / v22.x)
npm -v    # Harus v9.0.0 atau lebih baru
git --version

Jika belum terpasang, pasang Node.js LTS dari nodejs.org dan Git dari git-scm.com.

B. Instalasi & Autentikasi Google Cloud CLI (gcloud)

Tool gcloud sangat penting untuk mengaktifkan API GCP dan men-deploy kontainer ke Cloud Run:

Setelah instalasi gcloud selesai, ikuti alur berurutan berikut untuk autentikasi dan penyiapan Google Cloud Project:

Langkah a: Autentikasi Akun Google Anda

gcloud auth login

(Perintah ini akan membuka jendela browser. Pilih akun Google/Gmail Anda dan klik

Allow

).

Langkah b: Menyiapkan Google Cloud Project (Pilih salah satu kondisi):

C. Buka Proyek dengan Google Antigravity IDE

Buka Google Antigravity IDE (atau VS Code). Antigravity IDE sangat direkomendasikan untuk workshop ini karena dilengkapi AI Agent assistant yang memahami konteks repositori, arsitektur monorepo, serta mampu menjalankan verifikasi kode secara proaktif.

3. Langkah 1: Clone Repositori Starter

Buka terminal di Antigravity IDE dan clone repositori resmi workshop:

git clone https://github.com/putuwahyu29/nusaroute-ai.git
cd nusaroute-ai

4. Langkah 2: Instal Seluruh Dependensi Monorepo

Proyek ini menggunakan arsitektur monorepo ringan (backend TypeScript Express 5 dan frontend React 18/Vite). Jalankan satu perintah berikut di root untuk menginstal semua dependensi sekaligus:

npm run install:all

5. Langkah 3: Konfigurasi File Environment

Salin template konfigurasi lingkungan untuk backend dan frontend:

# Salin konfigurasi backend
cp backend/.env.example backend/.env

# Salin konfigurasi frontend (Vite membaca .env.local atau .env)
cp frontend/.env.example frontend/.env.local

Pada bagian ini, kita akan mengatur database real-time Cloud Firestore dan mengaktifkan seluruh API ekosistem Google Cloud.

Pilihan A: Setup Agentic via Google Antigravity IDE (Paling Praktis)

Jika Anda membuka proyek ini menggunakan Google Antigravity IDE (atau IDE berkemampuan AI Agent), repositori ini telah dilengkapi panduan AGENTS.md. Anda tidak perlu menjalankan perintah satu per satu!

Cukup buka panel Chat Antigravity dan ketik instruksi bahasa natural:

"Tolong bantu setup Google Cloud project untuk NusaRoute AI, aktifkan API yang dibutuhkan, dan siapkan file backend/.env serta frontend/.env.local."

AI Agent di Antigravity IDE akan secara otonom:

  1. Memeriksa status login akun Anda melalui gcloud auth list.
  2. Mendeteksi project yang ada atau membuatkan project baru.
  3. Mengaktifkan seluruh API layanan (firestore, run, aiplatform, maps).
  4. Menyiapkan kredensial Service Account dan menulis file .env di backend maupun frontend.
  5. Menjalankan npm run validate untuk memastikan semua konfigurasi siap digunakan.

Pilihan B: Setup Otomatis via Terminal Script (Universal CLI)

Jika Anda menggunakan editor teks biasa (seperti VS Code standar) atau terminal mandiri, gunakan script wizard interaktif yang telah kami sediakan:

  1. Pastikan Anda sudah login ke Google Cloud CLI:
    gcloud auth login
    
  2. Jalankan script interaktif di root repositori:
    npm run setup
    
    Script setup-config.js akan secara otomatis menanyakan pilihan nomor project Anda di terminal, mengaktifkan seluruh API yang dibutuhkan, dan mengisi file .env di backend maupun frontend.
  3. Jalankan verifikasi:
    npm run validate
    

Pilihan C: Setup Manual Step-by-Step Tanpa Script

Jika Anda ingin memahami setiap komponen infrastruktur secara mandiri atau tidak menggunakan skrip otomatis, ikuti 7 langkah terstruktur berikut:

1. Mengaktifkan API Layanan Google Cloud

Buka terminal dan aktifkan API layanan yang dibutuhkan.

A. Jika Proyek Anda Sudah Memiliki Billing Account (Lengkap untuk Cloud Run)

Jika project Anda sudah ditautkan ke akun penagihan (Cloud Billing Account), aktifkan 5 API Inti:

gcloud services enable \
  firestore.googleapis.com \
  run.googleapis.com \
  generativelanguage.googleapis.com \
  directions-backend.googleapis.com \
  maps-backend.googleapis.com

B. Jika Proyek Baru / Tanpa Billing Account (Khusus Mode Lokal & Hemat Biaya)

Google Cloud mewajibkan akun penagihan aktif khusus untuk layanan container run.googleapis.com dan secretmanager.googleapis.com. Jika project Anda baru dibuat dan belum ditautkan kartu kredit/billing, jangan sertakan

run.googleapis.com

sekarang:

# Aktifkan API yang tidak memerlukan billing container
gcloud services enable \
  generativelanguage.googleapis.com \
  firestore.googleapis.com \
  directions-backend.googleapis.com \
  maps-backend.googleapis.com

(Layanan Cloud Run baru dibutuhkan di

Langkah 9: Deployment Produksi

. Untuk Langkah 1 s.d. 8, seluruh fitur AI Gemini 3.6 Flash, routing TSP, peta, dan geofencing berjalan 100% normal di laptop Anda).

Rincian API Google Cloud & Mengapa Wajib / Opsional Diaktifkan:

Identifier API

Nama Layanan

Kategori

Peran Nyata di NusaRoute AI

Digunakan Pada

firestore.googleapis.com

Cloud Firestore API

Wajib (Core)

Database dokumen NoSQL real-time di region asia-southeast2 (Jakarta) untuk menyimpan status 15 paket pengiriman, data kurir/dispatcher, serta sinkronisasi instan via WebSocket onSnapshot.

backend/src/services/firebase-admin.ts & frontend/src/services/firebase.ts

run.googleapis.com

Cloud Run Admin API

Wajib (Core)

Infrastruktur serverless container (Gen 2) untuk menjalankan backend Express.js di cloud dengan auto-scaling dan alokasi CPU konstan (--no-cpu-throttling) agar background loop 3 menit tidak dibekukan.

Deployment backend (gcloud run deploy)

generativelanguage.googleapis.com

Google Generative Language API

Wajib (Core)

Endpoint resmi publik untuk model Gemini 3.6 Flash. Menjalankan inferensi penalaran multimodal (analisis foto insiden dan rekaman suara kurir) dengan format output JSON deterministik (responseSchema).

backend/src/services/ai-agent.ts

directions-backend.googleapis.com

Google Maps Directions API

Wajib (Core)

Menghitung rute navigasi jalan raya turn-by-turn, jarak tempuh, perkiraan waktu (ETA), dan rute alternatif menghindari titik macet.

frontend/src/components/GoogleMap.tsx

maps-backend.googleapis.com

Maps JavaScript API

Wajib (Core)

Library rendering peta interaktif berbasis vektor di browser kurir dan dispatcher lengkap dengan marker armada bergerak, layer lalu lintas (Traffic Layer), dan visualisasi polyline rute.

frontend/src/components/GoogleMap.tsx

distance-matrix-backend.googleapis.com

Google Maps Distance Matrix API

Opsional (Bypassed)

Sengaja digantikan oleh rumus matematika Haversine in-memory ($O(n^2)$) pada kode backend (haversineKm). Hal ini menghemat biaya kuota API per-elemen dan menghasilkan komputasi jarak instan (<1ms) tanpa latensi jaringan.

backend/src/services/traffic-agent.ts

secretmanager.googleapis.com

Secret Manager API

Opsional (Enterprise)

Standar keamanan cloud enterprise untuk menyimpan kunci rahasia. Pada workshop ini, variabel disimpan via Environment Variables standar (.env dan --set-env-vars) agar praktikum ramah pemula.

Manajemen rahasia Cloud Run

aiplatform.googleapis.com

Vertex AI Platform API

Opsional (Enterprise)

Endpoint enterprise Vertex AI. Karena SDK @google/genai menggunakan API Key dari AI Studio, request diarahkan langsung ke generativelanguage.googleapis.com.

Otorisasi kuota AI project GCP

2. Mendapatkan Kunci Gemini API (Google AI Studio)

Model multimodal Gemini 3.6 Flash diakses melalui Google AI Studio:

  1. Kunjungi aistudio.google.com dan login dengan akun Google Anda.
  2. Klik tombol Get API key di sidebar kiri.
  3. Klik Create API key β†’ Pilih project Google Cloud Anda (atau buat di project default).
  4. Salin string kunci API (berawalan AIzaSy...).
  5. Buka berkas backend/.env, lalu masukkan nilai tersebut:
    GEMINI_API_KEY=AIzaSyDxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    USE_MOCK_AI=false
    GEMINI_MODEL=gemini-3.6-flash
    

3. Membuat Database Cloud Firestore di Region Jakarta

  1. Buka Google Cloud Console β†’ Firestore.
  2. Klik Create Database.
  3. Pilih mode database: Native Mode (wajib untuk aplikasi web/mobile real-time).
  4. Beri nama Database ID: (default).
  5. Pilih Region: asia-southeast2 (Jakarta) agar latensi database dari dan ke Surabaya sangat rendah (<20ms).
  6. Klik Create Database.

4. Membuat Service Account Key untuk Backend Express

Backend Express membutuhkan kredensial Service Account untuk membaca dan menulis data pengiriman ke Firestore:

  1. Buka IAM & Admin β†’ Service Accounts.
  2. Klik + Create Service Account:
    • Beri nama: nusaroute-backend-sa.
    • Klik Create and Continue.
  3. Berikan Role: Cloud Datastore User (memberikan akses read/write penuh ke Firestore).
  4. Klik Done.
  5. Pada daftar Service Account, klik email nusaroute-backend-sa@... yang baru saja dibuat.
  6. Masuk ke tab Keys β†’ Klik Add Key β†’ Pilih Create new key.
  7. Pilih format JSON β†’ Klik Create. File kunci JSON akan otomatis terunduh ke laptop Anda.
  8. Buka file JSON tersebut dengan text editor, lalu salin nilainya ke backend/.env:
    FIREBASE_PROJECT_ID=id-project-anda
    FIREBASE_CLIENT_EMAIL=nusaroute-backend-sa@id-project-anda.iam.gserviceaccount.com
    FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvgIB...-----END PRIVATE KEY-----\n"
    

5. Membuat Kunci Google Maps API

Kunci ini digunakan untuk Directions API di backend serta rendering peta di frontend:

  1. Buka APIs & Services β†’ Credentials.
  2. Klik + Create Credentials β†’ Pilih API key.
  3. Salin API Key yang terbentuk (berawalan AIzaSy...).
  4. (Sangat Disarankan): Klik nama kunci tersebut untuk membatasi akses (API restrictions) hanya ke:
    • Maps JavaScript API
    • Directions API
    • Distance Matrix API
  5. Masukkan kunci ini ke dua berkas:
    • Pada backend/.env:
      GOOGLE_MAPS_API_KEY=AIzaSy...
      
    • Pada frontend/.env.local:
      VITE_GOOGLE_MAPS_API_KEY=AIzaSy...
      

6. Mendaftarkan Web App di Firebase Console (Client SDK)

Frontend React memerlukan kredensial Firebase Client SDK untuk mendengarkan perubahan data secara real-time via onSnapshot:

  1. Kunjungi console.firebase.google.com.
  2. Klik project Google Cloud Anda (jika belum muncul di Firebase, klik Add project lalu pilih project GCP yang sudah ada untuk mengimpornya).
  3. Di halaman Project Overview, klik ikon Web () untuk menambahkan aplikasi web baru.
  4. Beri nama aplikasi, misalnya: nusaroute-web (centang Firebase Hosting opsional) β†’ Klik Register app.
  5. Firebase akan menampilkan cuplikan objek firebaseConfig:
    const firebaseConfig = {
      apiKey: "AIzaSy...",
      authDomain: "project-id.firebaseapp.com",
      projectId: "project-id",
      storageBucket: "project-id.appspot.com",
      messagingSenderId: "1234567890",
      appId: "1:1234567890:web:abcdef..."
    };
    
  6. Salin nilai-nilai tersebut ke dalam frontend/.env.local:
    VITE_BACKEND_URL=http://localhost:3000
    VITE_FIREBASE_API_KEY=AIzaSy...
    VITE_FIREBASE_AUTH_DOMAIN=project-id.firebaseapp.com
    VITE_FIREBASE_PROJECT_ID=project-id
    VITE_FIREBASE_STORAGE_BUCKET=project-id.appspot.com
    VITE_FIREBASE_MESSAGING_SENDER_ID=1234567890
    VITE_FIREBASE_APP_ID=1:1234567890:web:abcdef...
    VITE_GOOGLE_MAPS_API_KEY=AIzaSy...
    

7. Mekanisme Auto-Seeding Database

Anda tidak perlu repot membuat dokumen atau koleksi Firestore secara manual! Begitu backend pertama kali dijalankan (npm run dev), fungsi seedDatabase() di backend/src/services/firebase-admin.ts akan otomatis:

Contoh Lengkap Berkas Konfigurasi Hasil Setup Manual

Setelah menyelesaikan seluruh langkah di atas, pastikan kedua file konfigurasi Anda memiliki struktur lengkap seperti berikut:

A. File backend/.env

# Server & CORS
PORT=3000
NODE_ENV=development
CORS_ORIGIN=http://localhost:5173

# Google Gemini AI
GEMINI_API_KEY=AIzaSyDxxxxxxxxxxxxxxxxxxxxxxxxxxxx
USE_MOCK_AI=false
GEMINI_MODEL=gemini-3.6-flash

# Firebase Admin SDK (Service Account)
FIREBASE_PROJECT_ID=nusaroute-sby-2026
FIREBASE_CLIENT_EMAIL=nusaroute-backend-sa@nusaroute-sby-2026.iam.gserviceaccount.com
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvgIB...-----END PRIVATE KEY-----\n"

# Google Maps API
GOOGLE_MAPS_API_KEY=AIzaSyDxxxxxxxxxxxxxxxxxxxxxxxxxxxx

B. File frontend/.env.local

# Backend API URL
VITE_BACKEND_URL=http://localhost:3000

# Google Maps API
VITE_GOOGLE_MAPS_API_KEY=AIzaSyDxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Firebase Client Web SDK
VITE_FIREBASE_API_KEY=AIzaSyDxxxxxxxxxxxxxxxxxxxxxxxxxxxx
VITE_FIREBASE_AUTH_DOMAIN=nusaroute-sby-2026.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=nusaroute-sby-2026
VITE_FIREBASE_STORAGE_BUCKET=nusaroute-sby-2026.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=123456789012
VITE_FIREBASE_APP_ID=1:123456789012:web:abcdef123456

Matriks Koordinasi Kunci API & Konfigurasi (.env)

Agar frontend dan backend dapat saling berkomunikasi serta terhubung ke layanan Google Cloud, berikut adalah panduan pemetaan variabel yang perlu dikoordinasikan:

Variabel

Berkas Target

Fungsi & Penjelasan

Di Mana Mendapatkannya?

GEMINI_API_KEY

backend/.env

Autentikasi model Gemini 3.6 Flash untuk penalaran multimodal foto & audio kurir. (Aman di backend, tidak pernah terekspos ke browser).

aistudio.google.com β†’ Get API Key

USE_MOCK_AI

backend/.env

Saklar mode AI (false untuk inferensi Live Gemini 3.6 Flash, true hanya sebagai fallback darurat offline).

Setel false saat mengisi GEMINI_API_KEY asli.

GOOGLE_MAPS_API_KEY

backend/.env

Pemanggilan Google Maps Directions API sisi server untuk kalkulasi rute dinamis (dynamic waypoints).

Google Cloud Console β†’ APIs & Services β†’ Credentials

VITE_GOOGLE_MAPS_API_KEY

frontend/.env.local

Me-render peta interaktif berbasis vektor di browser kurir dan dasbor dispatcher.

Kunci yang sama dengan Maps API di atas.

VITE_BACKEND_URL

frontend/.env.local

Alamat endpoint backend Express (default lokal: http://localhost:3000).

Port backend yang aktif di mesin lokal atau Cloud Run URL.

CORS_ORIGIN

backend/.env

Whitelist alamat frontend yang diizinkan memanggil backend (default: http://localhost:5173).

Port Vite dev server.

FIREBASE_* (Admin SDK)

backend/.env

Kredensial Service Account (PROJECT_ID, CLIENT_EMAIL, PRIVATE_KEY) untuk hak tulis/baca Firestore.

Google Cloud Console β†’ IAM & Admin β†’ Service Accounts β†’ Keys (JSON).

VITE_FIREBASE_* (Web SDK)

frontend/.env.local

Kredensial client Firebase untuk sinkronisasi real-time via WebSocket onSnapshot.

Firebase Console β†’ Project Settings β†’ General β†’ Web Apps.

Kini kita mulai memprogram agen kecerdasan buatan multimodal dengan model terkini Google Gemini 3.6 Flash.

File Target

Buka file: backend/src/services/ai-agent.ts

1. Pahami Skema Respons JSON (INCIDENT_RESPONSE_SCHEMA)

Agar respons AI selalu deterministik dan siap dieksekusi Maps API, kita terapkan Structured Outputs:

import { GoogleGenAI, Type, createPartFromBase64 } from "@google/genai";

const INCIDENT_RESPONSE_SCHEMA = {
  type: Type.OBJECT,
  properties: {
    action: {
      type: Type.STRING,
      enum: ["REROUTE", "WAIT", "REDIRECT_TO_HUB", "ESCALATE"],
      description: "Tindakan operasional yang disarankan untuk kurir",
    },
    severity: {
      type: Type.STRING,
      enum: ["low", "medium", "high", "critical"],
      description: "Tingkat keparahan hambatan dalam format standar",
    },
    severityLabel: {
      type: Type.STRING,
      enum: ["Rendah", "Sedang", "Tinggi", "Kritis"],
      description: "Label tingkat keparahan dalam Bahasa Indonesia",
    },
    incidentType: {
      type: Type.STRING,
      enum: ["road_closure", "traffic_jam", "flooding", "accident", "other"],
      description: "Klasifikasi jenis hambatan di lapangan",
    },
    incidentTypeLabel: {
      type: Type.STRING,
      description: "Deskripsi jenis hambatan",
    },
    analysis: {
      type: Type.STRING,
      description: "Analisis situasi lapangan yang objektif dalam Bahasa Indonesia",
    },
    analysisEn: {
      type: Type.STRING,
      description: "Detailed analysis in English for operational metadata logging",
    },
    recommendation: {
      type: Type.STRING,
      description: "Saran rute atau penanganan taktis kurir dengan nama jalan nyata di Surabaya",
    },
    recommendationEn: {
      type: Type.STRING,
      description: "Actionable recommendation in English",
    },
    reroutePoints: {
      type: Type.ARRAY,
      items: { type: Type.STRING },
      description: "Daftar nama jalan alternatif di Surabaya untuk bypass hambatan",
    },
    estimatedDelay: {
      type: Type.INTEGER,
      description: "Estimasi keterlambatan dalam satuan menit",
    },
  },
  required: [
    "action",
    "severity",
    "severityLabel",
    "incidentType",
    "incidentTypeLabel",
    "analysis",
    "recommendation",
    "reroutePoints",
    "estimatedDelay",
  ],
};

2. Implementasi processIncidentReport

Fungsi ini memproses buffer foto di RAM tanpa menyimpannya ke disk server:

export async function processIncidentReport(
  photoBuffer: Buffer | null = null,
  audioBuffer: Buffer | null = null,
  photoMime = "image/jpeg",
  audioMime = "audio/webm"
): Promise<AIDecision> {
  const client = getGenAIClient();
  const hasPhoto = Boolean(photoBuffer && photoBuffer.length > 0);
  const hasAudio = Boolean(audioBuffer && audioBuffer.length > 0);

  if (!client) {
    return generateContextualMock(hasPhoto, hasAudio);
  }

  const contentParts: any[] = [
    {
      text: "LAPORAN KENDALA LOGISTIK KURIR DI KOTA SURABAYA\nInstruksi: Analisis hambatan visual dan/atau audio, tentukan tingkat keparahan, dan berikan rute pengalihan nama jalan Surabaya.",
    },
  ];

  if (hasPhoto && photoBuffer) {
    contentParts.push(createPartFromBase64(photoBuffer.toString("base64"), photoMime));
  }

  if (hasAudio && audioBuffer) {
    contentParts.push(createPartFromBase64(audioBuffer.toString("base64"), audioMime));
  }

  const response = await client.models.generateContent({
    model: "gemini-3.6-flash",
    contents: [{ role: "user", parts: contentParts }],
    config: {
      systemInstruction: SURABAYA_INCIDENT_SYSTEM_INSTRUCTION,
      responseMimeType: "application/json",
      responseSchema: INCIDENT_RESPONSE_SCHEMA,
      temperature: 0.1,
    },
  });

  const parsedData = JSON.parse(response.text.trim());
  return normalizeIncidentResult(parsedData, false, "gemini-3.6-flash");
}

Kurir motor tidak boleh mengetik saat berkendara. Kurir cukup menekan mikrofon dan berbicara: "Lapor posko, Wonokromo macet total ada pohon tumbang di lajur kiri!"

Mekanisme Native Audio Tokenization

Gemini 3.6 Flash tidak memerlukan modul Whisper atau Speech-to-Text terpisah:

Pengujian di Antarmuka Kurir

  1. Buka browser di http://localhost:5173/courier.
  2. Klik tombol "Lapor via Suara".
  3. Ucapkan laporan singkat atau gunakan tombol uji sampel audio.
  4. Perhatikan bagaimana audio diproses di RAM via Multer MemoryStorage dan menghasilkan JSON instruksi operasional secara instan.

Keputusan AI (REROUTE) kini kita sambungkan ke Google Maps Platform untuk menggambar rute alternatif secara interaktif dan memvalidasi radius kehadiran kurir sebelum paket diselesaikan.

File Target

  1. Logika Spasial & Rerouting Backend: backend/src/services/traffic-agent.ts
  2. Rendering Navigasi Google Maps: frontend/src/components/GoogleMap.tsx
  3. Geofencing Presensi Kurir: frontend/src/pages/CourierPage.tsx

1. Deteksi Dini Bahaya & Rekomendasi Rute Alternatif (Backend)

Pada backend/src/services/traffic-agent.ts, fungsi proactiveReroute memindai setiap paket yang berpotensi melintasi zona kritis kemacetan atau banjir:

export function proactiveReroute(
  deliveries: Delivery[],
  trafficZones: TrafficZone[]
): Array<{
  delivery: Delivery;
  threatZone: TrafficZone;
  suggestedAction: "REROUTE" | "REDIRECT_TO_HUB";
  message: string;
}> {
  const criticalZones = trafficZones.filter((z) => z.level === "high" || z.level === "critical");
  const alerts: Array<{
    delivery: Delivery;
    threatZone: TrafficZone;
    suggestedAction: "REROUTE" | "REDIRECT_TO_HUB";
    message: string;
  }> = [];

  for (const delivery of deliveries) {
    if (delivery.status === "delivered" || !delivery.lat || !delivery.lng) continue;

    for (const zone of criticalZones) {
      const dist = haversineKm(delivery.lat, delivery.lng, zone.lat, zone.lng);
      if (dist != null && dist <= zone.radius) {
        alerts.push({
          delivery,
          threatZone: zone,
          suggestedAction: zone.level === "critical" ? "REDIRECT_TO_HUB" : "REROUTE",
          message: `Pengiriman ke ${delivery.recipient} terdampak ${zone.name} (${zone.level === "critical" ? "Macet Total" : "Padat"}). ${zone.reason || ""}`,
        });
        break;
      }
    }
  }

  return alerts;
}

Jika terdeteksi macet, fungsi generateRouteAlternatives menyediakan opsi rute bypass nyata di Surabaya (seperti Frontage Road sisi timur atau Koridor MERR):

export async function generateRouteAlternatives(
  delivery: Delivery,
  threatZone: TrafficZone
): Promise<{
  originalRoute: { path: string[]; durationMins: number; risk: string };
  alternatives: Array<{ name: string; via: string; durationMins: number; distanceKm: number; isRecommended: boolean }>;
}> {
  return {
    originalRoute: {
      path: [threatZone.name, delivery.address],
      durationMins: 35,
      risk: threatZone.level || "high",
    },
    alternatives: [
      {
        name: "Jalur Frontage / Arteri Sekunder",
        via: "Frontage Road sisi timur",
        durationMins: 20,
        distanceKm: 3.8,
        isRecommended: true,
      },
      {
        name: "Bypass Koridor Lingkar",
        via: "Jalur MERR / Lingkar Dalam",
        durationMins: 24,
        distanceKm: 4.5,
        isRecommended: false,
      },
    ],
  };
}

2. Rendering Navigasi Google Maps di Browser (Frontend)

Pada frontend/src/components/GoogleMap.tsx, Directions API dijalankan langsung pada peramban web kurir via Maps JavaScript API. Hal ini memastikan rute turn-by-turn dan polyline visual digambar secara real-time tanpa membebani server:

// Inisialisasi Directions Service & Renderer dari SDK Google Maps
directionsServiceRef.current = new window.google.maps.DirectionsService();
directionsRendererRef.current = new window.google.maps.DirectionsRenderer({
  suppressMarkers: true,
  polylineOptions: {
    strokeColor: "#10b981", // Hijau Emerald NusaRoute
    strokeWeight: 6,
    strokeOpacity: 0.95,
  },
  preserveViewport: true,
});
directionsRendererRef.current.setMap(map);

// Meminta rute jalan raya turn-by-turn dengan alternatif rute
directionsServiceRef.current.route(
  {
    origin,
    destination,
    travelMode: window.google.maps.TravelMode.DRIVING,
    provideRouteAlternatives: true,
  },
  (result, status) => {
    if (status === window.google.maps.DirectionsStatus.OK && result) {
      directionsRendererRef.current?.setDirections(result);
      directionsRendererRef.current?.setRouteIndex(preferredRouteIndex);
    }
  }
);

3. Geofencing Presensi 200 Meter Anti-Fraud

Untuk mencegah kecurangan kurir menekan tombol "Selesaikan Pengiriman" saat masih jauh dari lokasi rumah penerima, sistem menerapkan batasan geofencing presisi tinggi berbasis Formula Trigonometri Haversine:

$$\begin{aligned} a &= \sin^2\left(\frac{\Delta\phi}{2}\right) + \cos(\phi_1)\cos(\phi_2)\sin^2\left(\frac{\Delta\lambda}{2}\right) \
c &= 2 \cdot \operatorname{atan2}\left(\sqrt{a}, \sqrt{1-a}\right) \
d &= R \cdot c \quad (R = 6.371\text{ km}) \end{aligned}$$

Fungsi Haversine di backend/src/services/traffic-agent.ts:

export function haversineKm(
  lat1: number | null | undefined,
  lng1: number | null | undefined,
  lat2: number | null | undefined,
  lng2: number | null | undefined
): number | null {
  if (lat1 == null || lng1 == null || lat2 == null || lng2 == null) return null;
  const R = 6371; // Radius bumi dalam kilometer
  const dLat = ((lat2 - lat1) * Math.PI) / 180;
  const dLng = ((lng2 - lng1) * Math.PI) / 180;
  const a =
    Math.sin(dLat / 2) ** 2 +
    Math.cos((lat1 * Math.PI) / 180) *
      Math.cos((lat2 * Math.PI) / 180) *
      Math.sin(dLng / 2) ** 2;
  return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
}

Pada frontend/src/pages/CourierPage.tsx, tombol penyelesaian pengiriman terkunci otomatis (disabled) dengan ikon gembok jika kurir berada di luar radius 200 meter:

// Batas radius kehadiran fisik kurir: 200 meter (0.2 km)
const DELIVERY_MARK_RADIUS_KM = 0.2;

// Evaluasi status penguncian tombol secara real-time
const canMarkDelivered =
  !!activeDelivery &&
  activeDelivery.status !== "delivered" &&
  activeDistanceKm != null &&
  activeDistanceKm <= DELIVERY_MARK_RADIUS_KM;

const markDeliveredReason = !activeDelivery
  ? "Tidak ada tujuan aktif"
  : activeDelivery.status === "delivered"
  ? "Pengiriman sudah selesai"
  : activeDistanceKm == null
  ? "Lokasi kurir belum tersedia"
  : activeDistanceKm > DELIVERY_MARK_RADIUS_KM
  ? `Masih ${activeDeliveryDistanceLabel} dari lokasi tujuan`
  : "Siap ditandai terkirim";

Ketika kurir tiba dalam jarak $\le 200$ meter dari rumah/gedung penerima, status tombol secara otomatis berubah menjadi hijau aktif ("Tandai Terkirim").

Mari jalankan skenario simulasi pengiriman nyata di Kota Surabaya!

Skenario Uji: Koridor Wonokromo & Jalan Ahmad Yani

  1. Buka 2 tab browser secara berdampingan:
    • Tab Kiri (Dispatcher): http://localhost:5173/dispatcher
    • Tab Kanan (Kurir): http://localhost:5173/courier
  2. Di antarmuka kurir, pilih pengiriman DEL-001 (Tunjungan Plaza 6).
  3. Klik tombol "Lapor Hambatan Jalan":
    • Unggah foto kemacetan atau pilih rekaman suara.
  4. Perhatikan respons sistem dalam tempo <2 detik:
    • Gemini 3.6 Flash mengekstrak insiden ke JSON.
    • Perubahan rute disimpan ke Firestore dan dipancarkan via WebSocket onSnapshot.
    • Di kedua layar, rute merah otomatis berubah menjadi rute hijau alternatif.
    • Papan analitik mencatat efisiensi durasi perjalanan (memangkas rata-rata waktu dari 6 jam menjadi 4,1 jam).

Bagi developer tingkat lanjut (Advanced), sistem logistik cerdas tidak hanya bergantung pada LLM, melainkan mengombinasikan penalaran multimodal AI dengan algoritma komputasi spasial deterministik.

1. Algoritma Heuristik Nearest-Neighbor TSP

Di berkas backend/src/services/traffic-agent.ts, sistem mengimplementasikan algoritma Traveling Salesperson Problem (TSP) heuristik dengan kompleksitas O(nΒ²):

Uji algoritma via terminal atau cURL:

curl -X POST http://localhost:3000/api/deliveries/tsp-benchmark \
  -H "Content-Type: application/json" \
  -d '{"courierId": "sby-c01"}'

2. Telemetri & Observabilitas Inferensi AI

Pada berkas backend/src/services/ai-agent.ts, setiap respons dari Gemini 3.6 Flash dilengkapi telemetri performa:

3. Ketahanan Sistem: Retry dengan Exponential Backoff

Untuk mengatasi potensi gangguan jaringan (transient network glitch) atau batas rate limit (HTTP 429), fungsi withRetry menjalankan percobaan ulang dengan jeda eksponensial dan random jitter: delay = baseDelay * (2 ^ (attempt - 1)) + random_jitter

Kini saatnya mempublikasikan arsitektur Trifecta Serverless NusaRoute AI ke Google Cloud:

1. Deploy Backend ke Google Cloud Run (Gen 2)

Jalankan perintah deployment dengan flag arsitektur berikut:

cd backend
gcloud run deploy nusaroute-api \
  --source . \
  --region asia-southeast2 \
  --platform managed \
  --allow-unauthenticated \
  --memory 1Gi \
  --cpu 1 \
  --min-instances 0 \
  --max-instances 3 \
  --no-cpu-throttling \
  --set-env-vars "NODE_ENV=production,PORT=8080"

Salin URL Service yang dihasilkan (contoh: https://nusaroute-api-xxx.asia-southeast2.run.app).

2. Deploy Frontend ke Firebase Hosting

Perbarui frontend/.env.local (atau frontend/.env):

VITE_BACKEND_URL=https://nusaroute-api-xxx.asia-southeast2.run.app
VITE_GOOGLE_MAPS_API_KEY=AIzaSy...

Jalankan build dan publikasikan ke jaringan CDN global Google:

cd ../frontend
npm run build
firebase deploy --only hosting

Aplikasi Anda kini aktif di https://.web.app.

3. Verifikasi Status Layanan Produksi

Periksa kesehatan daemon otonom dan analitik sistem langsung melalui endpoint:

Selamat! Anda telah menyelesaikan seluruh rangkaian hands-on NusaRoute AI di DevFest Cloud Surabaya 2026.

Apa Saja yang Telah Anda Kuasai?

Tautan & Resource Komunitas

Wani inovasi, wani ngoding! Sampai jumpa di sesi DevFest berikutnya.