--- id: SVC-PFM-QRY-quick-search title: Quick Search service module product_area: platform module: queries repository: services-platform source_module: modules/quick-search revision: 1 status: draft design_intent: confirmed implementation_evidence: observed inference: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-PFM-QRY-005 does_not_own: - CRM owns the contact and organization records and originating change notifications. - Queries owns projection vocabulary and the shared record-query interface. - >- The provider owns search document storage; Platform retains configuration, claims and progress ledgers. - Security defines record grants and authorizes the access request. operations: - operation_id: getQuickSearchHealth intent: Return this API’s health and deployed service identity. method: GET /quick_search/health access: public permission: 'none: public route' realises: - CAP-PFM-QRY-016 published_to_submissions: 'not published: diagnostic health read' provenance: observed source: 'services-platform:modules/quick-search/aws/api/quick-search.routes.ts:getQuickSearchHealth' - operation_id: issueQuickSearchAccess intent: >- Issue a workspace- and type-restricted provider credential after checking every requested type. method: 'POST /quick_search/{tenantId}/access' access: console permission: platform.quick-search.read realises: - CAP-PFM-QRY-016 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/quick-search/aws/api/quick-search.routes.ts:issueQuickSearchAccess' - operation_id: listQuickSearchConfigurations intent: Read permitted record-type field configuration and generation ledger state. method: 'GET /quick_search/{tenantId}/configurations' access: console permission: platform.quick-search-settings.read realises: - CAP-PFM-QRY-017 published_to_submissions: 'not published: information retrieval' provenance: observed source: >- services-platform:modules/quick-search/aws/api/quick-search.routes.ts:listQuickSearchConfigurations - operation_id: getQuickSearchConfiguration intent: 'Read one type’s settings, returning owner defaults when no saved configuration exists.' method: 'GET /quick_search/{tenantId}/configurations/{recordType}' access: console permission: platform.quick-search-settings.read realises: - CAP-PFM-QRY-017 published_to_submissions: 'not published: information retrieval' provenance: observed source: >- services-platform:modules/quick-search/aws/api/quick-search.routes.ts:getQuickSearchConfiguration - operation_id: listQuickSearchFields intent: Describe eligible and excluded dataset fields with indexing eligibility reasons. method: 'GET /quick_search/{tenantId}/configurations/{recordType}/fields' access: console permission: platform.quick-search-settings.read realises: - CAP-PFM-QRY-017 published_to_submissions: 'not published: information retrieval' provenance: observed source: 'services-platform:modules/quick-search/aws/api/quick-search.routes.ts:listQuickSearchFields' - operation_id: replaceQuickSearchConfiguration intent: Version-check a field-list replacement and request rebuild only for an effective change. method: 'PUT /quick_search/{tenantId}/configurations/{recordType}' access: console permission: platform.quick-search-settings.update realises: - CAP-PFM-QRY-017 published_to_submissions: 'not published: console work management' provenance: observed source: >- services-platform:modules/quick-search/aws/api/quick-search.routes.ts:replaceQuickSearchConfiguration - operation_id: rebuildQuickSearchIndex intent: Request rebuilding the current configured projection without changing its fields. method: 'POST /quick_search/{tenantId}/configurations/{recordType}/rebuild' access: console permission: platform.quick-search-settings.rebuild realises: - CAP-PFM-QRY-017 published_to_submissions: 'not published: console work management' provenance: observed source: 'services-platform:modules/quick-search/aws/api/quick-search.routes.ts:rebuildQuickSearchIndex' - operation_id: handleQuickSearchChangeEvents intent: Process at most one hundred CRM events and return per-event indexing outcomes. method: Lambda invoke platform_quick_search_indexer (CRM service role only) access: internal permission: 'none: IAM invoke grant to the CRM role on the live alias' realises: - CAP-PFM-QRY-017 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/quick-search/aws/api/quick-search.routes.ts (imported), aws/logic/*.ts, services/**, registry/record-types.ts, db/*.table.ts; docs/quick-search.md; docs/proposals/quick-search.md (approved 2026-10-09) - operation_id: runQuickSearchRebuild intent: >- Prepare, scan, reconcile and validate provider contents, then conditionally activate ledger progress. method: Step Functions platform-quick-search-rebuild with task function platform_quick_search_rebuild access: internal permission: 'none: started only by a rebuild request' realises: - CAP-PFM-QRY-017 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/quick-search/aws/api/quick-search.routes.ts (imported), aws/logic/*.ts, services/**, registry/record-types.ts, db/*.table.ts; docs/quick-search.md; docs/proposals/quick-search.md (approved 2026-10-09) - operation_id: runQuickSearchMaintenance intent: 'Resubmit targets, repair scope drift and clean retained deletion claims on their schedules.' method: Three EventBridge rules on platform_quick_search_maintenance access: internal permission: 'none: scheduled' realises: - CAP-PFM-QRY-017 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/quick-search/aws/api/quick-search.routes.ts (imported), aws/logic/*.ts, services/**, registry/record-types.ts, db/*.table.ts; docs/quick-search.md; docs/proposals/quick-search.md (approved 2026-10-09) - operation_id: quickSearchLifecycleParticipant intent: Provision registered search scopes and purge them during workspace deletion. method: workspace lifecycle participant platform.quick-search access: internal permission: 'none: invoked by the lifecycle jobs' realises: - CAP-PFM-QRY-017 published_to_submissions: 'not published: internal processing interface' provenance: observed source: >- services-platform at ad3f6a6: modules/quick-search/aws/api/quick-search.routes.ts (imported), aws/logic/*.ts, services/**, registry/record-types.ts, db/*.table.ts; docs/quick-search.md; docs/proposals/quick-search.md (approved 2026-10-09) events: - name: 'CRM change events (contacts, organizations, addresses, affiliations)' direction: consumed when: The CRM consumer submits a change batch. payload_summary: >- Events identify workspace, record type, record, change operation and relevant field names; snapshots support relevance checks. jobs: - >- The durable rebuild job prepares, scans, reconciles, validates and activates ledger progress, repeating bounded slices under four task invocations. - >- Maintenance separately resubmits targets every fifteen minutes, distributes nightly repair across six UTC hours and purges old deletion claims at 06:30 UTC. integrations: - system: Algolia direction: outbound contract: >- The provider supplies a shared environment index, derived browser keys and ordered document replacement using the configured secret. - system: CRM direction: inbound contract: CRM invokes the versioned indexer alias and consumes one result per event. - system: Workspace lifecycle (Platform) direction: inbound contract: >- The lifecycle participant provisions and verifies search scopes and purges provider documents before scope rows. consistency: - rule: Changing the target commits with the rebuild request it requires. kind: transactional compensation: Maintenance reoffers committed work whose state machine did not start. - rule: >- Activation compares the target in the ledger without switching separate provider document generations. kind: transactional compensation: >- Previously accepted replacements remain visible after failure; later repair must reconcile them. - rule: CRM event delivery updates search asynchronously. kind: eventual compensation: Failed events retry through CRM and scheduled reconciliation repairs remaining drift. - rule: An issued provider key retains its permissions until renewal or expiry. kind: eventual compensation: There is no individual key-revocation path; the configured lifetime is fifteen minutes. evidence: - >- services-platform at ad3f6a6: modules/quick-search/aws/api/quick-search.routes.ts (imported), aws/logic/*.ts, services/**, registry/record-types.ts, db/*.table.ts; docs/quick-search.md; docs/proposals/quick-search.md (approved 2026-10-09) - 'react-console at baf6dae: lib/quick-search/*.ts; components/console/quick-search/*.tsx' controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Quick Search service module ## What This Service Is For Quick Search maintains a derived typed-lookup projection and issues browser access to it. Contact and organization records remain CRM-owned. ## Boundary The registry determines record types and required grants. Dataset metadata supplies eligible fields, and the provider stores indexed values outside the business database. ## Operations in Words Access requests validate all requested types and can provision missing scopes. Configuration changes are versioned and can request rebuilds; internal operations process CRM events and scheduled maintenance. ## Events and Jobs CRM batch notifications feed indexing. Durable jobs perform rebuilds, with periodic resubmission, reconciliation and deletion-claim cleanup as distinct recovery work. ## Consistency Guarantees Target requests and ledger activation are transactional. Document replacement is eventual and can be visible during rebuild; fifteen-minute credentials also bound delayed permission withdrawal.