Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Search and Indexing Strategy

​

Hybrid Search Architecture

​

1. Firestore Native Search (Point Queries)

• Pros: Real-time consistency, no extra cost.
• Cons: No support for partial matches (fuzzy search) or complex “OR” queries.

​

2. Typesense (Full-Text Search — Primary)

• Multi-collection search: A single query fans out across all indexed collections via client.multiSearch.perform().
• Fuzzy matching: Supports typo-tolerant search on configurable query fields per collection.
• Faceted filters: Status, project, user, date-range filters are applied server-side via Typesense filter_by clauses.
• Hosted on Typesense Cloud (*.a2.typesense.net); no self-hosted infra required.

​

3. Fuse.js (Client-Side Fallback)

​

Indexed Collections

​

Data Synchronization

​

Firestore-to-Typesense Triggers

​

Sync Lifecycle

1. Trigger: onDocumentWritten fires on any create, update, or delete in the source collection.
2. Guard: If Typesense is not configured (isTypesenseConfigured() returns false), the trigger exits silently — the system degrades gracefully.
3. Schema Assurance: ensureCollection() creates the Typesense collection on first write (idempotent).
4. Transformation: The Cloud Function extracts a flat search document, converting Firestore Timestamp values to Unix milliseconds and stripping internal-only fields.
5. Upsert / Delete: upsertDocument() or deleteDocument() is called on the Typesense client.
6. Error Logging: Failures are logged via firebase-functions/v2 structured logger with document ID and collection name for observability.

​

Manual Reindex

// Client-side invocation
const reindex = httpsCallable(functions, 'reindexCollection');
await reindex({ collection: 'gm_projects', organizationId: 'org_abc' });

​

Frontend Search Service

​

Client Initialization

​

Multi-Collection Search

• query_by — collection-specific text fields.
• filter_by — always starts with organizationId:={orgId} (mandatory tenant isolation), then appends optional status/project/user filters.
• per_page — configurable limit per collection (default 10).
• highlight_full_fields — enables snippet highlighting for UI display.

​

RBAC Post-Filtering

• Collection-level: Each collection maps to one or more Permission enums. If the user lacks the required permission, the entire collection’s results are dropped.
• Ownership-level: For journals and expenses, non-approvers only see their own records (filtered by userId).
• Pre-optimization: Collections the user cannot access are excluded from the multiSearch request entirely, reducing payload and latency.

​

Result Transformation

• title, description, subtitle — human-readable display fields.
• navigationTarget — deep-link path (e.g., /projects/{id}, /expenses?id={id}).
• icon — Lucide icon name for UI rendering.
• score — Typesense text_match score for relevance ranking.
• matchedFields — fields that contributed to the match (for highlight display).

​

Vector Search (AI Discovery)

• Embedding: Text content is converted into vector arrays using Google Gemini models.
• Similarity search: Cosine similarity queries run against the vectorized grant listings.
• Hybrid scoring: Semantic results are combined with traditional filters (location, dollar amount) to produce a final Match Score.

​

Security and Tenancy

​

Server-Side (Cloud Functions)

• Every indexing trigger validates that organizationId exists before upserting. Documents without an organizationId are skipped and logged as warnings.
• The Typesense admin API key (used for writes) is stored as a Firebase Secret (TYPESENSE_API_KEY), never exposed to the client.

​

Client-Side (Frontend)

• The frontend uses a read-only Search API key (VITE_TYPESENSE_SEARCH_API_KEY) that cannot modify indices.
• Every search query programmatically injects organizationId:=${orgId} into filter_by — this is enforced in code, not via Typesense scoped keys.
• Data masking: Search results contain only the metadata needed for display. Full records are always fetched from Firestore when the user navigates to a detail view.

​

Callable Search Proxy (Recommended)

• Verifies authentication.
• Resolves caller tenant context from people collection.
• Rejects cross-tenant search unless caller is superadmin.
• Applies mandatory organizationId filters server-side before querying Typesense.
• Supports phased rollout with frontend feature flag:
• Enable: VITE_TYPESENSE_USE_CLOUD_FUNCTIONS=true
• Roll back: set VITE_TYPESENSE_USE_CLOUD_FUNCTIONS=false

​

Environment Configuration

​

Frontend (src/.env.local)

VITE_TYPESENSE_HOST=<cluster>.a2.typesense.net
VITE_TYPESENSE_SEARCH_API_KEY=<search-only-key>
VITE_TYPESENSE_PORT=443
VITE_TYPESENSE_PROTOCOL=https
VITE_TYPESENSE_ENABLED=true
VITE_TYPESENSE_USE_CLOUD_FUNCTIONS=false

​

Cloud Functions (functions/.env)

TYPESENSE_API_KEY=<admin-key>       # Write access; use Firebase Secrets in production
TYPESENSE_HOST=<cluster>.a2.typesense.net
TYPESENSE_PORT=443
TYPESENSE_PROTOCOL=https

​

Rollout Playbook (Secure Search Mode)

1. Deploy Functions containing searchTypesenseSecure.
2. Keep VITE_TYPESENSE_USE_CLOUD_FUNCTIONS=false and verify no regressions.
3. Enable VITE_TYPESENSE_USE_CLOUD_FUNCTIONS=true in staging frontend.
4. Validate command palette search:
   • works for normal user in own organization
   • rejects cross-tenant access
   • logs show non-zero searchTime and expected collections
5. Promote env flag to production.
6. If issues occur, immediately roll back by setting VITE_TYPESENSE_USE_CLOUD_FUNCTIONS=false.

​

Search Observability and Operations

​

Metrics Counters

• typesense_success
• secure_callable_error
• fuse_fallback_count

​

No-Result Query Capture

​

Nightly Jobs

• nightlyTuneSearchFromNoResults (02:00) - derives synonym updates + typo config from top no-result queries.
• nightlyReconcileSearchIndex (02:30) - compares Firestore vs Typesense collection counts and writes drift reports to searchReconciliationReports.

​

Key Source Files