Teknis — API Tarantula

Service backend utama RAGA yang dibangun di atas NestJS. Bertanggung jawab sebagai core API layer — mengelola workspace, knowledge (dokumen, audio, database, API), chat, system prompt, user access, serta mengorkestrasikan panggilan ke engine eksternal (chatbot, OCR, summarize, speech).

Repository

Key	Value
Git Remote	`https://git.tlab.co.id/tarantula/tarantula-v2/service/api-tarantula.git`
Branch Aktif	`dev`
Branch Lain	`main`, `staging`, `refactor/code-integrations`

bash

git clone https://git.tlab.co.id/tarantula/tarantula-v2/service/api-tarantula.git
cd api-tarantula
git checkout dev

Tech Stack

Layer	Teknologi
Framework	NestJS 10 (TypeScript)
Database	PostgreSQL 16 via TypeORM 0.3
Cache / Queue	Redis 7 (ioredis + Bull)
Object Storage	MinIO
Search / Index	Elasticsearch 8.17
Secret Management	Infisical SDK v4
Logging	nest-winston (Winston 3.17)
Testing	Jest 29 + Supertest
Runtime	Node.js (Docker)

Environment Variables

File `.env` (Bootstrap Infisical)

File .env hanya memuat variabel bootstrap untuk autentikasi ke Infisical. Semua secret aplikasi diambil dari Infisical saat startup.

bash

INFISICAL_ENV=dev
INFISICAL_PATH=/
INFISICAL_SITE_URL=http://infisical-backend:8080
INFISICAL_CLIENT_ID=<client-id>
INFISICAL_CLIENT_SECRET=<client-secret>
INFISICAL_PROJECT_ID=<project-id>

Variable	Keterangan
`INFISICAL_ENV`	Environment target di Infisical (`dev` / `staging` / `prod`)
`INFISICAL_PATH`	Path secret di Infisical (default `/`)
`INFISICAL_SITE_URL`	URL Infisical server (self-hosted atau `https://app.infisical.com`)
`INFISICAL_CLIENT_ID`	Client ID untuk Universal Auth
`INFISICAL_CLIENT_SECRET`	Client Secret untuk Universal Auth
`INFISICAL_PROJECT_ID`	ID project Infisical yang menyimpan secrets service ini

Secrets via Infisical

Semua variabel berikut dikelola di Infisical dan di-inject ke process.env saat runtime oleh InfisicalService.

Database (PostgreSQL)

Variable	Keterangan
`DB_HOST`	Host PostgreSQL
`DB_PORT`	Port PostgreSQL (default `5432`)
`DB_USER`	Username PostgreSQL
`DB_PASSWORD`	Password PostgreSQL
`DB_NAME`	Nama database

Redis

Variable	Default	Keterangan
`REDIS_HOST`	`localhost`	Host Redis
`REDIS_PORT`	`6379`	Port Redis
`REDIS_PASSWORD`	—	Password Redis (opsional)

MinIO (Object Storage)

Variable	Default	Keterangan
`MINIO_ENDPOINT`	`localhost`	Endpoint MinIO
`MINIO_PORT`	—	Port MinIO (opsional)
`MINIO_SSL`	`false`	Gunakan SSL (`true`/`false`)
`MINIO_ACCESS_KEY`	—	Access key MinIO
`MINIO_SECRET_KEY`	—	Secret key MinIO
`MINIO_BUCKET`	`tarantula`	Nama bucket default
`MINIO_DOMAIN`	`https://s3.ziwardingai.xyz`	Domain publik dipakai untuk menyusun URL file yang diupload (dokumen, gambar chat, dsb.)

Elasticsearch

Variable	Default	Keterangan
`ELASTICSEARCH_HOST`	`http://localhost:9200`	URL Elasticsearch node
`ELASTICSEARCH_USERNAME`	—	Username Elasticsearch
`ELASTICSEARCH_PASSWORD`	—	Password Elasticsearch
`MAXIMUM_CHAT_PER_ROOM`	`2`	Batas maksimum pesan per room yang di-index
`INDEX_USER_ACTIVITY_LOG`	`user-activity-log`	Nama index Elasticsearch tempat `activity-log` menulis aktivitas user

Chatbot Engine (opa-data / VLLM)

Variable	Default	Keterangan
`CHATBOT_URL`	`http://192.168.0.25:8034`	Base URL engine chatbot
`MAX_CHAR_GENERATE_REPORT`	`100000`	Batas karakter untuk generate report

