First Class Modules

Global secured search

Searches permitted records across modules and also uses permission-filtered vector retrieval to find meaningfully related information in indexed uploads, PDFs, images, screenshots, tables, diagrams, and text.

Use Global Search as the universal finder when users need to locate customers, files, work, conversations, events, custom records, or related evidence from uploaded content in one place.

What it does

Searches permitted records across modules and also uses permission-filtered vector retrieval to find meaningfully related information in indexed uploads, PDFs, images, screenshots, tables, diagrams, and text.

Key capabilities

• Run bounded text search across authorized modules and records.
• Search eligible indexed uploads, PDFs, images, screenshots, tables, diagrams, and extracted text in a shared vector space.
• Find conceptually related information even when the source uses different words from the query.
• Retrieve the original text, page, image, and source identity so results can retain evidence and citations.
• Filter by module and page through stable result envelopes.
• Show safe matched-field snippets plus module, status, location, relation, activity, and update context.
• Add or remove favorites without leaving the result list.

How vector and AI search improve discovery

Global Search has two complementary secured paths. Operational record search is best for exact names, identifiers, fields, statuses, and module records. The AI search path vectorizes eligible indexed content so a query can match by meaning, not only by identical keywords.

For example, a search for declining renewal risk can surface a customer record, a differently worded conversation, a chart on an uploaded PDF page, and a screenshot containing relevant evidence—provided each source is indexed, AI-eligible, and visible to the current user.

AI relevance is a discovery aid, not proof that every result is correct. Users can open the original source, page, or visual evidence to verify the result in context.

Common uses

• App-wide command and search experiences.
• Finding a record when its owning module is unknown.
• Discovering related material across records and uploaded documents.
• Finding a PDF page, image, screenshot, chart, table, or diagram from a natural-language description.
• Cross-module navigation in relationship-heavy applications.

How it connects

Record results point to the canonical record in its owning module. AI search uses the platform's secured source, document-element, chunk, visual-index, and vector retrieval chain; it returns original source/page/asset references instead of copying the evidence into a new business record.

Where applicable, its records use the universal RecordId conventions so they can participate in secured relationships, activity history, favorites, dynamic fields, notifications, Inbox attention, and global search without copying the source record.

Security and data boundary

The server applies SaaS, tenant, CanAiReadRecords, DataRole, location, record, field, and AI-eligibility rules before vector candidates or visual evidence can be returned. Unindexed, deleted, AI-excluded, or otherwise unauthorized content is absent from results. Relevance never grants access, and counts, snippets, citations, and related context must not reveal inaccessible records or fields.

• The authenticated service derives the SaaS app, tenant account, user, DataRole, and location scope; browser identifiers are never authorization proof.
• The page editor composes React components with validated data bindings. Those bindings call typed runtime APIs, whose application services execute reviewed stored procedures.
• List, search, detail, relation, activity, favorite, and write operations reapply their required server-side permissions.

Add it to an app

1. Open the SaaS app in the Developer Console and identify the user journey and page where this module belongs.
2. Add the validated module.global-search module block through the supported page/template authoring flow.
3. Configure the module with the page editor's React components and validated data bindings; the bindings call authenticated platform APIs backed by reviewed stored procedures.
4. Place the page in the correct user-type menus and assign existing DataRole, record, field, and location permissions.
5. Test list, detail, search, empty, denied, stale-update, and cross-location behavior before publishing an exact version.

Copy/paste the complete Global Search page

The native block gives users bounded cross-module record search, server-provided matched fields, module/location context, relation/activity counts, paging, and favorites.

{
  "blocks": [
    { "_id": "find-anything", "_type": "module.global-search", "props": {}, "children": [] }
  ]
}

Custom unstyled React search

Search requests at most 100 already-authorized rows per page, within a 5,000-match browsing window. Refine filters to reach other records. includeTotal=false is the default; hasMore is the safe next-page signal. The separate secured count endpoint can return the full authorized total without delaying row rendering. See progressive loading and exact counts; a missing or failed count is not zero. Do not download every module and filter it in the browser.

