API Tarantula Service

API Tarantula is the main backend of the RAGA platform — a NestJS service that manages workspaces, all knowledge sources, conversation history, and exposes the Open API for external integrations. It is the "workbench" where data is assembled before being sent to the inference engine.

Note: system prompt construction and the actual LLM call (QWEN/GLM, as described in Raga Engine) are executed by a separate chatbot-service. API Tarantula acts as the orchestrator that gathers context (documents, audio, database, API, topics) and forwards it to chatbot-service for processing.

Tech Stack

Component	Technology
Runtime & Framework	Node.js 20, NestJS 10, TypeScript
Primary database	PostgreSQL, accessed via TypeORM
Cache & Queue	Redis-compatible (Dragonfly), job queue via Bull
Search & knowledge index	Elasticsearch (multiple indices: chat history, audio, document OCR, RDBMS list, API list, etc.)
File storage	Minio (object storage)
Secrets management	Infisical — database, SMTP, Minio, Elasticsearch credentials and other service URLs are not stored in .env, but pulled at boot time from Infisical
Email	Nodemailer, sent asynchronously via a Bull queue

Domain Model

Workspace is the platform's central entity. Each workspace is connected many-to-many to five types of knowledge sources, and owns its own conversation history:

Knowledge Source	Related Modules	Description
Documents	documents, document-ocr, document-summaries, document-folder	Document upload, OCR extraction, summary & NER
Audio	audios, audio-documents, audio-document-chunks, audio-document-summaries	Audio upload, transcription, per-speaker chunking, summaries
Topics (Basic Knowledge)	topics, topic-documents	Baseline knowledge always included in the prompt
Database (RDBMS)	databases	External database connections, table/column list for Text-to-SQL
External API	apis, endpoints	External API definitions and their endpoints for Text-to-API

Every knowledge source type has a matching *-users module (document-users, audio-users, topic-users, database-users, api-users, etc.) that controls which users may access that resource. This is a repeated per-resource access pattern, not a single generic ACL module.

Conversations are stored in two layers:

• room-chats — conversation threads, scoped to one workspace.
• chat-histories — individual chat turns within a room, storing a knowledge_source field (which knowledge source answered) and the response.

Module Map

Workspace & Access

Module	Function
workspaces	Workspace entity, aggregates all knowledge sources
workspace-users	Assigns users to a workspace
workspace-roles	Assigns roles to users within a workspace
workspace-integrations	External integration configs per workspace
workspace-iframes	Embeddable widget/iframe config + app key verification

Conversation

Module	Function
room-chats	Conversation threads within a workspace
chat-histories	Chat turns, including which knowledge source was used
system-prompt / system-prompt-users	Reusable system prompt template library, shareable across workspaces
canvas	Test endpoint (/canvas/execute) for trying a combination of knowledge sources & LLM model before applying it to a workspace

Integration & Compatibility

Module	Function
open-api	Public API surface (chat, history, verification, iframe) — see Integrations Intro
openai-compat	OpenAI-compatible endpoints, mounted under the same namespace as the Open API (GET /open-api/models, POST /open-api/chat/completions)
whatsapp	WhatsApp session/QR management and its link to a workspace

Operations & System

Module	Function
model-management	LLM model configs assignable to a workspace
dashboard	Analytics: token usage, LLM usage, top questions, wordclouds
activity-log	Records user activity to an Elasticsearch index
settings	Generic key-value settings
health	Aggregate health check across service dependencies
mail	Asynchronous email sending via queue
infisical	Infisical connection probe/debug

External Integrations

API Tarantula does not run LLM inference, OCR, audio transcription, or summarization itself — all of it is delegated to other services over HTTP, configured via environment variables:

Environment Variable	Purpose
CHATBOT_URL	Chatbot service (chatbot-service) — system prompt construction & LLM inference
DATABASE_CONNECT_URL	database-connect service — external RDBMS connections, table/column listing, query execution for Text-to-SQL
SUMMARIZE_URL	summarizer service — hierarchical summarization for documents & audio transcripts
PDF_URL	PDF/OCR extraction service
SPEACHES_URL	Audio transcription (speech-to-text) service
WHATSAPP_URL	WhatsApp gateway for the whatsapp module
LICENSE_API_URL	License validation service for the dashboard

Observability & Health

The GET /health endpoint (health module, built on @nestjs/terminus) verifies connectivity to: PostgreSQL, Minio, Elasticsearch, the PDF/OCR service (PDF_URL), chatbot-service (CHATBOT_URL), database-connect (DATABASE_CONNECT_URL), and the WhatsApp gateway (WHATSAPP_URL). Redis/Dragonfly is not currently included in this check despite being used for caching and queues.

Authentication & Access

There are two API surfaces with different mechanisms:

• Open API (/open-api/**, used by external integrations) — verified via app_key + workspace_id, see Send Message Via API for details.
• Internal API (used by the RAGA dashboard/admin) — restricted via a token sent in the Authorization header, with access scope determined by the user's workspace-users and workspace-roles assignments.

Deployment & Configuration

• The service runs on port 3000, packaged via Dockerfile (production) and docker-compose.dev.yml (development, including PostgreSQL and Dragonfly containers).
• All operational secrets (database, Redis, SMTP, Minio, Elasticsearch credentials, index names, other service URLs, upload size limits, chat character limits, and even the Telegram bot token for alerting) are managed through Infisical and pulled at application start — not stored directly in .env.
• Database migrations run separately via npm run migration:run before the service accepts traffic.

Summary

API Tarantula is RAGA's orchestration layer: it manages workspaces, five types of knowledge sources, and conversation history, then delegates heavy lifting (LLM inference, OCR, transcription, summarization, RDBMS queries) to supporting services over HTTP. The Open API is the only documented entry point for third-party integration, separate from the internal API surface used by the RAGA dashboard.