Search Roadmap and Architecture (#4030)
* search documentation and roadmap * fixup * add link to architecture issue * formatting * add nav to mkdocs yaml and microsite sidebar * use backstage search instead of backstage global search * add file extension to app_config * Update docs/features/search/README.md Co-authored-by: Himanshu Mishra <himanshu@orkohunter.net> * replace Big Picture with Architecture * search architecture wip * changes to architecture and documentation to it * update used user profiles according to the glossary * prettier ignore description * clarify architecture bullet points with examples Co-authored-by: Himanshu Mishra <himanshu@orkohunter.net>
This commit is contained in:
Emma Indal
@@ -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).
|
||||
@@ -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.
|
||||
|
||||
<img data-zoomable src="../../assets/search/architecture.drawio.svg" alt="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
|
||||
Reference in New Issue
Block a user