diff --git a/docs/assets/search/architecture.drawio.svg b/docs/assets/search/architecture.drawio.svg new file mode 100644 index 0000000000..736d4545f0 --- /dev/null +++ b/docs/assets/search/architecture.drawio.svg @@ -0,0 +1,541 @@ + + + + + + + + + + + + + + +
+
+
+
+
+
+
+
+
+ + + + + + + + + + +
+
+
+
+
+
+
+
+
+ + + + + + + + + + + + + +
+
+
+ App Package: <Route path="/search" element={<... />} /> +
+
+
+ + + App Package: <Route path="/search" element={<... />}... + + + + + + + +
+
+
+ @backstage/plugin-search-backend +
+
+
+ + + @backstage/plugin-search-backend + + + + + + + +
+
+
+ Other Plugins +
+ (TechDocs, Catalogue, Etc) +
+
+
+ + + Other Plugins... + + + + + + + +
+
+
+
+ +
+ +
+
+
+
+ + + + + + + + +
+
+
+ @backstage/plugin-search +
+
+
+ + + @backstage/plugin-search + + + + + + + + + +
+
+
+ Other Backend Plugin (TechDocs, Catalogue, Etc) +
+
+
+ + + Other Backend Plugin (TechDocs, Catalogue, Etc) + + + + + + + +
+
+
+ Search Engine (Elastic, Solr, SaaS, etc.) +
+
+
+ + + Search Engine (Elastic, Solr, SaaS, et... + + + + + + + +
+
+
+ Search Engine Integration Layer +
+
+
+ + + Search Engine Integration Layer + + + + + + + + + + + + + + + +
+
+
+ + 1 2 3 + +
+
+
+ + + 1 2 3 + + + + + + + +
+
+
+ + X number of search results + +
+
+
+ + + X number of sear... + + + + + + + + + + + +
+
+
+ + Components + +
+
+
+ + + Components + + + + + + + + + +
+
+
+ Pass Search +
+ Term and Filters +
+ and then +
+ Return Results +
+
+
+ + + Pass Search... + + + + + + + +
+
+
+ + Search API + +
+
+
+ + + Search API + + + + + + + + + +
+
+
+ + Components + +
+
+
+ + + Components + + + + + + + + +
+
+
+ + Scheduler + +
+
+
+ + + Scheduler + + + + + + + +
+
+
+ + Gather Documents + +
+
+
+ + + Gather D... + + + + + + + + + + +
+
+
+ + Collate Documents +
+ Or Metadata + +
+
+
+ + + Collate Docum... + + + + + + + +
+
+
+ + API Endpoint +
+ +
+
+
+ + + API Endp... + + + + + + + +
+
+
+ + Query Processing + +
+
+
+ + + Query Processing + + + + + + + +
+
+
+ + Index Processing + +
+
+
+ + + Index Processi... + + + + + + + +
+
+
+ + Index Processing + +
+
+
+ + + Index Processi... + + + + + + + +
+
+
+ + Query Processing + +
+
+
+ + + Query Processing + + + + + + + +
+
+
+ + + Manage Index + +
+ Create, Remove, Replace Documents and Indices + +
+
+
+ + + Manage Index... + + + + + + + + + + +
+
+
+ + Compile and Execute Query from Term and Filters + +
+
+
+ + + Compile and Execut... + + + + + + + + + Viewer does not support full SVG 1.1 + + + + diff --git a/docs/features/search/README.md b/docs/features/search/README.md new file mode 100644 index 0000000000..0b13b47979 --- /dev/null +++ b/docs/features/search/README.md @@ -0,0 +1,100 @@ +--- +id: search-overview +title: Search Documentation +sidebar_label: Overview +# prettier-ignore +description: Backstage Search lets you find the right information you are looking for in the Backstage ecosystem. +--- + +# Backstage Search + +## What is it? + +Backstage Search lets you find the right information you are looking for in the +Backstage ecosystem. + +## Features + +- A federated, faceted search, searching across all entities registered in your + Backstage instance. + +- A search that lets you plug in your own search engine of choice. + +- A standardized search API where you can choose to index other plugins data. + +## Project roadmap + +| Version | Description | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Backstage Search V.0 ✅ | Search Frontend letting you search through the entities of the software catalog. [See V.0 Use Cases.](#backstage-search-v0) | +| Backstage Search V.1 ⌛ | Basic “out-of-the-box” in-memory indexing process of entities, and their metadata, registered to the Software Catalog. [See V.1 Use Cases.](#backstage-search-v1) | +| Backstage Search V.2 ⌛ | Search Backend responsible for the indexing process of entities, and their metadata, registered to the Software Catalog. [See V.2 Use Cases.](#backstage-search-v2) | +| Backstage Search V.3 ⌛ | Standardized Search API lets you index other plugins data to the search engine of choice. [See V.3 Use Cases.](#backstage-search-v3) | + +## Use Cases + +#### Backstage Search V.0 + +- As a software engineer I should be able to navigate to a search page and + search for entities registered in the Software Catalog. +- As a software engineer I should be able to use the search input field in the + sidebar to search for entities registered in the Software Catalog. +- As a software engineer I should be able to see the number of results my search + returned. +- As a software engineer I should be able to filter on metadata (kind, + lifecycle) when I’ve performed a search. +- As a software engineer I should be able to hide the filters if I don’t need to + use them. + +#### Backstage Search V.1 + +- As a software engineer I should be able to get a match of a search on all + entity metadata (e.g. owner, name, description, kind). +- As an integrator I should not have to plug in any search engine, instead I can + use the out of the box in-memory indexing process to index entities and their + metadata registered in the Software Catalog. + +#### Backstage Search V.2 + +- As an integrator I should be able to spin up an instance of ElasticSearch. +- As an integrator I should be able to define a ElasticSearch cluster in my + app_config.yaml where my data gets indexed to. + +more to come... + +#### Backstage Search V.3 + +- As a contributor I should be able to integrate plugin data to the indexing + process of Backstage Search by using the standardized API. +- As a software engineer I should be able to search for all content (for + example, entities, metadata, documentation) in backstage search. + +more to come... + +## Search Engines Supported + +See [Backstage Search Architecture](architecture.md) to get an overview of how +the search engines are used. + +| Search Engine | Support Status | +| ------------- | -------------- | +| ElasticSearch | Not yet ❌ | + +[Reach out to us](#feedback) if you want to chat about support for more search +engines. + +## Tech Stack + +| Stack | Location | +| --------------- | ------------------------ | +| Frontend Plugin | @backstage/plugin-search | +| Backend Plugin | ⌛ | + +## Feedback + +For any questions of feedback, reach out to us in the `#search` channel of our +[Discord chatroom](https://github.com/backstage/backstage#community). + +We are still looking for feedback to improve the architecture to fit your +use-case, see +[this open issue](https://github.com/backstage/backstage/issues/4078). diff --git a/docs/features/search/architecture.md b/docs/features/search/architecture.md new file mode 100644 index 0000000000..3075719b9d --- /dev/null +++ b/docs/features/search/architecture.md @@ -0,0 +1,39 @@ +--- +id: architecture +title: Search Architecture +description: Documentation on Search Architecture +--- + +# Search Architecture + +> _This is a proposed architecture which has not been implemented yet. We are +> still looking for feedback to improve the architecture to fit your use-case, +> see [this open issue](https://github.com/backstage/backstage/issues/4078)._ + +Below you can explore the Search Architecture. Our aim with this architecture is +to support a wide variety of search engines, while providing a simple developer +experience for plugin developers, and a good out-of-the-box experience for +Backstage end-users. + +Search Architecture + +At a base-level, we want to support the following: + +- We aim to enable the capability to search across the entire Backstage + ecosystem by decoupling search from content management. +- We aim to enable the capability to deploy Backstage using any search engine, + by providing an integration and translation layer between the core search + plugin and search engine specific logic that can be extended for different + search engines. We may also introduce the ability to replace the backend API + endpoint with a custom endpoint for simpler customization. + +More advanced use-cases we hope to support with this architecture include: + +- It should be easy for any plugin to expose new content to search. (e.g. entity + metadata, documentation from TechDocs) +- It should be easy for any plugin to append relevant metadata to existing + content in search. (e.g. location (path) for TechDocs page) +- It should be easy to refine search queries (e.g. ranking, scoring, etc.) +- It should be easy to customize the search UI +- It should be easy to add search functionality to any Backstage plugin or + deployment diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 1148f774da..f5a433fc84 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -72,6 +72,14 @@ "features/software-templates/extending/extending-preparer" ] }, + { + "type": "subcategory", + "label": "Backstage Search", + "ids": [ + "features/search/search-overview", + "features/search/architecture" + ] + }, { "type": "subcategory", "label": "TechDocs", diff --git a/mkdocs.yml b/mkdocs.yml index bceabf942e..99a96d77dc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -48,6 +48,9 @@ nav: - Create your own Templater: 'features/software-templates/extending/create-your-own-templater.md' - Create your own Publisher: 'features/software-templates/extending/create-your-own-publisher.md' - Create your own Preparer: 'features/software-templates/extending/create-your-own-preparer.md' + - Backstage Search: + - Overview: 'features/search/README.md' + - Architecture: 'features/search/architecture.md' - TechDocs: - Overview: 'features/techdocs/README.md' - Getting Started: 'features/techdocs/getting-started.md'