Haya Routing Service - Documentation

Welcome to the Haya Routing Service documentation. This documentation is organized into three main guides:

📚 Documentation Index

1. Hierarchy Data Guide

Understanding the hierarchy system and data structure

This guide explains:

• How the level-based hierarchy system works
• Node structure and fields at each level
• Multi-tenant and multi-app isolation
• Role-based access control
• Embedding configuration
• Source texts collection
• Best practices and common patterns

Read this if you want to:

• Understand how hierarchy data is structured
• Learn about level-based architecture
• Configure nodes and their relationships
• Set up access control

2. API Documentation

Complete API reference

This guide covers:

• Routing APIs (POST /api/v1/route, batch routing)
• Hierarchy Management APIs (CRUD operations)
• Admin APIs (advanced operations)
• Source Texts APIs (embedding management)
• Cache Management APIs
• Health & Metrics APIs
• Error handling and status codes

Read this if you want to:

• Integrate with the API
• Understand request/response formats
• Manage hierarchy nodes programmatically
• Monitor system health

3. Routing Mechanics Guide

How routing decisions are made

This guide explains:

• Synonyms: Query expansion and matching
• Keywords: Boost/penalty keyword routing
• Query Intent: Intent detection and boosting
• Context: How context fields impact matching
• Weights: Field weight configuration
• Confidence Scores: How confidence is calculated
• Complete routing flow with examples

Read this if you want to:

• Understand how queries are matched
• Configure synonyms, keywords, and query intent
• Tune weights and confidence thresholds
• Debug routing issues

🚀 Quick Start

1. New to the system? Start with Hierarchy Data Guide to understand the data model
2. Want to integrate? Check API Documentation for endpoints
3. Need to tune routing? Read Routing Mechanics Guide for configuration

📖 Additional Resources

• Configuration Files: See config/ directory for weight and confidence configurations
• Example Data: See data/hierarchy-data.json for example hierarchy structure
• Test Queries: See test-queries.json for example routing requests

4. Configuration Guide

How to update and manage configuration data

This guide explains:

• How to update hierarchy-data.json (services, categories, collections)
• How to configure embedding weights
• How to adjust confidence settings
• How to update boost/penalty configurations
• Configuration workflow and best practices

Read this if you want to:

• Update routing keywords and boosts
• Tune embedding weights
• Adjust confidence thresholds
• Manage configuration files

5. Test Script Guide

How to use the test script

This guide covers:

• Running the test suite
• Understanding test results
• Adding new tests
• Debugging failed tests
• Continuous testing workflow

Read this if you want to:

• Validate routing behavior
• Test configuration changes
• Debug routing issues
• Integrate tests into CI/CD

🔍 Finding Information

By Topic

Hierarchy Structure:

• Hierarchy Data Guide - Core Concepts
• Hierarchy Data Guide - Hierarchy Node Structure

API Endpoints:

• API Documentation - Routing APIs
• API Documentation - Hierarchy Management APIs
• API Documentation - Admin APIs

Routing Logic:

• Routing Mechanics Guide - Synonyms
• Routing Mechanics Guide - Keywords
• Routing Mechanics Guide - Query Intent
• Routing Mechanics Guide - Weights
• Routing Mechanics Guide - Confidence Scores

💡 Common Use Cases

Setting Up a New Service

1. Read Hierarchy Data Guide - Registration
2. Use API Documentation - POST /api/v1/hierarchy/nodes
3. Configure Routing Mechanics Guide - Keywords

Tuning Routing Accuracy

1. Review Routing Mechanics Guide - Complete Routing Example
2. Update Configuration Guide - Hierarchy Data to adjust keyword boosts
3. Adjust Configuration Guide - Embedding Weights
4. Configure Configuration Guide - Confidence Config
5. Test changes using Test Script Guide

Debugging Routing Issues

1. Run Test Script Guide to identify failing tests
2. Check Routing Mechanics Guide - Routing Flow
3. Review Routing Mechanics Guide - Complete Routing Example
4. Use API Documentation - GET /api/v1/admin/hierarchy/nodes/:nodeId/source-texts to inspect embeddings
5. Update Configuration Guide based on test results

📝 Documentation Updates

This documentation is maintained alongside the codebase. If you find any issues or have suggestions, please update the relevant guide.

🎯 Key Concepts

• Level-Based Architecture: Level determines fields and behavior, type is metadata
• Multi-Tenant: All operations are scoped to tenant/app
• Role-Based Access: Access control at every level
• Semantic Matching: Vector embeddings for intelligent routing
• Configurable: Weights, keywords, synonyms, query intent all configurable

Happy routing! 🚀