From 8570593d5526812ee9adc95485a11f51d55575d6 Mon Sep 17 00:00:00 2001
From: KN4CK3R <admin@oldschoolhack.me>
Date: Mon, 13 Mar 2023 23:15:09 +0100
Subject: [PATCH] Add package registry architecture overview (#23445)

As announced in #22810 I added a readme file to help understanding how
the package registry archictecture works and how the go packages are
related.
---
 routers/api/packages/README.md | 50 ++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 routers/api/packages/README.md

diff --git a/routers/api/packages/README.md b/routers/api/packages/README.md
new file mode 100644
index 0000000000..533a0d32f0
--- /dev/null
+++ b/routers/api/packages/README.md
@@ -0,0 +1,50 @@
+# Gitea Package Registry
+
+This document gives a brief overview how the package registry is organized in code.
+
+## Structure
+
+The package registry code is divided into multiple modules to split the functionality and make code reuse possible.
+
+| Module | Description |
+| - | - |
+| `models/packages` | Common methods and models used by all registry types |
+| `models/packages/<type>` | Methods used by specific registry type. There should be no need to use type specific models. |
+| `modules/packages` | Common methods and types used by multiple registry types |
+| `modules/packages/<type>` | Registry type specific methods and types (e.g. metadata extraction of package files) |
+| `routers/api/packages` | Route definitions for all registry types |
+| `routers/api/packages/<type>` | Route implementation for a specific registry type |
+| `services/packages` | Helper methods used by registry types to handle common tasks like package creation and deletion in `routers` |
+| `services/packages/<type>` | Registry type specific methods used by `routers` and `services` |
+
+## Models
+
+Every package registry implementation uses the same underlaying models:
+
+| Model | Description |
+| - | - |
+| `Package` | The root of a package providing values fixed for every version (e.g. the package name) |
+| `PackageVersion` | A version of a package containing metadata (e.g. the package description) |
+| `PackageFile` | A file of a package describing its content (e.g. file name) |
+| `PackageBlob` | The content of a file (may be shared by multiple files) |
+| `PackageProperty` | Additional properties attached to `Package`, `PackageVersion` or `PackageFile` (e.g. used if metadata is needed for routing) |
+
+The following diagram shows the relationship between the models:
+```
+Package <1---*> PackageVersion <1---*> PackageFile <*---1> PackageBlob
+```
+
+## Adding a new package registry type
+
+Before adding a new package registry type have a look at the existing implementation to get an impression of how it could work.
+Most registry types offer endpoints to retrieve the metadata, upload and download package files.
+The upload endpoint is often the heavy part because it must validate the uploaded blob, extract metadata and create the models.
+The methods to validate and extract the metadata should be added in the `modules/packages/<type>` package.
+If the upload is valid the methods in `services/packages` allow to store the upload and create the corresponding models.
+It depends if the registry type allows multiple files per package version which method should be called:
+- `CreatePackageAndAddFile`: error if package version already exists
+- `CreatePackageOrAddFileToExisting`: error if file already exists
+- `AddFileToExistingPackage`: error if package version does not exist or file already exists
+
+`services/packages` also contains helper methods to download a file or to remove a package version.
+There are no helper methods for metadata endpoints because they are very type specific.