Search System Architecture

Scope

The search system defines an OS-native resource discovery layer for Prox OS apps. @prox-os/search owns searchable objects, query contracts, local search helpers, adapter examples, UI primitives, mock data, and Storybook examples.

Indexing pipelines, persistence, backend search APIs, embeddings, vector search, permission enforcement, OS routing, and execution remain outside this package.

Position

Search owns searchable objects, queries, local adapters, and search UI.
Apps own domain meaning.
Runtime and backend layers own indexing, providers, permissions, routing, and execution.

This lets Prox OS search across apps, documents, files, notifications, collaboration objects, AI sessions, security events, workspace resources, developer tooling, and future community resources without coupling the primitive package to a backend search service.

Search Versus Command And Activity

Search answers "where is this resource or content?" Command answers "what can I launch or execute?" Activity answers "what happened over time?"

@prox-os/search can index commands and activity entries later, but it should not become the command palette or activity timeline.

Runtime-Agnostic Provider Boundary

Phase 1 ships a local adapter for mock documents. It does not bind to a provider.

Future provider adapters can implement a narrow interface:

search(query)
listFacets(query)
indexDocument(document)
removeDocument(documentId)
listRecentSearches(scope)
saveSearch(query)
subscribeToIndex(scope, callback)

Provider candidates remain future choices:

• local storage search provider;
• backend search API;
• Postgres full-text search;
• Meilisearch, Typesense, or Algolia;
• vector search and embeddings;
• permission-aware indexing;
• per-workspace index routing.

No provider is installed in Phase 1.

Event Flow

flowchart LR
  Domain["Domain object"] --> Document["OsSearchDocument"]
  Document --> Index["Local or future backend index"]
  Query["OsSearchQuery"] --> Index
  Index --> Result["OsSearchResult"]
  Result --> UI["Search UI"]
  UI --> Intent["Action intent"]
  Intent --> Runtime["App or OS runtime"]
  Runtime --> Backend["Future backend/provider"]

The UI emits search events and optional action refs. The app/runtime decides what to open, which provider to query, and which permission or audit rules apply.

Data Model Sketch

classDiagram
  class OsSearchDocument {
    id
    kind
    title
    body
    source
    target
    accessLevel
  }
  class OsSearchQuery {
    text
    scope
    filters
    sort
    limit
  }
  class OsSearchFilter {
    field
    operator
    value
  }
  class OsSearchFacet {
    field
    values
  }
  class OsSearchResult {
    score
    rank
    matches
    actions
  }
  class OsSearchResponse {
    totalCount
    tookMs
    indexId
  }

  OsSearchQuery --> OsSearchFilter
  OsSearchResponse --> OsSearchResult
  OsSearchResponse --> OsSearchFacet
  OsSearchResult --> OsSearchDocument

Relationship To Frontend Packages

Permission And Privacy Considerations

• Search can express accessLevel, restricted status, redacted previews, and target metadata, but real permission enforcement belongs to runtime/backend policy.
• Private, security, billing, and AI-related results should be indexed and displayed only under workspace policy.
• Provider implementations must filter results before the UI receives them.
• Saved searches can reveal sensitive intent and should follow workspace privacy rules once persisted.
• Public community search should use separate indexes and moderation policy.

Why Phase 1 Avoids Backend And Vector Search

Search touches indexing, permissions, tenancy, privacy, ranking, freshness, observability, and data retention. Vector search also adds embedding providers, model changes, cost controls, and semantic relevance risks. Phase 1 keeps the package testable by shipping the contract, local adapter, mock data, UI surface, and provider seams first.

Phase Roadmap

Phase 1: Search Contracts And Local Primitives

• Types.
• Helpers.
• Local search adapter.
• Mock index.
• React primitives.
• Storybook examples.
• Action, app, command, collaboration, notification, document, resource, file, AI, security, and workspace adapters.
• Docs.

Phase 2: Provider Boundary And Local State

• OsSearchProvider interface.
• Local storage provider.
• Recent and saved search persistence adapter.
• Index update events.
• Permission-aware redaction helpers.
• Search analytics events.

Phase 3: OS Runtime Integration

• Top bar or desktop search panel.
• Command palette bridge.
• App, window, resource, and workspace scoped search.
• Notification, collaboration, activity, and search handoff.

Phase 4: Backend And Semantic Search

• Backend search API.
• Postgres full-text search.
• Meilisearch, Typesense, or Algolia provider.
• Vector search and embeddings.
• AI answer over search results.
• Per-workspace index routing.
• Public community resource search.

Non-Goals

• No real search backend.
• No crawler or embedding pipeline.
• No vector database.
• No command palette replacement.
• No notification center replacement.
• No collaboration or file manager ownership.
• No security dashboard.
• No activity timeline.
• No OS Shell private imports.