Layanan API Tarantula

API Tarantula adalah backend utama platform RAGA — sebuah service NestJS yang mengelola workspace, seluruh sumber pengetahuan (knowledge source), riwayat percakapan, serta mengekspos Open API untuk integrasi eksternal. Service ini adalah "meja kerja" tempat data disusun sebelum dikirim ke mesin inferensi.

Perlu dicatat: penyusunan system prompt dan pemanggilan LLM (QWEN/GLM, sebagaimana dijelaskan di Raga Engine) dieksekusi oleh service chatbot-service yang terpisah. API Tarantula berperan sebagai orkestrator yang mengumpulkan konteks (dokumen, audio, database, API, topik) dan meneruskannya ke chatbot-service untuk diproses.

Tech Stack

Komponen	Teknologi
Runtime & Framework	Node.js 20, NestJS 10, TypeScript
Database utama	PostgreSQL, diakses via TypeORM
Cache & Queue	Redis-compatible (Dragonfly), antrian job via Bull
Index pencarian & knowledge	Elasticsearch (banyak index: chat history, audio, dokumen OCR, daftar RDBMS, daftar API, dsb.)
Penyimpanan file	Minio (object storage)
Manajemen secrets	Infisical — kredensial database, SMTP, Minio, Elasticsearch, dan URL layanan lain tidak disimpan di .env, melainkan ditarik saat boot dari Infisical
Email	Nodemailer, dikirim asinkron lewat Bull queue

Model Domain

Workspace adalah entitas pusat platform. Setiap workspace terhubung many-to-many ke lima jenis sumber pengetahuan, serta memiliki riwayat percakapannya sendiri:

Sumber Pengetahuan	Modul Terkait	Keterangan
Dokumen	documents, document-ocr, document-summaries, document-folder	Upload dokumen, ekstraksi OCR, ringkasan & NER
Audio	audios, audio-documents, audio-document-chunks, audio-document-summaries	Upload audio, transkripsi, chunk per pembicara, ringkasan
Topik (Basic Knowledge)	topics, topic-documents	Knowledge dasar yang selalu disertakan ke prompt
Database (RDBMS)	databases	Koneksi database eksternal, daftar tabel/kolom untuk Text-to-SQL
API eksternal	apis, endpoints	Definisi API eksternal & endpoint-nya untuk Text-to-API

Setiap jenis sumber pengetahuan punya modul *-users pasangannya (document-users, audio-users, topic-users, database-users, api-users, dst.) yang mengatur user mana saja yang boleh mengakses resource tersebut. Ini adalah pola akses per-resource yang diulang di setiap domain, bukan satu modul ACL generik.

Percakapan disimpan dalam dua lapis:

• room-chats — thread percakapan, terikat ke satu workspace.
• chat-histories — pesan per giliran chat di dalam sebuah room, menyimpan field knowledge_source (sumber pengetahuan mana yang dipakai untuk menjawab) dan response.

Peta Modul

Workspace & Akses

Modul	Fungsi
workspaces	Entitas workspace, agregasi seluruh knowledge source
workspace-users	Penugasan user ke workspace
workspace-roles	Penugasan role ke user dalam workspace
workspace-integrations	Konfigurasi integrasi eksternal per workspace
workspace-iframes	Konfigurasi widget/iframe embed + verifikasi app key

Percakapan

Modul	Fungsi
room-chats	Thread percakapan dalam workspace
chat-histories	Pesan per giliran chat, termasuk sumber pengetahuan yang dipakai
system-prompt / system-prompt-users	Pustaka template system prompt yang bisa dipakai ulang antar workspace
canvas	Endpoint uji coba (/canvas/execute) untuk mencoba kombinasi knowledge source & model LLM sebelum diterapkan ke workspace

Integrasi & Kompatibilitas

Modul	Fungsi
open-api	Permukaan API publik (chat, riwayat, verifikasi, iframe) — lihat Integrasi Ke Raga
openai-compat	Endpoint kompatibel format OpenAI, dipasang di namespace yang sama dengan Open API (GET /open-api/models, POST /open-api/chat/completions)
whatsapp	Manajemen sesi/QR WhatsApp dan tautannya ke workspace

Operasional & Sistem

Modul	Fungsi
model-management	Konfigurasi model LLM yang bisa dipasang ke workspace
dashboard	Analitik: penggunaan token, penggunaan LLM, pertanyaan terpopuler, wordcloud
activity-log	Pencatatan aktivitas user ke index Elasticsearch
settings	Pengaturan key-value generik
health	Health check gabungan seluruh dependensi service
mail	Pengiriman email asinkron via queue
infisical	Probe/debug koneksi ke Infisical

Integrasi Eksternal

API Tarantula tidak menjalankan inferensi LLM, OCR, transkripsi audio, atau ringkasan sendiri — semua didelegasikan ke service lain lewat HTTP, dikonfigurasi via environment variable:

Environment Variable	Tujuan
CHATBOT_URL	Layanan chatbot (chatbot-service) — penyusunan system prompt & inferensi LLM
DATABASE_CONNECT_URL	Layanan database-connect — koneksi RDBMS eksternal, list tabel/kolom, eksekusi query untuk Text-to-SQL
SUMMARIZE_URL	Layanan summarizer — ringkasan bertingkat untuk dokumen & transkrip audio
PDF_URL	Layanan OCR/ekstraksi PDF
SPEACHES_URL	Layanan transkripsi audio (speech-to-text)
WHATSAPP_URL	Gateway WhatsApp untuk modul whatsapp
LICENSE_API_URL	Layanan validasi lisensi untuk dashboard

Observability & Health

Endpoint GET /health (modul health, berbasis @nestjs/terminus) memverifikasi konektivitas ke: PostgreSQL, Minio, Elasticsearch, layanan PDF/OCR (PDF_URL), chatbot-service (CHATBOT_URL), database-connect (DATABASE_CONNECT_URL), dan gateway WhatsApp (WHATSAPP_URL). Redis/Dragonfly saat ini belum termasuk dalam pengecekan ini meskipun dipakai untuk cache dan queue.

Autentikasi & Akses

Ada dua permukaan API dengan mekanisme berbeda:

• Open API (/open-api/**, dipakai integrasi eksternal) — diverifikasi lewat app_key + workspace_id, lihat detail di Kirim Pesan Via API.
• API internal (dipakai dashboard/admin RAGA) — dibatasi lewat token yang dikirim di header Authorization, dengan cakupan akses ditentukan oleh penugasan workspace-users dan workspace-roles milik user tersebut.

Deployment & Konfigurasi

• Service berjalan di port 3000, dikemas lewat Dockerfile (produksi) dan docker-compose.dev.yml (development, menyertakan container PostgreSQL dan Dragonfly).
• Seluruh secret operasional (kredensial database, Redis, SMTP, Minio, Elasticsearch, nama index, URL layanan lain, batas ukuran upload, batas karakter chat, hingga token bot Telegram untuk alerting) dikelola lewat Infisical dan ditarik saat aplikasi start — bukan disimpan langsung di file .env.
• Migrasi database dijalankan terpisah lewat npm run migration:run sebelum service menerima trafik.

Ringkasan

API Tarantula adalah lapisan orkestrasi RAGA: mengelola workspace, lima jenis sumber pengetahuan, dan riwayat percakapan, lalu mendelegasikan pekerjaan berat (inferensi LLM, OCR, transkripsi, ringkasan, query RDBMS) ke service pendukung lain lewat HTTP. Open API menjadi satu-satunya pintu masuk yang didokumentasikan untuk integrasi pihak ketiga, terpisah dari permukaan API internal yang dipakai dashboard RAGA.