Appearance

Typesense Integration ​

File Information ​

  • Path: server/api/typesense/search.post.ts, app/composables/api/useSearchApi.ts
  • Purpose: Server-side Typesense search proxy and integration

Overview ​

Typesense is a fast, typo-tolerant search engine that powers the search functionality in the Brand Portal. This document covers the complete setup, configuration, and API integration for high-performance full-text search across digital assets, folders, and collages.

Architecture ​

System Components ​

  1. Typesense Server: Search engine server (self-hosted or cloud)
  2. Collections: Indexed data structures (digital_assets, folders, collages)
  3. Search API: Server-side proxy for Typesense operations
  4. Frontend Client: Search composables and components
  5. Search Store: Search state management

Key Features ​

1. Server-Side Search Proxy ​

  • Secure search API endpoint
  • Server-side Typesense API key (never exposed to client)
  • Request validation
  • Response transformation
  • Error handling

2. Multi-Collection Search ​

  • Search across multiple collections
  • Collection filtering
  • Unified search results
  • Result aggregation

3. Advanced Filtering ​

  • Tag filters
  • File type filters
  • Date range filters
  • Custom field filters
  • Workspace filtering

4. Sorting ​

  • Sort by relevance (default)
  • Sort by date (created, modified)
  • Sort by file size
  • Sort by file name
  • Ascending/descending order

5. Pagination ​

  • Page-based pagination
  • Results per page configuration
  • Total results count
  • Last page detection

File Structure ​

Core Files ​

Server API Routes ​

  • server/api/typesense/search.post.ts - Typesense search proxy

    • Server-side search execution
    • Typesense API key management
    • Request validation
    • Response transformation
    • Error handling

  • server/api/typesense/utils.ts - Typesense utilities

    • Search query building
    • Filter construction
    • Response formatting

Composables ​

  • app/composables/api/useSearchApi.ts - Search API composable
    • Search execution
    • Filter building
    • Query construction
    • Result processing

Stores ​

  • app/stores/search.ts - Search state management
    • Search query
    • Active filters
    • Search results
    • Pagination state

Configuration ​

Environment Variables ​

bash
TYPESENSE_HOST=search.example.com
TYPESENSE_PORT=443
TYPESENSE_PROTOCOL=https
TYPESENSE_API_KEY=your-api-key
SEARCH_KEY=public-search-key

Server Configuration ​

typescript
// server/api/typesense/search.post.ts
const typesenseConfig = {
  nodes: [{
    host: process.env.TYPESENSE_HOST,
    port: parseInt(process.env.TYPESENSE_PORT || '443'),
    protocol: process.env.TYPESENSE_PROTOCOL || 'https'
  }],
  apiKey: process.env.TYPESENSE_API_KEY
}

Search Flow ​

Search Execution ​

  1. User enters search query or applies filters
  2. Frontend builds search request
  3. Request sent to /api/typesense/search
  4. Server validates request
  5. Server calls Typesense API with secure key
  6. Typesense returns results
  7. Server transforms and returns results
  8. Frontend processes and displays results

Filter Building ​

  1. User selects filters (tags, file types, dates)
  2. Filters converted to Typesense filter_by syntax
  3. Filter query built
  4. Search executed with filters
  5. Results filtered accordingly

API Endpoints ​

  • Endpoint: POST /api/typesense/search
  • Request:
    typescript
    {
  request: {
    q: string,              // Search query
    collections: string[],  // Collections to search
    sort_by: string        // Sort expression
  },
  filterQuery: object,     // Collection filters
  commonSearchParams: {
    query_by: string,      // Fields to search
    per_page: number,      // Results per page
    page: number          // Page number
  },
  workspace_id_filter: string
}
  • Response:
    typescript
    {
  digital_assets: {
    data: {
      hits: Asset[],
      found: number,
      page: number
    }
  }
}

Security Features ​

  1. Server-Side API Key: Typesense API key never exposed to client
  2. Request Validation: All requests validated on server
  3. Workspace Filtering: Automatic workspace filtering
  4. Permission Checks: Search permissions validated

Performance Optimizations ​

  1. Server-Side Proxy: Reduces client-side complexity
  2. Caching: Search results can be cached
  3. Pagination: Efficient pagination prevents large result sets
  4. Filter Optimization: Optimized filter queries