diff --git a/docs/assets/backend-system/architecture-building-blocks.drawio.svg b/docs/assets/backend-system/architecture-building-blocks.drawio.svg index 0244d461c6..6c0860be98 100644 --- a/docs/assets/backend-system/architecture-building-blocks.drawio.svg +++ b/docs/assets/backend-system/architecture-building-blocks.drawio.svg @@ -1,15 +1,11 @@ - + - - - - - + -
+
Backend @@ -17,16 +13,16 @@
- + Backend - + -
+
Services @@ -34,20 +30,52 @@
- + Services - - - - - + + -
+
+
+
+ Provide +
+
+
+ + + Provide + + + + + + + + +
+
+
+ Depend On +
+
+
+ + + Depend On + + + + + + + +
Plugins @@ -55,16 +83,16 @@
- + Plugins - + -
+
Extension Points @@ -72,20 +100,52 @@
- + Extension Poi... - - - - - + + -
+
+
+
+ Call +
+
+
+ + + Call + + + + + + + + +
+
+
+ Depend On +
+
+
+ + + Depend On + + + + + + + +
Modules @@ -93,19 +153,71 @@
- + Modules - - + + + + + +
+
+
+ Imports +
+
+
+ + + Imports + + + + + + + + +
+
+
+ Imports +
+
+
+ + + Imports + + + + + + + + +
+
+
+ Provides +
+
+
+ + + Provides + + + - Viewer does not support full SVG 1.1 + Text is not SVG - cannot display diff --git a/docs/backend-system/architecture/01-index.md b/docs/backend-system/architecture/01-index.md index e3354112fb..88ba3262df 100644 --- a/docs/backend-system/architecture/01-index.md +++ b/docs/backend-system/architecture/01-index.md @@ -6,16 +6,14 @@ sidebar_label: System Architecture description: The structure and architecture of the new Backend System and its component parts --- -# Overview +## Building Blocks This section introduces the high-level building blocks upon which this new system is built. These are all concepts that exist in our current system in one way or another, but they have all been lifted up to be first class concerns in -the new system. - -## Building Blocks - -This section introduces the high-level building blocks upon which this new system is built. Regardless of whether you are setting up your own backstage instance, developing plugins, or extending plugins with new features, it is important to understand these concepts. +the new system. Regardless of whether you are setting up your own backstage +instance, developing plugins, or extending plugins with new features, it is +important to understand these concepts. The diagram below provides an overview of the different building blocks, and the other blocks that each of them interact with. @@ -37,7 +35,7 @@ Plugins provide the actual features, just like in our existing system. They oper Services provide utilities to help make it simpler to implement plugins, so that each plugin doesn't need to implement everything from scratch. There are both many built-in services, like the ones for logging, database access, and reading configuration, but you can also import third-party services, or create your own. -Services are also a customization point for individual backend installations. You can both override services with your own implementations, as well as make smaller customizations to existing services. +Services are also a customization point for individual backend installations. You can override services with your own implementations, as well as make smaller customizations to existing services. ### Extension Points @@ -45,7 +43,7 @@ Many plugins have ways in which you can extend them, for example entity provider Extension Points look a little bit like services, since you depended on them just like you would a service. A key difference is that extension points are registered and provided by plugins themselves, based on what customizations each individual plugin wants to expose. -Extension Points are also exported separately from the plugin instance itself, and a single plugin can also expose multiple different extension points at once. This makes it easier to evolve and deprecated individual Extension Points over time, rather than dealing with a single large API surface. +Extension Points are also exported separately from the plugin instance itself, and a single plugin can also expose multiple different extension points at once. This makes it easier to evolve and deprecate individual Extension Points over time, rather than dealing with a single large API surface. ### Modules @@ -53,22 +51,20 @@ Modules use the plugin Extension Points to add new features for plugins. They mi Each module may only extend a single plugin, and the module must be deployed together with that plugin in the same backend instance. Modules may however only communicate with their plugin through its registered extension points. -Just like plugins, modules also have access to services and can depend on their own service implementations. They will however share services with the plugin that they extend, there are no module-specific service implementations. +Just like plugins, modules also have access to services and can depend on their own service implementations. They will however share services with the plugin that they extend - there are no module-specific service implementations. ## Package structure A detailed explanation of the package architecture can be found in the [Backstage Architecture Overview](../../overview/architecture-overview.md#package-architecture). The -most important packages to consider for this system are `backend`, -`plugin--backend`, `plugin--node`, and -`plugin--backend-module-`. +most important packages to consider for this system are the following: - `plugin--backend` houses the implementation of the backend plugins themselves. -- `plugin--node` houses the extension points and any other utilities +- `plugin--node` houses the backend plugin's extension points and any other utilities that modules or other plugins might need. - `plugin--backend-module-` houses the modules that extend - the plugins via the extension points. + the plugin via its extension points. - `backend` is the backend itself that wires everything together to something that you can deploy. diff --git a/docs/backend-system/index.md b/docs/backend-system/index.md index ca13bc188c..de598167ae 100644 --- a/docs/backend-system/index.md +++ b/docs/backend-system/index.md @@ -3,7 +3,7 @@ id: index title: The Backend System sidebar_label: Overview # prettier-ignore -description: The backend system +description: The Backend System --- > **DISCLAIMER: The new backend system is under active development and is not considered stable** @@ -12,4 +12,4 @@ description: The backend system The new backend system is under active development, and only a small number of plugins have been migrated so far. It is possible to try it out, but it is not recommended to use this new system in production yet. -You can find an example backend setup in [the backend-next package](https://github.com/backstage/backstage/tree/master/packages/backend-next). +You can find an example backend setup in [the `backend-next` package](https://github.com/backstage/backstage/tree/master/packages/backend-next).