Skip to content

Glossary

Key terms used across HUPH documentation. Sorted alphabetically.

Aria — the AI chatbot persona that users interact with on WhatsApp. Short for nothing — just a friendly name chosen to feel approachable to prospective students.

BGE-M3 — (legacy, removed April 2026) An open-source embedding model from BAAI producing both dense (1024-dimension) and sparse vectors in a single pass. HUPH used it via a self-hosted apps/rag Python service during Mar–early Apr 2026. Replaced by Dify + OpenAI embeddings. Do not expect it in the current repo.

BGE-reranker-v2-m3 — (legacy, removed April 2026) A cross- encoder from BAAI used to rerank top candidates after initial hybrid retrieval. Removed alongside apps/rag when the AI pipeline moved into Dify.

Channel — an entry point for user messages. As of April 2026, HUPH has exactly ONE active channel: WhatsApp (via 360dialog). Telegram and Web were deleted in the Apr 8 cleanup.

Claude Haiku — the Anthropic LLM used for response generation, intent classification (Layer 3 fallback), and eval judging. Current model ID: claude-haiku-4-5 (no date suffix). Called via Anthropic API direct (not AWS Bedrock).

Cluster — an academic grouping of UPH programs. HUPH has 5 clusters:

  • CASS (College of Arts & Social Sciences)
  • CBT (College of Business & Technology)
  • CHS (College of Health Sciences)
  • CIST (College of Information Science & Technology)
  • CNE (College of Nursing & Education)

Each cluster has dedicated counselors.

Cluster ownership (sticky vs flip) — HUPH's hybrid-lite ownership model. A lead's owner_source determines how it flips:

  • program_match — fluid, follows the latest program mentioned
  • register_intent — locks the cluster when user says "mau daftar"
  • manual — admin override, always wins

See escalation page.

Counselor Dashboard — Phase 1.6 admin view (merged Apr 9 via PR #2) showing per-counselor queue, KPIs, and scoped lead access.

Dify — self-hosted AI platform used by HUPH as the chat completion + annotation reply + KB management layer. Hosted at dify.huph.val.id. FAQ annotations match in ~300 ms, bypassing the full LLM pipeline.

Dify Annotation — a curated Q&A pair in Dify that matches user queries via fuzzy match. Bypasses LLM, returns in ~300 ms. HUPH's FAQ system syncs faq_local rows into Dify annotations.

Escalation — handing off a conversation from Aria to a human counselor. Sets conversations.status = 'escalated' and pauses the bot. Triggered by rules (frustrated user, long conversation) or a manual Take Over from the admin Inbox.

Escalation kind — one of two notification types:

  • escalation — title "Escalation: ", fired when action=escalate, status flips
  • notify — title "Hot lead: ", fired when action=notify, status untouched

FAQ vs KB — two different answer paths:

  • FAQ = curated exact-match pairs stored locally and synced to Dify annotations. Fast (~300 ms), no LLM.
  • Knowledge Base (KB) = semantic-search retrieval over crawled documents. Slower (~6 s), more flexible.

Feature flag — a boolean env var that gates a subsystem. HUPH's current flags:

  • LEAD_CAPTURE_ENABLED — lead capture Phase 2A pipeline
  • TEAM_OWNERSHIP_ENABLED — cluster resolver and ownership
  • ESCALATION_ROUTING_ENABLED — notification fan-out
  • API_AUTH_MODE — disabled | warn | enforce for Phase 0 auth

Golden QA dataset — a fixed set of 21 question-answer pairs used to measure RAG quality via Run Eval in the admin KB Evaluation tab. Baseline as of 2026-03-27: 95.2% pass rate (20/21), faithfulness 0.94, relevancy 0.93.

Hybrid search — combining dense vector similarity with sparse keyword matching, fused via RRF. Historically implemented in HUPH via self-hosted BGE-M3 + a direct Qdrant query; current architecture delegates retrieval to Dify's workflow which runs similar logic over Milvus.

Intent Router — Phase 1 4-tier classifier that routes incoming messages to the right handler before RAG. Tiers: deterministic regex → keyword heuristic → Claude Haiku → default.

JWE (NextAuth) — the encrypted JWT format used by NextAuth for session tokens. Crucially NOT a signed JWT — decoding requires next-auth/jwt encode/decode with the shared NEXTAUTH_SECRET, never jsonwebtoken.sign/verify. Silent failure if you confuse them.

Lead — a structured record with contact data (name, phone, email, program interest) extracted from conversations. Distinct from conversation — one conversation can yield 0 or 1 leads, and one lead can have many conversations.

Lead stage (real DB enum): incomplete → new → contacted → qualified → enrolled → lost

Milvus — the current vector database. Used by Dify for KB retrieval. Brought up via docker-compose.milvus.yml, separate from the main docker-compose.yml. Replaced Qdrant in late Mar / early Apr 2026.

Qdrant — (legacy, removed April 2026) The former vector database used by the old self-hosted RAG service. docker-compose.yml line 33 explicitly comments "Qdrant removed — replaced by Milvus". The qdrant_data volume is kept for 30 days as backup.

NextAuth — the auth library used by apps/admin for session management. Uses JWE cookies (not signed JWT). Custom admin_users table as the identity store, bcrypt password hashes.

Persona — the prompt scaffolding applied based on user type. Variables: user_type (fresh_student | parent | transfer), tone (ramah | formal | professional), address_style (Kamu | Anda | Bu/Pak), emoji_usage, answer_length, guidance_rules.

Phoenix — Arize Phoenix, used for OpenTelemetry trace collection on port 6006. Complements Langfuse (which does LLM- specific observability).

RAG (Retrieval-Augmented Generation) — the pattern HUPH uses for chatbot answers: retrieve relevant documents from a vector DB, then feed them to an LLM as context for generation. HUPH's implementation now lives entirely in the Dify stack (Dify handles embeddings, similarity search in Milvus, and LLM call). An older self-hosted apps/rag Python service ran this pipeline in Mar– early Apr 2026 but was replaced. See AI Pipeline architecture page.

RBAC Phase 1.5 — cluster-based access control on admin endpoints. marketing_counselor with cluster_id=X only sees cluster X leads + conversations. marketing_staff and marketing_admin are global.

RRF (Reciprocal Rank Fusion) — the algorithm used to fuse dense and sparse search results in hybrid retrieval. Each candidate gets a score based on its rank in each ranking, then summed across rankings. Used by HUPH historically in the direct Qdrant hybrid search; Dify's current workflow uses similar fusion semantics internally.

Socket.io — the realtime transport HUPH uses (replacing deprecated SSE). Runs embedded in the API server on port 3101 with /admin namespace. Authenticated via NextAuth JWE forwarded on the upgrade request.

Take Over — counselor action from the admin Inbox that escalates a conversation: sets conversations.status = 'escalated', assigns assigned_agent_id to the counselor, pauses Aria. Confirmed via a ConfirmDialog to prevent accidents.

Timezone trigger bug (WIB) — historical bug where timestamp without time zone columns got serialized without a UTC offset, causing the frontend to parse them as WIB local time and show "7 hours ago" for fresh events. Fixed 2026-04-08 via AT TIME ZONE 'UTC' casts in all 5 trigger functions.

UPH — Universitas Pelita Harapan. The university HUPH is built for. See uph.edu.

WhatsApp 24-hour window — WhatsApp Business API constraint: outbound free-form messages are only allowed within 24 hours of the user's last message. After that, you must use pre-approved Meta Template Messages (2–7 days review). Affects follow-up page.