This page is the canonical developer overview for StratoFusion AI Search,
semantic indexing, and grounded Ask AI. It consolidates the root AI Search
planning files into one maintained architecture reference and links out to the
narrow module guides for implementation details.
Consolidated Sources
This page supersedes the root-level planning files:
AI Search adds meaning-aware retrieval and grounded question answering over
indexed user files without replacing provider-native basic or fulltext
search. The design keeps provider quirks behind adapters, keeps all indexed
content scoped by user and connected account, and treats answer generation as a
fail-soft layer that can only answer from retrieved citations.
Current Status
AI Search is implemented behind runtime rollout flags and remains disabled by
default. The current backend includes:
provider-neutral indexing adapters for Google Drive, OneDrive, and Dropbox.
deterministic extraction for the explicit supported-file allow-list.
chunking, embedding, semantic upsert, and semantic retrieval behind ports.
durable indexing job state, diagnostics, retry, cancel, dismiss, and health.
APIs under /api/search/indexing
runtime-gated semantic search with keyword fallback.
grounded POST /api/search/ask responses that return no_answer instead of.
fabricating when retrieval, grounding, or generation is insufficient
The user-facing AI indexing surface is /user/ai-indexing. AI indexing is
separate from transfer jobs; backup and sync stay under /user/jobs.
Diagrams
These Mermaid diagrams show the implementation from system context down to the
critical runtime flows. If a renderer does not support Mermaid, read each block
as structured pseudocode for the same architecture.
System Context
AI Search is a retrieval subsystem inside the Next.js app. It reuses the current
provider service layer for account-scoped access and keeps semantic
infrastructure behind ports.
Rendering diagram...
Indexing Pipeline
Indexing converts account-scoped provider resources into canonical semantic
chunks. Unsupported or failed files produce explicit item outcomes.
Rendering diagram...
Indexing Job Sequence
The UI never indexes directly. It asks the indexing route to create durable
work, then watches snapshots or SSE-style job events.
Rendering diagram...
Semantic Retrieval Path
AI Search mode reuses the normal search surface and scope filters. If semantic
infrastructure is unavailable, the route falls back instead of failing the whole
search.
Rendering diagram...
Grounded Ask AI Path
Ask AI is stricter than semantic search. It only returns an answer when the
retrieved evidence is usable and citations can be returned to the user.
Rendering diagram...
Data Isolation And Storage
The stable identity boundary is (userId, service, accountId, resourceId).
Vector entries and PostgreSQL rows must agree on that scope.
Rendering diagram...
Fail-Soft Decision Flow
AI infrastructure must degrade safely. Search can fall back to keyword results;
Ask AI returns no_answer rather than an ungrounded response.
Rendering diagram...
Architectural Decisions
Keep Search APIs Under /api/search
AI Search is an additive search mode, not a separate product silo. Existing
search routes keep ownership of search orchestration and reuse the same auth,
subscription, quota, service, account, and current-scope filters as the other
search modes.
Reuse The Existing Service Layer
The AI pipeline must not introduce a third provider abstraction. Provider
discovery and content retrieval flow through narrow AI-specific adapters that
wrap the existing provider services and return canonical indexing records.
Shared AI code sees canonical fields such as userId, service, accountId,
resourceId, parentResourceId, mimeType, modifiedAt, sizeBytes,
contentHash, eligible, and skipReason.
Preserve The Account Boundary
Every durable record and vector operation is scoped by:
(userId, service, accountId, resourceId)
Shared UI models must not expose provider-native paths, namespace headers,
drive IDs, vector backend IDs, or provider-specific pagination details.
Separate Discovery, Extraction, Chunking, And Retrieval
Extraction decides whether bytes contain supported text. Chunking decides how
that text is prepared for embeddings. Retrieval and RAG only consume indexed
chunks and canonical metadata.
Use Ports For AI Infrastructure
Embedding, semantic index, and grounded-answer generation are behind ports. The
current concrete adapters support OpenAI embeddings, Weaviate semantic indexing,
and OpenAI grounded answers, but shared callers resolve them through factories
and fail-soft wrappers.
Infrastructure failure returns disabled, unavailable, empty-hit, or no_answer
results instead of leaking provider exceptions into routes or UI.
Model Indexing As A State Machine
Indexing is long-running, resumable work. Durable job and item state is required
for page reloads, stale-run recovery, retry, cancellation, diagnostics, and
external mutation reconciliation.
Active user controls can cancel, retry, and dismiss visible job history. Broad
AI state reset remains admin-only because it deletes semantic vectors and PostgreSQL
metadata.
Module Layout
Primary implementation areas:
src/lib/search/ai/adapters/ - provider-specific indexing adapters and.
user-scoped service bridges
src/lib/search/ai/providers/ - embedding and semantic index ports.
factories, fail-soft wrappers, and concrete adapters
src/lib/search/ai/retrieval/ - grounded answer service and index coverage.
src/app/api/search/indexing/ - thin indexing API routes.
src/app/api/search/ask/route.ts - grounded Ask AI API route.
src/hooks/useAiSearchAvailability.ts, src/hooks/useAiIndexingJob.ts.
src/hooks/useAskAi.ts - UI data hooks
src/components/search/ - AI search, indexing, and Ask AI rendering.
Rollout Gates
AI Search has independent runtime gates:
subscription access to AI Search.
global search/indexing flags such as AI_SEARCH_ENABLED.
provider-specific flags for Google Drive, OneDrive, and Dropbox.
embedding provider configuration.
semantic index backend configuration.
grounded-answer provider configuration.
AI_RAG_ENABLED for Ask AI.
OCR-specific flags for standalone PNG/JPEG OCR.
Keep indexing, semantic retrieval, OCR, and grounded answers independently
disableable. Internal rollout order remains:
The scheduled external-change reconciliation path obeys the same indexing
gate. When AI_INDEXING_ENABLED is disabled, its authenticated production cron
route is a successful no-op and must not refresh provider tokens or enumerate
provider accounts.
Enable indexing for internal accounts and supported providers.
Validate semantic retrieval quality and fallback behavior.
Enable Ask AI only after citation quality is acceptable.
Expand file types or provider scopes behind targeted tests and rollback
flags.
Supported Content Policy
Indexing is intentionally limited to deterministic formats:
plain text, Markdown/MDX, source code, JSON/YAML/XML/CSV/TSV/HTML/SVG, and.
similar text-like formats
PDFs with extractable embedded text.
DOCX files with extractable plain text.
XLSX visible worksheet values.
PPTX visible slide text and speaker notes.
Google Docs, Sheets, Slides, and Drawings exported by Google Drive before.
extraction
standalone PNG/JPEG images only when OCR is enabled.
Unsupported, encrypted, corrupt, empty, oversized, unknown, or policy-skipped
files must be explicit item outcomes, not silent successes.
OpenXML extraction validates package metadata before parser dispatch. The
guard bounds entry count, per-entry and aggregate expansion, and compression
ratio, and rejects encrypted entries, ZIP64 size markers, absolute/traversal
entry names, and inconsistent central-directory metadata. Parser errors remain
sanitized and document contents are never logged.
Risk Controls
The highest-risk areas are:
multi-tenant vector isolation.
stale vectors after file updates, moves, deletes, account disconnects, or user.
deletion
provider token expiry during background work.
provider rate limits and partial provider outages.
embedding and vector query cost growth.
unsupported or low-quality extraction being misrepresented as searchable.
answers without citations being mistaken for grounded results.
Required mitigations:
scope all vector filters by userId, service, and accountId.
clear existing vectors for a file before replacement upserts.
reconcile dirty scopes after uploads, copies, moves, renames, deletes, backup.
sync, and provider change polling
fail fast when semantic infrastructure is unavailable.
return keyword fallback or no_answer instead of fabricating semantic results.
sanitize provider, parser, vector, and model errors before user display.
never log document content, OAuth tokens, raw provider errors, or raw extracted.
text
Test Focus
Unit tests should cover extraction policies, chunking, state transitions,
adapter metadata normalization, score merging, citation formatting, and fail-soft
adapter behavior.
Integration tests should cover indexing job lifecycle, provider adapter
discovery/download, user and account isolation, stale-index replacement,
semantic fallback, Ask AI no_answer, and route authorization.
Frontend tests should cover mode gating, indexing status rendering, diagnostics,
retry/cancel/dismiss controls, citation cards, mobile search controls, and
upgrade/paywall states.
Regression tests must continue to prove that basic, fulltext, direct
downloads, uploads, backup, sync, and rclone transfer flows are unaffected by
AI Search rollout.