RDBMS Engine (database-connect)

Variable	Default	Keterangan
`DATABASE_CONNECT_URL`	`http://192.168.0.25:8105`	Base URL layanan `database-connect` untuk koneksi RDBMS eksternal & Text-to-SQL
`DATABASE_CONNECT_TIMEOUT`	`86400000`	Timeout (ms) untuk request ke `database-connect`

OCR / PDF Engine

Variable	Default	Keterangan
`PDF_URL`	`http://192.168.0.25:8090/api/v1`	URL service PDF/OCR Tarantula
`ENGINE_SOURCE_LOCAL`	`true`	Gunakan source file lokal untuk OCR

Summarize Engine

Variable	Default	Keterangan
`SUMMARIZE_URL`	`http://10.1.102.14:8014`	URL service summarize
`SUMMARIZE_TIMEOUT`	`86400000`	Timeout (ms) untuk proses summarize
`SUMMARIZE_ENABLE_NER`	`true`	Aktifkan Named Entity Recognition
`SUMMARIZE_CHUNK_SIZE`	`1000`	Ukuran chunk teks untuk summarize
`SUMMARIZE_TARGET_CONTEXT`	`128000`	Target context window LLM

Speaches (Speech-to-Text)

Variable	Default	Keterangan
`SPEACHES_URL`	`https://speaches.ziwardingai.xyz/v1`	URL service transcription
`SPEACHES_MODEL`	`turbo`	Model Whisper yang digunakan
`SPEACHES_DIARIZE`	`true`	Aktifkan speaker diarization
`SPEACHES_SUPPRESS_NUMERALS`	`false`	Suppress angka pada output

WhatsApp Integration

Variable	Default	Keterangan
`WHATSAPP_URL`	`http://192.168.0.27:18004`	URL WhatsApp Go service
`WHATSAPP_TIMEOUT`	`86400000`	Timeout (ms) koneksi WhatsApp

License Validation

Variable	Default	Keterangan
`LICENSE_API_URL`	`http://10.1.102.15:8003`	URL layanan validasi lisensi
`LICENSE_API_EMAIL`	`admin@mail.com`	Email untuk Basic Auth ke layanan lisensi
`LICENSE_API_PASSWORD`	`123456`	Password untuk Basic Auth ke layanan lisensi

Struktur Folder

