SearchSignal is an inspectable ecommerce catalog-readiness and retrieval-quality framework. It helps teams find catalog defects, normalization gaps, and search risks before they deploy or migrate keyword, semantic, or hybrid product search.
Search quality depends on the product data behind it. Inconsistent identifiers, ambiguous prices and availability, sparse descriptions, and unnormalised attributes can turn a search migration into a production data problem. Teams need evidence that catalog records are valid, explicit, and eligible before they index or serve them.
SearchSignal maps source records into a canonical product contract, validates required evidence, applies explicit normalization rules, scores catalog readiness, and records eligibility decisions before document admission. Its synthetic demonstrator exposes keyword, deterministic semantic, and hybrid retrieval alongside golden-query evaluation.
The deployed synthetic demonstrator is available at search-signal.vercel.app.
/explains the framework and its limits./demodemonstrates deterministic retrieval over fictional products./consoleshows a read-only catalog-readiness workflow.
Every catalog and result in these surfaces is synthetic. The demonstrator has no merchant data, live Typesense connection, or production-readiness claim.
Catalog → map → validate → normalize → assess readiness → determine eligible documents → evaluate retrieval
Curated public screenshots are added only from verified production or matching-preview captures. The mandatory final 200%-zoom evidence is still open as P-011E; see the live QA report for the current evidence boundary.
flowchart LR
source["Synthetic catalog fixtures"] --> connector["Connectors and mapping"]
connector --> core["Canonical validation"]
core --> normalization["Explicit normalization"]
normalization --> readiness["Readiness and eligibility"]
readiness --> retrieval["Deterministic retrieval"]
retrieval --> demo["Next.js demo and console"]
retrieval --> evaluation["Golden-query evaluation"]
provider["Future: Typesense and embeddings"] -.-> retrieval
store["Future: durable persistence"] -.-> readiness
The architecture guide distinguishes current synthetic, deterministic components from future live-provider and persistence boundaries.
apps/web Next.js public surfaces and API routes
packages/* Catalog, retrieval, evaluation, and operational contracts
data Server-only synthetic fixtures and configuration
docs Evidence, architecture, runbooks, and product materials
scripts Deterministic verification and release-readiness checks
- Keep the critical path deterministic and grounded in normalized catalog fields.
- Make the synthetic/demo boundary explicit; synthetic data never becomes a production fallback.
- Fail closed when production provider configuration is missing or incomplete.
- Normalize through named, inspectable rules rather than silent repair.
- Keep reference implementations bounded and non-durable until a live design is validated.
- Produce citeable readiness, retrieval, and release evidence.
TypeScript, pnpm workspaces, Next.js App Router, React, Zod, Vitest, and Vercel deployment configuration are verified in this repository. Typesense, an embedding provider, and PostgreSQL are future integration boundaries, not deployed SearchSignal services.
Use Node 22.x (see .nvmrc) and the pinned pnpm version.
pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test
pnpm buildSEARCHSIGNAL_DEMO_ENABLED=true is the only variable required for a demo-only preview. Provider, intake, and merchant-mode variables are optional, server-only, and must remain unset unless their corresponding boundaries are intentionally configured. See the keys-only environment reference and .env.example; never commit real values.
The current clean Node 22 run passed frozen installation, lint, typecheck, all 340 tests, build, and the 20-check Vercel-readiness validator. CI repeats the workspace verification ladder on pull requests and main; see the test plan.
SearchSignal is deployed as a Vercel monorepo project with the repository root as its root directory, pnpm install --frozen-lockfile, and pnpm --filter @searchsignal/web build. The verified settings and non-promoting procedure are in the deployment runbook.
- Synthetic data only; no merchant data is included.
- No production provider credentials are committed or exposed to the client.
- Missing provider configuration returns a sanitized
503; it never falls back to demo data. - Production readiness is unproven, and the project does not claim to be a production SaaS.
See SECURITY.md for reporting and boundary guidance.
SearchSignal has no live Typesense service, live embedding provider, Shopify connector, durable merchant persistence, live analytics, or multi-tenant SaaS infrastructure.
Possible merchant-pilot work begins with a live provider, durable evidence storage, a validated connector, and measured search analytics. Original Sprints 11–14 are reconciled replacement/backlog work, not completed features. Optional showcase improvements remain separate from product capability claims; see the roadmap reconciliation.
Portfolio project: complete
Synthetic demonstrator: complete
Merchant pilot: not implemented
Production SaaS: not implemented
Final actual-200%-zoom browser evidence (P-011E) remains open as a documentation-evidence item; see the live QA report. It does not block this public-release packaging.
- Architecture
- Portfolio case study
- Deployment runbook
- Rollback runbook
- Security policy
- Contribution guide
- Changelog
No license file is currently declared in this repository. The owner must choose and add a license before public reuse can be granted.