diff --git a/docs/architecture-decisions/adr011-plugin-package-structure.md b/docs/architecture-decisions/adr011-plugin-package-structure.md index 363cae01a5..2def903dfc 100644 --- a/docs/architecture-decisions/adr011-plugin-package-structure.md +++ b/docs/architecture-decisions/adr011-plugin-package-structure.md @@ -35,9 +35,11 @@ We follow this structure for plugin packages (where `x` is the plugin name, for example `catalog` or `techdocs`): - `x`: Contains the main frontend code of the plugin. +- `x-module-`: Contains optional modules related to the frontend plugin + package. - `x-backend`: Contains the main backend code of the plugin. - `x-backend-module-`: Contains optional modules related to the backend - plugin. + plugin package. - `x-react`: Contains shared widgets, hooks and similar that both the plugin itself (`x`) and third-party frontend plugins can depend on. - `x-node`: Contains utilities for backends that both the plugin backend itself diff --git a/docs/overview/architecture-overview.md b/docs/overview/architecture-overview.md index 3425b02db9..13e2b66abb 100644 --- a/docs/overview/architecture-overview.md +++ b/docs/overview/architecture-overview.md @@ -164,6 +164,104 @@ https://circleci.com. ![CircleCI plugin talking to proxy talking to SaaS Circle CI](../assets/architecture-overview/circle-ci-plugin-architecture.png) +## Package Architecture + +Backstage relies heavily on NPM packages, both for distribution of libraries, +and structuring of code within projects. While the way you structure your +Backstage project is up to you, there is a set of established patterns that we +encourage you to follow. These patterns can help set up a sound project +structure as well as provide familiarity between different Backstage projects. + +The following diagram shows and overview the package architecture of Backstage. +It takes the point of view of an individual plugin and all of the packages that +it may contain, indicated by the thicker border and italic text. Surrounding the +plugin are different package groups which are the different possible interface +points of the plugin. Note that not all library package lists are complete as +packages have been omitted for brevity. + +![Package architecture](./package-architecture.png) + + + +### Overview + +The arrows in the diagram above indicate a runtime dependency on the code of the +target package. This strict dependency graph only applies to runtime +`dependencies`, and there may be `devDependencies` that breaks the rules of this +table for the purpose of testing. While there are some arrows that show a +dependency on a collection of frontend, backend and isomorphic packages, those +still have abide by important compatibility rules shown in the bottom left. + +The `app` and `backend` packages are the entry points of a Backstage project. +The `app` package is the frontend application that brings together a collection +of frontend plugins and customizes them to fit an organization, while the +`backend` package is the backend service that powers the Backstage application. +Worth noting is that there can be more than one instance of each of these +packages within a project. Particularly the `backend` packages can benefit from +being split up into smaller deployment units that each serve their own purpose +with a smaller collection of plugins. + +### Plugin Packages + +A typical plugin consists of up to five packages, two frontend ones, two +backend, and one isomorphic packages. All packages within the plugin must share +a common prefix, typically of the form `@/plugin-`, but +alternatives like `backstage-plugin-` or +`@scope/backstage-plugin-` are also valid. Along with this prefix, +each of the packages have their own unique suffix that denotes their role. In +addition to these five plugin packages it's also possible for to a plugin to +have additional frontend and backend modules that can be installed to enable +optional features. For a full list of suffixes and their roles, see the +[Plugin Package Structure ADR](../architecture-decisions/adr011-plugin-package-structure.md). + +The `-react`, `-common`, and `-node` plugin packages together form the external +library of a plugin. The plugin library enables other plugins to build on top of +and extend a plugin, and likewise allows the plugin to depend on and extend +other plugins. Because of this, it is preferable that plugin library packages +allow duplicate installations of themselves, as you may end up with a mix of +versions being installed as dependencies of various plugins. It is also +forbidden for plugins to directly import non-library packages from other +plugins, all communication between plugins must be handled through libraries and +the application itself. + +### Frontend Packages + +The frontend packages are grouped into two main groups. The first one is +"Frontend App Core", which is the set of packages that are only used by the +`app` package itself. These packages help build up the core structure of the app +as well as provide a foundation for the plugin libraries to rely upon. + +The second group is the rest of the shared packages, further divided into +"Frontend Plugin Core" and "Frontend Libraries". The core packages that are +considered particularly stable and form the core of the frontend framework. +Their most important role is to form the boundary around each plugin and provide +a set of tools that helps you combine a collection of plugins into a running +application. The rest of the frontend packages are more traditional libraries +that serve as building blocks to create plugins. + +### Backend Packages + +The backend library packages do not currently share a similar plugin +architecture as the frontend packages. They are instead simply a collection of +building blocks and patterns that help you build backend services. This is +however likely to change in the future. + +### Common Packages + +The common packages are the packages are effectively depended on by all other +pages. This is a much smaller set of packages but they are also very pervasive. +Because the common packages are isomorphic and must execute both in the frontend +and backend, they are never allowed to depend on any of the frontend of backend +packages. + +The Backstage CLI is in a category of its own and is depended on by virtually +all other packages. It's not a library in itself though, and must always be a +development dependency only. + ## Databases As we have seen, both the `lighthouse-audit-service` and `catalog-backend` diff --git a/docs/overview/package-architecture.drawio b/docs/overview/package-architecture.drawio new file mode 100644 index 0000000000..c320c94c69 --- /dev/null +++ b/docs/overview/package-architecture.drawio @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/docs/overview/package-architecture.png b/docs/overview/package-architecture.png new file mode 100644 index 0000000000..dfa48fb13b Binary files /dev/null and b/docs/overview/package-architecture.png differ