api-tarantula/
├── src/
│   ├── app.module.ts               # Root module, bootstrap semua module
│   ├── main.ts                     # Entry point NestJS
│   │
│   ├── common/                     # Shared utilities, config, integrations
│   │   ├── config/                 # Config class tiap service eksternal
│   │   │   ├── chatbot.config.ts
│   │   │   ├── elasticsearch.config.ts
│   │   │   ├── minio.config.ts
│   │   │   ├── pdf-tarantula.config.ts
│   │   │   ├── rdbms.config.ts
│   │   │   ├── redis.config.ts
│   │   │   ├── speaches.config.ts
│   │   │   ├── summarize.config.ts
│   │   │   ├── typeorm.config.ts
│   │   │   └── whatsapp-go.config.ts
│   │   ├── decorator/               # Custom decorators
│   │   ├── dto/                     # Shared DTO (PaginationDto, ParamDto)
│   │   ├── exception/                # Custom exceptions
│   │   ├── filter/                   # Global exception filter
│   │   ├── helper/                   # PDF helper, safe JSON parse
│   │   ├── integrations/             # HTTP client tiap service eksternal
│   │   │   ├── chatbot/
│   │   │   ├── elasticsearch/
│   │   │   ├── minio/
│   │   │   ├── pdf-tarantula/
│   │   │   ├── rdbms/
│   │   │   ├── redis/
│   │   │   ├── speaches/
│   │   │   ├── summarize/
│   │   │   └── whatsapp-go/
│   │   ├── interceptor/              # Response interceptor (format standar)
│   │   ├── logger/                   # Telegram transport untuk Winston
│   │   ├── middleware/                # API key middleware, dynamic CSP
│   │   └── services/
│   │       └── document/              # Chunk document service
│   │
│   ├── db/
│   │   ├── migrations/               # TypeORM migrations (70+ file)
│   │   └── seeds/                     # Data seeder
│   │
│   ├── infisical/                    # Infisical secret loader & service
│   │
│   ├── activity-log/                 # Log aktivitas user
│   ├── apis/                         # Manajemen API eksternal di workspace
│   ├── api-users/                    # ACL: user akses ke API
│   ├── audio-document-chunks/        # Chunk audio transkripsi
│   ├── audio-document-summaries/     # Ringkasan audio document
│   ├── audio-document-users/         # ACL: user akses ke audio document
│   ├── audio-documents/              # Dokumen hasil transkripsi audio
│   ├── audio-users/                  # ACL: user akses ke audio
│   ├── audios/                       # Manajemen file audio
│   ├── canvas/                       # Fitur uji coba kombinasi knowledge & LLM
│   ├── chat-histories/               # Riwayat chat per room
│   ├── dashboard/                    # Data ringkasan dashboard
│   ├── database-users/               # ACL: user akses ke database
│   ├── databases/                    # Koneksi database eksternal (RDBMS)
│   ├── document-folder/              # Folder manajemen dokumen
│   ├── document-folder-users/        # ACL: user akses ke folder
│   ├── document-ocr/                 # Hasil OCR per dokumen
│   ├── document-summaries/           # Ringkasan dokumen
│   ├── document-users/               # ACL: user akses ke dokumen
│   ├── documents/                    # Manajemen dokumen (upload, metadata)
│   ├── endpoints/                    # Endpoint dari API eksternal
│   ├── health/                       # Health check endpoint
│   ├── log/                          # HTTP request logging middleware
│   ├── mail/                         # Email service (Bull queue + template)
│   ├── model-management/             # Manajemen model LLM per workspace
│   ├── open-api/                     # Permukaan API publik (app_key)
│   ├── openai-compat/                # OpenAI-compatible chat completion endpoint
│   ├── room-chats/                   # Room chat management
│   ├── settings/                     # Global setting aplikasi
│   ├── shared/                       # Shared service (JWT, auth helper)
│   ├── system-prompt/                # Manajemen system prompt workspace
│   ├── system-prompt-users/          # ACL: user akses ke system prompt
│   ├── topic-document-users/         # ACL: user akses ke topic document
│   ├── topic-documents/              # Relasi topic ↔ document
│   ├── topic-users/                  # ACL: user akses ke topic
│   ├── topics/                       # Manajemen topik knowledge
│   ├── utils/                        # Utility endpoint (misc)
│   ├── whatsapp/                     # Integrasi WhatsApp
│   ├── workspace-iframes/            # Konfigurasi iframe embed workspace
│   ├── workspace-integrations/       # Integrasi eksternal per workspace
│   ├── workspace-roles/              # Role management dalam workspace
│   ├── workspace-users/              # User membership workspace
│   └── workspaces/                   # Manajemen workspace (core entity)
│
├── test/                             # E2E tests
├── scripts/                          # Infisical CLI helper script
├── docker-compose.dev.yml            # Docker untuk development lokal
├── docker-compose.yml                # Docker untuk production/staging
├── Dockerfile.dev                    # Image development
├── Dockerfile                        # Image production
├── Dockerfile.stag                   # Image staging
├── nest-cli.json
├── tsconfig.json
└── package.json

Arsitektur Modul

Domain utama dikelompokkan ke dalam modul NestJS yang mengikuti pola controller → service → entity:

Workspace Core — workspaces, workspace-users, workspace-roles, workspace-integrations, workspace-iframes
Knowledge: Dokumen — documents, document-ocr, document-folder, document-summaries, topics, topic-documents
Knowledge: Audio — audios, audio-documents, audio-document-chunks, audio-document-summaries
Knowledge: Database & API — databases, apis, endpoints
Chat & Intelligence — room-chats, chat-histories, system-prompt, model-management, canvas, openai-compat
Auth & Access — shared (JWT), open-api, activity-log
Support — mail, health, settings, dashboard, whatsapp, infisical

Setiap knowledge source juga punya modul *-users pasangannya (document-users, audio-users, topic-users, database-users, api-users, dst.) untuk mengatur akses per-resource — lihat Ringkasan Arsitektur.

Modul Penting