import { FormEvent, useEffect, useRef, useState } from "react";
import type { GlobalSearchItem, GlobalSearchResponse } from "@buildwithhq/module-sdk";
import { searchGlobalRecords } from "./api";

const empty: GlobalSearchResponse = { contractVersion: 1, query: "", pageNumber: 1, pageSize: 50, totalRecords: 0, totalPages: 0, totalIsExact: false, hasMore: false, modules: [], items: [] };

export function UnstyledGlobalSearch({ locationId = "", onOpenRecord }: { locationId?: string; onOpenRecord?: (item: GlobalSearchItem) => void }) {
  const [draft, setDraft] = useState("");
  const [query, setQuery] = useState("");
  const [moduleKey, setModuleKey] = useState("");
  const [page, setPage] = useState(1);
  const [result, setResult] = useState<GlobalSearchResponse>(empty);
  const [error, setError] = useState<string | null>(null);
  const request = useRef(0);

  useEffect(() => {
    const version = ++request.current;
    const controller = new AbortController();
    searchGlobalRecords(query, moduleKey, page, controller.signal, locationId, 50)
      .then(value => { if (version === request.current) setResult(value); })
      .catch((caught: unknown) => { if (!controller.signal.aborted && version === request.current) setError(caught instanceof Error ? caught.message : "Search failed."); });
    return () => controller.abort();
  }, [locationId, moduleKey, page, query]);

  function submit(event: FormEvent) {
    event.preventDefault();
    const normalized = draft.trim();
    if (normalized && normalized.length < 2) { setError("Enter at least two characters."); return; }
    setError(null); setPage(1); setQuery(normalized);
  }

  return <section className="custom-global-search">
    <h1>Search</h1>
    <form role="search" onSubmit={submit}><label>Search all visible records<input value={draft} maxLength={200} onChange={event => setDraft(event.target.value)} /></label><label>Module<select value={moduleKey} onChange={event => { setModuleKey(event.target.value); setPage(1); }}><option value="">All modules</option>{result.modules.map(module => <option key={module.moduleKey} value={module.moduleKey}>{module.moduleName}</option>)}</select></label><button>Search</button></form>
    {error && <p role="alert">{error}</p>}
    <p>{result.totalRecords}{result.totalIsExact ? "" : "+"} visible matches</p>
    <ol>{result.items.map(item => <li key={item.recordId}><article><header><span>{item.moduleName}</span><h2>{item.title}</h2></header><p>{item.recordStatus || "No status"} - {item.locationName || "All locations"}</p><dl>{item.matchedFields.map(field => <div key={field.fieldKey}><dt>{field.fieldLabel}</dt><dd>{field.matchedValue}</dd></div>)}</dl><small>{item.relationCount} relations - {item.activityCount} activity - matched {item.matchKind}</small>{onOpenRecord && <button type="button" onClick={() => onOpenRecord(item)}>Open in {item.moduleName}</button>}</article></li>)}</ol>
    <nav aria-label="Search pages"><button disabled={page <= 1} onClick={() => setPage(value => value - 1)}>Previous</button><span>Page {result.pageNumber}{result.totalIsExact ? ` of ${Math.max(1, result.totalPages)}` : ""}</span><button disabled={!result.hasMore} onClick={() => setPage(value => value + 1)}>Next</button></nav>
  </section>;
}

Favorite a result without broadening access

The result's moduleKey tells the shell which owning module should open it. There is intentionally no generic edit call: writes stay with the owning module's typed API.

import type { GlobalSearchItem } from "@buildwithhq/module-sdk";
import { searchGlobalRecords, setGlobalSearchFavorite } from "./api";

export async function toggleSearchFavorite(item: GlobalSearchItem) {
  return setGlobalSearchFavorite(item.recordId, !item.isFavorite);
}

export function reloadCurrentSearch(query: string, moduleKey: string, page: number, locationId = "") {
  return searchGlobalRecords(query, moduleKey, page, undefined, locationId, 50);
}

