Search Architecture Documentation

Overview

The Mambu Documentation site uses Typesense Cloud for search functionality, with custom components for grouped, color-coded results by content type (User Guide, API v2, etc.).

Components

1. SearchBar (Navbar Dropdown)

Location: src/theme/SearchBar/index.tsx

• Custom Typesense-powered search component displayed in the navbar
• Shows grouped, color-coded results dropdown as you type
• Queries Typesense API in real-time with debouncing (300ms)
• Groups results by type: User Guide, API v2, API v1, Streaming, Functions, Payments
• Displays up to 5 results per type in the dropdown
• Pressing Enter or clicking "View all results" navigates to the full search page

Features:

• Keyboard navigation (Cmd/Ctrl+K to focus, arrow keys to navigate)
• Color-coded borders and badges for each content type
• Shows result title, description snippet, and URL
• Links to full search page for comprehensive results

2. Search Page

Location: src/pages/search.tsx

• Full-page search results with same Typesense backend
• Same grouping and color-coding as SearchBar
• Displays up to 8 results per type (more than dropdown)
• Accessed via:
  • Pressing Enter in SearchBar
  • Clicking "View all results" link
  • Direct URL: /search?q={query}

Features:

• Full-width search input
• Grouped results with section headers
• Color-coded result cards with badges
• URL query parameter sync for sharing links

3. Typesense Configuration

Typesense Cloud Instance:

• Host: 406zmegqr3v8s12jp-1.a1.typesense.net
• Collection: mambu_docs
• Search API Key: 9w8cPSteGpsftOesXEPfl25m1QiwcYZD (read-only)
• Admin API Key: 499IuNjbmBEC0UuAp2f3tvPPZ1YpQFIR (for indexing)

Search Features:

• Full-text search across title, description, and content
• Grouped by content type with priority sorting
• Faceted search by type
• Highlighting of search terms

Content Type Classification

Results are classified into these types based on file path:

Type	Path Pattern	Color	Priority	Label
user-guide	/docs/docs/	#0066cc (Blue)	1	User Guide
api-v2	/api/api-v2/	#4fb645 (Green)	2	API v2 Reference
api-v1	/api/api-v1/	#0065c9 (Blue)	3	API v1 Reference
streaming	/api/streaming/	#e74c3c (Red)	4	Streaming API
functions	/api/functions/	#f39c12 (Orange)	5	Functions API
payments	/api/payments-mpg/	#9b59b6 (Purple)	6	Payments API

Indexing Process

Indexing Script

Location: scripts/index-to-typesense.js

This script indexes all documentation files to Typesense Cloud:

How it works:

1. Scans docs/ directory recursively for .md and .mdx files
2. Parses frontmatter and content from each file
3. Uses frontmatter id field to generate correct URLs (important!)
4. Extracts title, description, content, and headings
5. Classifies content type based on file path
6. Uploads documents to Typesense in batches of 100

Key URL Generation Logic:

• If frontmatter has an id field, uses that to build the URL
• Example: File notifications-event-triggers.mdx with id: event-triggers → URL /docs/event-triggers
• This ensures search URLs match Docusaurus routing

Running the indexer manually:

npm run typesense:index

Note: Requires NODE_TLS_REJECT_UNAUTHORIZED=0 due to SSL certificate issue.

Automatic Indexing (CI/CD Only)

Indexing is DISABLED by default to keep local builds fast.

The indexing script is integrated into scripts/main.js but only runs when explicitly enabled:

ENABLE_TYPESENSE_INDEX=true yarn build

Recommended CI/CD Setup

Best practice: Run indexing as a separate job AFTER deployment completes.

Example GitLab CI configuration:

stages:
  - build
  - deploy
  - post-deploy

build:
  stage: build
  script:
    - yarn install
    - yarn build
  # Note: ENABLE_TYPESENSE_INDEX is NOT set here

deploy:
  stage: deploy
  script:
    - # Your deployment commands
  only:
    - main

update-search-index:
  stage: post-deploy
  script:
    - yarn install
    - npm run typesense:index
  environment:
    name: production
  only:
    - main
  when: on_success  # Only runs if deploy succeeded
  allow_failure: true  # Don't fail pipeline if indexing fails

Why this approach:

• ✅ Doesn't slow down local development
• ✅ Doesn't slow down the build/deploy process
• ✅ Only indexes when deploying to production
• ✅ Runs after deployment so it can't block releases
• ✅ Won't fail your deployment if indexing has issues
• ✅ Minimal Typesense API usage = lower costs

When Re-indexing Happens

With the recommended setup, the index updates:

• After successful deployment to production (main branch)
• Only when changes are merged to main
• Independent of the build/deploy process

Manual Indexing

For testing or emergency updates:

npm run typesense:index

Document Schema

Each indexed document has these fields:

{
  id: string,              // Base64 encoded file path (unique ID)
  title: string,           // From frontmatter or filename
  description: string,     // From frontmatter or first 200 chars
  content: string,         // Cleaned text content (up to 5000 chars)
  url: string,            // URL path (respects frontmatter 'id')
  type: string,           // Content type key (faceted)
  type_label: string,     // Display label for type
  priority: number,       // Sort priority (faceted)
  headings: string[],     // Up to 10 heading texts
  tags: string[],         // From frontmatter (optional, faceted)
  sidebar_label: string   // From frontmatter (optional)
}

Local Search Plugin (Unused)

Status: Installed but not used

The @easyops-cn/docusaurus-search-local plugin is configured in docusaurus.config.ts but creates a duplicate /search/ route that conflicts with the custom search page.

Current configuration causes warning:

[WARNING] Duplicate routes found!
- Attempting to create page at /search/, but a page already exists at this route.

Resolution options:

1. Remove local search plugin from docusaurus.config.ts (recommended - keep using Typesense)
2. Remove custom search page and use local plugin (would lose color-coding/grouping features)

Troubleshooting

Stale URLs in Search Results

Problem: Search returns old URLs (e.g., /docs/notifications-event-triggers instead of /docs/event-triggers)

Cause: Typesense index not updated after page URL changes

Solution: Re-run the indexing script:

npm run typesense:index

SSL Certificate Errors

Problem: SELF_SIGNED_CERT_IN_CHAIN error when indexing

Solution: Use NODE_TLS_REJECT_UNAUTHORIZED=0 environment variable (already set in package.json)

Search Not Working

1. Check browser console for API errors
2. Verify Typesense Cloud instance is accessible
3. Check API keys are correct in both SearchBar and search page
4. Ensure collection mambu_docs exists in Typesense

Files Modified for Search

• src/theme/SearchBar/index.tsx - Custom SearchBar component
• src/theme/SearchBar/styles.css - SearchBar styling
• src/pages/search.tsx - Full search page
• src/pages/search.css - Search page styling
• scripts/index-to-typesense.js - Indexing script
• package.json - Added typesense scripts
• docusaurus.config.ts - Local search plugin config (creates duplicate route)

Maintenance Tasks

Regular Maintenance

• Re-index after significant content updates: npm run typesense:index
• Monitor Typesense Cloud usage and billing
• Review search analytics if available

Future Improvements

• Automate re-indexing as part of deployment pipeline
• Add search analytics tracking
• Consider removing local search plugin to eliminate duplicate route warning
• Add pagination to search page for queries with many results
• Implement search suggestions/autocomplete
• Add search filters (by type, tags, etc.)