Modul	Tanggung Jawab
`workspaces`	Entity inti RAGA; mengatur LLM, chain mode, stream, personalisasi, dan relasi ke semua knowledge
`documents`	Upload, metadata, status OCR, progress tracking dokumen PDF/file
`document-ocr`	Menyimpan hasil OCR per chunk; relasi ke service PDF Tarantula
`audios`	Upload file audio; memicu transkripsi ke service Speaches
`audio-documents`	Hasil transkripsi per segmen; status `is_publish_transcribe`
`topics`	Pengelompokan dokumen menjadi knowledge topic dalam workspace
`databases`	Koneksi RDBMS eksternal (PostgreSQL/MySQL) untuk fitur Text-to-SQL
`apis`	Definisi API eksternal yang bisa dipanggil oleh chatbot (Text-to-API)
`system-prompt`	Template system prompt workspace; mendukung tipe report dan prompt permanen
`model-management`	Konfigurasi model LLM yang tersedia per workspace (QWEN, GLM, dll.)
`chat-histories`	Menyimpan history percakapan per room; dipakai sebagai context oleh engine
`openai-compat`	Endpoint kompatibel OpenAI (`POST /open-api/chat/completions`, `GET /open-api/models`) untuk integrasi pihak ketiga — bukan di path `/v1/...`, melainkan menyatu dengan namespace `open-api`
`infisical`	Loader secret dari Infisical; menginisialisasi `process.env` sebelum modul lain berjalan
`activity-log`	Interceptor + decorator untuk mencatat setiap aksi user ke index Elasticsearch (`INDEX_USER_ACTIVITY_LOG`), bukan ke tabel database

Infrastruktur (Development)

Dijalankan via docker-compose.dev.yml:

bash

docker compose -f docker-compose.dev.yml up -d

Container	Image	Port	Keterangan
`api-jabarin`	`Dockerfile.dev` (NestJS)	3000	Aplikasi dengan hot-reload
`db-api-jabarin`	`postgres:16-alpine`	5432	PostgreSQL
`cached-api-jabarin`	`redis:7.4.5-alpine3.21`	6379	Redis untuk cache & Bull queue
`minio-jabarin`	`quay.io/minio/minio`	9000 (API), 9001 (Console)	Object storage untuk file upload
`es-jabarin`	`elasticsearch-wolfi:8.17.0`	9200, 9300	Single-node Elasticsearch untuk indexing

Semua container terhubung dalam network network-jabarin.

Integrasi Eksternal

Service	Env Var	Keterangan
Chatbot Engine (opa-data)	`CHATBOT_URL`	Engine chatbot RAGA; dipanggil untuk inferensi LLM
PDF Tarantula (OCR)	`PDF_URL`	Service OCR dokumen; menerima file PDF dan mengembalikan teks per chunk
Speaches (STT)	`SPEACHES_URL`	Whisper-based speech-to-text; dipakai untuk transkripsi audio
Summarize Engine	`SUMMARIZE_URL`	Service summarize + NER untuk dokumen dan audio
WhatsApp Go	`WHATSAPP_URL`	Bridge WhatsApp untuk integrasi chatbot via WA
Infisical	`INFISICAL_SITE_URL`	Secret management; semua env var sensitif diambil dari sini

Perintah Development

bash

# Install dependencies
npm install

# Jalankan development (hot-reload)
npm run start:dev

# Build production
npm run build

# Jalankan migrations
npm run migration:run

# Buat migration baru
npm run migration:create --name=NamaMigration

# Rollback migration
npm run migration:revert

# Run tests
npm run test

# Run tests + coverage
npm run test:cov

# Sync secrets baru ke Infisical
npm run sync:infisical

API Tarantula

User Service

OPA

OPA Auth

OPA Config

OPA Data

Summarizer

OCR

OCR V3

Minio Uploader

Database Connect

API Connect

Chatbot Service

Frontend

Raga License Env

Documentation Site

Teknis — API Tarantula

Repository

Tech Stack

Environment Variables

File `.env` (Bootstrap Infisical)

Secrets via Infisical

Struktur Folder

Arsitektur Modul

Modul Penting

Infrastruktur (Development)

Integrasi Eksternal

Perintah Development

OPA Auth

OPA Config

OPA Data

OCR V3

Teknis — API Tarantula ​

Repository ​

Tech Stack ​

Environment Variables ​

File .env (Bootstrap Infisical) ​

Secrets via Infisical ​

Struktur Folder ​

Arsitektur Modul ​

Modul Penting ​

Infrastruktur (Development) ​

Integrasi Eksternal ​

Perintah Development ​

Teknis — API Tarantula

Repository

Tech Stack

Environment Variables

File `.env` (Bootstrap Infisical)

Secrets via Infisical

Struktur Folder

Arsitektur Modul

Modul Penting

Infrastruktur (Development)

Integrasi Eksternal

Perintah Development