Optional starter styling

.custom-global-search { width: 100%; max-width: none; }
.custom-global-search form, .custom-global-search nav { align-items: end; display: flex; flex-wrap: wrap; gap: .75rem; }
.custom-global-search > ol { list-style: none; margin: 1rem 0; padding: 0; }
.custom-global-search > ol > li { border-bottom: 1px solid var(--line, #d8dee8); padding: 1rem 0; }
.custom-global-search article header { display: flex; gap: .75rem; justify-content: space-between; }
.custom-global-search article dl > div { display: grid; gap: .5rem; grid-template-columns: minmax(110px, 180px) minmax(0, 1fr); }
.custom-global-search article button { margin-top: .75rem; }

Exact data path and the AI-search boundary

The component above uses the current operational record-search contract; it does not falsely label a keyword request as vector search. Semantic and multimodal retrieval must use a separately published, validated AI binding that applies CanAiReadRecords, DataRole, location, field, source, and AI-eligibility filtering before candidates reach React. Keep interactive lookup bounded; use the governed AI-insights/data-graph path for whole authorized-graph analysis.

Build a professional Global secured search dashboard

These six registry-backed presentation blocks let a designer turn the secured Global secured search API into a complete admin page without writing a chart, grid, status badge, empty state, or timeline from scratch. The normal operational API begins at /api/modules/global-search; a dashboard-wide count or trend should come from a separate purpose-built presentation binding so the browser never downloads a broad record population to calculate one number.

The ZIP contains this feature's fictional design composition at pages/first-class/global-search-sample.json, its executable authenticated page at pages/first-class/global-search-live.json, and the catalog-driven FirstClassPresentationGallery.tsx. Use the sample only for visual design. The live page calls the real native API and reviewed stored procedures under the signed-in user's scope.

Copy/paste design preview: all six blocks

This complete static page document renders immediately in Puck/Monaco and is useful while styling a template. Its names, counts, dates, and IDs are fictional design fixtures; static preview values are not live tenant facts.

{
  "blocks": [
    {
      "_id": "global-search-metrics",
      "_type": "core.metric-strip",
      "props": {
        "title": "Search activity and discovery",
        "asOfUtc": "2026-09-04T18:00:00Z",
        "items": [
          {
            "key": "searches",
            "label": "Searches today",
            "value": 486,
            "format": "number",
            "tone": "primary"
          },
          {
            "key": "records",
            "label": "Record results opened",
            "value": 214,
            "format": "number",
            "tone": "success"
          },
          {
            "key": "visual",
            "label": "Visual matches",
            "value": 38,
            "format": "number",
            "tone": "neutral"
          },
          {
            "key": "zero",
            "label": "Zero-result queries",
            "value": 17,
            "format": "number",
            "tone": "warning"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "global-search-recent",
      "_type": "core.entity-list",
      "props": {
        "title": "Recently opened results",
        "hasMore": true,
        "items": [
          {
            "id": "global-search-sample-1",
            "recordId": "global-search-record-1",
            "primary": "North Wing closeout",
            "secondary": "Work Orders - exact and semantic match",
            "status": {
              "key": "relevant",
              "label": "Relevant",
              "tone": "success"
            },
            "trailing": "94%"
          },
          {
            "id": "global-search-sample-2",
            "recordId": "global-search-record-2",
            "primary": "North Wing closeout - Follow-up",
            "secondary": "Work Orders - exact and semantic match - Updated two hours ago by the assigned owner",
            "status": {
              "key": "in-review",
              "label": "In review",
              "tone": "primary"
            },
            "trailing": "Today"
          },
          {
            "id": "global-search-sample-3",
            "recordId": "global-search-record-3",
            "primary": "North Wing closeout - West region",
            "secondary": "Work Orders - exact and semantic match - Related to three visible records at the Reno location",
            "status": {
              "key": "on-track",
              "label": "On track",
              "tone": "success"
            },
            "trailing": "3 related"
          },
          {
            "id": "global-search-sample-4",
            "recordId": "global-search-record-4",
            "primary": "North Wing closeout - Customer response",
            "secondary": "Work Orders - exact and semantic match - Waiting for an external response before work can continue",
            "status": {
              "key": "scheduled",
              "label": "Scheduled",
              "tone": "warning"
            },
            "trailing": "Tomorrow"
          },
          {
            "id": "global-search-sample-5",
            "recordId": "global-search-record-5",
            "primary": "North Wing closeout - Regional operations review with a deliberately long title",
            "secondary": "Work Orders - exact and semantic match - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "status": {
              "key": "needs-attention",
              "label": "Needs attention",
              "tone": "danger"
            },
            "trailing": "Review",
            "tertiary": "Long-content fixture: verify keyboard focus, wrapping, narrow columns, and mobile overflow before publishing."
          },
          {
            "id": "global-search-sample-6",
            "recordId": "global-search-record-6",
            "primary": "North Wing closeout - Completed preview",
            "secondary": "Work Orders - exact and semantic match - Closed after review with its related evidence retained",
            "status": {
              "key": "complete",
              "label": "Complete",
              "tone": "success"
            },
            "trailing": "Closed"
          }
        ]
      },
      "children": []
    },
    {
      "_id": "global-search-bystatus",
      "_type": "core.progress-list",
      "props": {
        "title": "Results by source",
        "items": [
          {
            "key": "records",
            "label": "Business records",
            "value": 267,
            "maximum": 486,
            "displayValue": "267",
            "tone": "primary",
            "status": {
              "key": "records",
              "label": "Business records",
              "tone": "primary"
            }
          },
          {
            "key": "documents",
            "label": "Documents",
            "value": 143,
            "maximum": 486,
            "displayValue": "143",
            "tone": "success",
            "status": {
              "key": "documents",
              "label": "Documents",
              "tone": "success"
            }
          },
          {
            "key": "visuals",
            "label": "Images and diagrams",
            "value": 76,
            "maximum": 486,
            "displayValue": "76",
            "tone": "neutral",
            "status": {
              "key": "visuals",
              "label": "Images and diagrams",
              "tone": "neutral"
            }
          }
        ]
      },
      "children": []
    },
    {
      "_id": "global-search-trend",
      "_type": "core.series-chart",
      "props": {
        "title": "Search and result activity",
        "variant": "bar",
        "defaultPeriodKey": "d7",
        "periods": [
          {
            "key": "d7",
            "label": "7 days",
            "labels": [
              "Fri",
              "Sat",
              "Sun",
              "Mon",
              "Tue",
              "Wed",
              "Thu"
            ],
            "series": [
              {
                "key": "primary",
                "label": "Searches",
                "tone": "primary",
                "values": [
                  8,
                  5,
                  4,
                  12,
                  15,
                  11,
                  17
                ]
              },
              {
                "key": "secondary",
                "label": "Results opened",
                "tone": "success",
                "values": [
                  6,
                  4,
                  3,
                  9,
                  12,
                  10,
                  14
                ]
              }
            ]
          }
        ]
      },
      "children": []
    },
    {
      "_id": "global-search-table",
      "_type": "core.presentation-grid",
      "props": {
        "title": "Recent authorized discoveries",
        "columns": [
          {
            "key": "result",
            "label": "Result",
            "type": "text",
            "align": "left"
          },
          {
            "key": "module",
            "label": "Module",
            "type": "text",
            "align": "left"
          },
          {
            "key": "match",
            "label": "Match",
            "type": "text",
            "align": "left"
          },
          {
            "key": "status",
            "label": "State",
            "type": "status",
            "align": "left"
          },
          {
            "key": "opened",
            "label": "Opened",
            "type": "date",
            "align": "left"
          }
        ],
        "rows": [
          {
            "id": "global-search-row-1",
            "recordId": "global-search-record-1",
            "cells": {
              "result": "North Wing closeout",
              "module": "Work Orders",
              "match": "Title and related PDF",
              "status": {
                "key": "relevant",
                "label": "Relevant",
                "tone": "success"
              },
              "opened": "2026-09-04T17:36:00Z"
            }
          },
          {
            "id": "global-search-row-2",
            "recordId": "global-search-record-2",
            "cells": {
              "result": "North Wing closeout - Follow-up",
              "module": "Work Orders",
              "match": "Title and related PDF",
              "status": {
                "key": "in-review",
                "label": "In review",
                "tone": "primary"
              },
              "opened": "2026-09-04T15:42:00Z"
            }
          },
          {
            "id": "global-search-row-3",
            "recordId": "global-search-record-3",
            "cells": {
              "result": "North Wing closeout - West region",
              "module": "Work Orders",
              "match": "Title and related PDF",
              "status": {
                "key": "on-track",
                "label": "On track",
                "tone": "success"
              },
              "opened": "2026-09-04T12:18:00Z"
            }
          },
          {
            "id": "global-search-row-4",
            "recordId": "global-search-record-4",
            "cells": {
              "result": "North Wing closeout - Customer response",
              "module": "Work Orders",
              "match": "Title and related PDF",
              "status": {
                "key": "scheduled",
                "label": "Scheduled",
                "tone": "warning"
              },
              "opened": "2026-09-03T21:07:00Z"
            }
          },
          {
            "id": "global-search-row-5",
            "recordId": "global-search-record-5",
            "cells": {
              "result": "North Wing closeout - Regional operations review with a deliberately long title",
              "module": "Work Orders - This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
              "match": "Title and related PDF",
              "status": {
                "key": "needs-attention",
                "label": "Needs attention",
                "tone": "danger"
              },
              "opened": "2026-09-03T16:31:00Z"
            }
          },
          {
            "id": "global-search-row-6",
            "recordId": "global-search-record-6",
            "cells": {
              "result": "North Wing closeout - Completed preview",
              "module": "Work Orders",
              "match": "Title and related PDF",
              "status": {
                "key": "complete",
                "label": "Complete",
                "tone": "success"
              },
              "opened": "2026-09-02T19:14:00Z"
            }
          }
        ],
        "page": {
          "pageNumber": 1,
          "pageSize": 6,
          "totalRecords": 486,
          "totalIsExact": true,
          "hasMore": true
        }
      },
      "children": []
    },
    {
      "_id": "global-search-timeline",
      "_type": "core.timeline",
      "props": {
        "title": "Search activity",
        "hasMore": true,
        "items": [
          {
            "id": "global-search-event-1",
            "recordId": "global-search-record-1",
            "occurredUtc": "2026-09-04T17:58:00Z",
            "title": "Authorized result opened",
            "description": "North Wing closeout was opened from a permission-filtered search result.",
            "actor": "Maya Chen",
            "tone": "primary"
          },
          {
            "id": "global-search-event-2",
            "recordId": "global-search-record-2",
            "occurredUtc": "2026-09-04T15:42:00Z",
            "title": "Authorized result opened - Follow-up",
            "description": "North Wing closeout was opened from a permission-filtered search result. Updated two hours ago by the assigned owner.",
            "actor": "Avery Patel",
            "tone": "primary"
          },
          {
            "id": "global-search-event-3",
            "recordId": "global-search-record-3",
            "occurredUtc": "2026-09-04T12:18:00Z",
            "title": "Authorized result opened - West region",
            "description": "North Wing closeout was opened from a permission-filtered search result. Related to three visible records at the Reno location.",
            "actor": "Sam Rivera",
            "tone": "success"
          },
          {
            "id": "global-search-event-4",
            "recordId": "global-search-record-4",
            "occurredUtc": "2026-09-03T21:07:00Z",
            "title": "Authorized result opened - Customer response",
            "description": "North Wing closeout was opened from a permission-filtered search result. Waiting for an external response before work can continue.",
            "actor": "Maya Chen",
            "tone": "warning"
          },
          {
            "id": "global-search-event-5",
            "recordId": "global-search-record-5",
            "occurredUtc": "2026-09-03T16:31:00Z",
            "title": "Authorized result opened - Regional operations review with a deliberately long title",
            "description": "North Wing closeout was opened from a permission-filtered search result. This deliberately longer supporting line verifies wrapping, truncation, responsive spacing, and dense dashboard behavior.",
            "actor": "Automation",
            "tone": "danger"
          },
          {
            "id": "global-search-event-6",
            "recordId": "global-search-record-6",
            "occurredUtc": "2026-09-02T19:14:00Z",
            "title": "Authorized result opened - Completed preview",
            "description": "North Wing closeout was opened from a permission-filtered search result. Closed after review with its related evidence retained.",
            "actor": "Jordan Lee",
            "tone": "success"
          }
        ]
      },
      "children": []
    }
  ]
}

Copy/paste React composition

Copy InteractivePresentationComponents.tsx and its optional CSS from the Professional Foundation Developer Kit, then add this module-specific composition. It is semantic and unstyled by default; pass styled after importing interactive-presentation-components.css for the supplied polished foundation. Either version accepts only a bounded already-authorized document and fails closed through the shared strict parsers.

import {
  EntityList,
  MetricStrip,
  PresentationGrid,
  ProgressList,
  SeriesChart,
  Timeline,
} from "./InteractivePresentationComponents";

export interface GlobalSearchPresentationData {
  readonly metrics: unknown;
  readonly recent: unknown;
  readonly byStatus: unknown;
  readonly trend: unknown;
  readonly table: unknown;
  readonly timeline: unknown;
}

export interface GlobalSearchPresentationProps {
  /** Pass only the already-authorized presentation document returned by the API. */
  readonly data?: GlobalSearchPresentationData | null;
  readonly loading?: boolean;
  readonly error?: boolean;
  readonly styled?: boolean;
  /** Record identity is navigation context; the detail API must authorize it again. */
  readonly onOpenRecord?: (recordId: string) => void;
}

export function GlobalSearchPresentation({
  data,
  loading = false,
  error = false,
  styled = false,
  onOpenRecord,
}: GlobalSearchPresentationProps) {
  if (error) return <p role="alert">The Global secured search presentation could not be loaded.</p>;
  if (loading || !data) return <p role="status">Loading Global secured search presentation...</p>;

  return (
    <main className={styled ? "bwhq-api-example" : undefined}>
      <header>
        <p>Global secured search</p>
        <h1>Search activity and discovery</h1>
        <p>Authorized search usage, result types, saved discoveries, visual evidence, and recent queries.</p>
      </header>

      <MetricStrip data={data.metrics} styled={styled} />
      <div className={styled ? "bwhq-api-example__split" : undefined}>
        <ProgressList data={data.byStatus} styled={styled} />
        <EntityList data={data.recent} styled={styled} onOpenRecord={onOpenRecord} />
      </div>
      <SeriesChart data={data.trend} styled={styled} />
      <PresentationGrid data={data.table} styled={styled} onOpenRecord={onOpenRecord} />
      <Timeline data={data.timeline} styled={styled} onOpenRecord={onOpenRecord} />
    </main>
  );
}

Copy the live, authenticated module page

This document has no placeholder key and needs no invented endpoint. Save it to a page and add that page to a User Type menu. The registered native component calls /api/modules/global-search, uses the current tenant session, and preserves the module's real list, detail, create/update, pagination, empty, loading, and error behavior. Dynamic Records discovers the organization's real tenant-owned modules when no module key is configured.

{
  "blocks": [
    {
      "_id": "global-search-live",
      "_type": "module.global-search",
      "props": {},
      "children": []
    }
  ]
}

The server derives SaaS app, organization, user, DataRoles, locations, module-specific membership/privacy, and any AI-read gate from verified identity. A returned identifier can select a detail target, but the detail or write endpoint authorizes it again. Page layout, status, tone, totals, action names, and identifiers never grant authority.

Capability review: 2026-09-14. For exact current technical availability, use the generated API Map and first-class module inventory.