1 files changed, 90 insertions, 0 deletions
diff --git a/doc/development/fe_guide/registry_architecture.md b/doc/development/fe_guide/registry_architecture.md
new file mode 100644
index 00000000000..47a6dc40e19
--- /dev/null
+++ b/doc/development/fe_guide/registry_architecture.md
@@ -0,0 +1,90 @@
+---
+stage: Package
+group: unassigned
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Registry architecture
+
+GitLab has several registry applications. Given that they all leverage similar UI, UX, and business
+logic, they are all built with the same architecture. In addition, a set of shared components
+already exists to unify the user and developer experiences.
+
+Existing registries:
+
+- Package Registry
+- Container Registry
+- Infrastructure Registry
+- Dependency Proxy
+
+## Frontend architecture
+
+### Component classification
+
+All the registries follow an architecture pattern that includes four component types:
+
+- Pages: represent an entire app, or for the registries using [vue-router](https://v3.router.vuejs.org/) they represent one router
+  route.
+- Containers: represent a single piece of functionality. They contain complex logic and may
+  connect to the API.
+- Presentationals: represent a portion of the UI. They receive all their data with `props` or through
+  `inject`, and do not connect to the API.
+- Shared components: presentational components that accept a various array of configurations and are
+  shared across all of the registries.
+
+### Communicating with the API
+
+The complexity and communication with the API should be concentrated in the pages components, and
+in the container components when needed. This makes it easier to:
+
+- Handle concurrent requests, loading states, and user messages.
+- Maintain the code, especially to estimate work. If it touches a page or functional component,
+  expect it to be more complex.
+- Write fast and consistent unit tests.
+
+### Best practices
+
+- Use [`provide` or `inject`](https://v2.vuejs.org/v2/api/?redirect=true#provide-inject)
+  to pass static, non-reactive values coming from the app initialization.
+- When passing data, prefer `props` over nested queries or Vuex bindings. Only pages and
+  container components should be aware of the state and API communication.
+- Don't repeat yourself. If one registry receives functionality, the likelihood of the rest needing
+  it in the future is high. If something seems reusable and isn't bound to the state, create a
+  shared component.
+- Try to express functionality and logic with dedicated components. It's much easier to deal with
+  events and properties than callbacks and asynchronous code (see
+  [`delete_package.vue`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/packages_and_registries/package_registry/components/functional/delete_package.vue)).
+- Leverage [startup for GraphQL calls](graphql.md#making-initial-queries-early-with-graphql-startup-calls).
+
+## Shared compoenents library
+
+Inside `vue_shared/components/registry` and `packages_and_registries/shared`, there's a set of
+shared components that you can use to implement registry functionality. These components build the
+main pieces of the desired UI and UX of a registry page. The most important components are:
+
+- `code-instruction`: represents a copyable box containing code. Supports multiline and single line
+  code boxes. Snowplow tracks the code copy event.
+- `details-row`: represents a row of details. Used to add additional info in the details area of
+  the `list-item` component.
+- `history-item`: represents a history list item used to build a timeline.
+- `list-item`: represents a list element in the registry. It supports: left action, left primary and
+  secondary content, right primary and secondary content, right action, and details slots.
+- `metadata-item`: represents one piece of metadata, with an icon or a link. Used primarily in the
+  title area.
+- `persisted-dropdown-selection`: represents a dropdown menu that stores the user selection in the
+  `localStorage`.
+- `registry-search`: implements `gl-filtered-search` with a sorting section on the right.
+- `title-area`: implements the top title area of the registry. Includes: a main title, an avatar, a
+  subtitle, a metadata row, and a right actions slot.
+
+## Adding a new registry page
+
+When adding a new registry:
+
+- Leverage the shared components that already exist. It's good to look at how the components are
+  structured and used in the more mature registries (for example, the Package Registry).
+- If it's in line with the backend requirements, we suggest using GraphQL for the API. This helps in
+  dealing with the innate performance issue of registries.
+- If possible, we recommend using [Vue Router](https://v3.router.vuejs.org/)
+  and frontend routing. Coupled with Apollo, the caching layer helps with the perceived page
+  performance.