# linus-berg/nugget architecture

> Architecture diagram of the GitHub repository linus-berg/nugget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/linus-berg/nugget
- Repository: https://github.com/linus-berg/nugget

## Overview

Nugget is an S3-backed offline NuGet V3 server. Clients restore/search through protocol endpoints; uploaders publish packages through the authenticated write API. The graph also preserves advisory serving and cross-instance catalog synchronization. Endpoint-to-service relationships are supported by the SOURCE INDEX; unsampled endpoint internals are not inferred beyond those references.

Main entry points: [`Nugget.Api/Catalog/PackageCatalog.cs`](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/PackageCatalog.cs) (Package Catalog), [`Nugget.Api/Vulnerabilities/VulnerabilityStore.cs`](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Vulnerabilities/VulnerabilityStore.cs) (Vulnerability Store), [`Nugget.Api/Catalog/CatalogSynchronizer.cs`](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/CatalogSynchronizer.cs) (Catalog Synchronizer), [`Nugget.Api/Packages/PackageRepository.cs`](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Packages/PackageRepository.cs) (Metadata Repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["NuGet API"]
  node_flat["Flat Container"]
  node_registration["Registrations"]
  node_search["Search API<br/>[SearchEndpoints.cs]"]
  node_service_index["Service Index"]
  node_publish_api["Publish API"]
  node_vulnerability_api["Vulnerability API"]
  node_http_helpers["HTTP Helpers<br/>[HttpHelpers.cs]"]
end

subgraph group_packages["Package Lifecycle"]
  node_package_inspector["Package Inspector"]
  node_publisher["Package Publisher"]
  node_records["Package Records<br/>[PackageRecord.cs]"]
  node_repository["Metadata Repository"]
end

subgraph group_catalog["Catalog and Search"]
  node_catalog["Package Catalog<br/>[PackageCatalog.cs]"]
  node_summaries["Package Summaries<br/>[PackageSummary.cs]"]
  node_sync["Catalog Synchronizer"]
  node_sync_service["Sync Service"]
  node_change_feed["Change Feed<br/>[ChangeFeed.cs]"]
  node_downloads["Download Statistics"]
  node_search_query["Search Query<br/>[SearchQuery.cs]"]
end

subgraph group_storage["S3 Persistence"]
  node_object_store["Object Store Interface<br/>[IObjectStore.cs]"]
  node_s3[("S3 Store<br/>[S3ObjectStore.cs]")]
  node_storage_keys["Storage Keys<br/>[StorageKeys.cs]"]
  node_json["JSON Serialization<br/>[NuggetJson.cs]"]
end

subgraph group_security["Advisories"]
  node_vulnerability_store["Vulnerability Store"]
end

node_nuget_clients(("NuGet Clients"))
node_uploaders(("Package Uploaders"))
node_nuget_org(("NuGet Advisory Source"))

node_nuget_clients -->|"requests resources"| node_service_index
node_nuget_clients -->|"restores packages"| node_flat
node_nuget_clients -->|"requests metadata"| node_registration
node_nuget_clients -->|"searches packages"| node_search
node_uploaders -->|"uploads packages"| node_publish_api
node_publish_api -->|"inspects upload"| node_package_inspector
node_publish_api -->|"publishes versions"| node_publisher
node_publish_api -->|"records changes"| node_change_feed
node_publish_api -->|"updates catalog"| node_catalog
node_publisher -->|"updates metadata"| node_repository
node_publisher -->|"writes package"| node_object_store
node_publisher -->|"appends changes"| node_change_feed
node_repository -->|"reads and writes"| node_object_store
node_repository -->|"loads records"| node_records
node_repository -->|"keys metadata"| node_storage_keys
node_flat -->|"reads package records"| node_repository
node_flat -->|"reads package data"| node_catalog
node_flat -->|"counts downloads"| node_downloads
node_registration -->|"reads package data"| node_catalog
node_registration -->|"reads records"| node_repository
node_registration -->|"adds advisories"| node_vulnerability_store
node_search -->|"searches catalog"| node_catalog
node_search -->|"uses download counts"| node_downloads
node_search -->|"adds advisories"| node_vulnerability_store
node_service_index -->|"advertises advisories"| node_vulnerability_store
node_service_index -->|"reports package state"| node_catalog
node_vulnerability_api -.->|"serves advisory data"| node_vulnerability_store
node_sync_service -->|"runs synchronization"| node_sync
node_sync -->|"loads snapshots"| node_object_store
node_sync -->|"rebuilds from metadata"| node_repository
node_sync -->|"applies changes"| node_catalog
node_sync -->|"publishes counts"| node_downloads
node_sync -->|"loads advisories"| node_vulnerability_store
node_sync -->|"consumes changes"| node_change_feed
node_catalog -->|"indexes records"| node_summaries
node_catalog -->|"parses search terms"| node_search_query
node_change_feed -->|"stores change entries"| node_object_store
node_vulnerability_store -->|"stores advisories"| node_object_store
node_vulnerability_store -->|"keys advisory files"| node_storage_keys
node_nuget_org -.->|"supplies mirrored data"| node_vulnerability_store
node_object_store -->|"implemented by"| node_s3
node_http_helpers -->|"serializes responses"| node_json

click node_flat "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/FlatContainerEndpoints.cs"
click node_registration "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/RegistrationEndpoints.cs"
click node_search "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/SearchEndpoints.cs"
click node_service_index "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/ServiceIndexEndpoints.cs"
click node_publish_api "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/PublishEndpoints.cs"
click node_vulnerability_api "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/VulnerabilityEndpoints.cs"
click node_http_helpers "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/HttpHelpers.cs"
click node_package_inspector "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Packages/PackageInspector.cs"
click node_publisher "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Packages/PackagePublisher.cs"
click node_records "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Packages/PackageRecord.cs"
click node_repository "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Packages/PackageRepository.cs"
click node_catalog "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/PackageCatalog.cs"
click node_summaries "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/PackageSummary.cs"
click node_sync "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/CatalogSynchronizer.cs"
click node_sync_service "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/CatalogSyncService.cs"
click node_change_feed "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/ChangeFeed.cs"
click node_downloads "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/DownloadStatistics.cs"
click node_search_query "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/SearchQuery.cs"
click node_vulnerability_store "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Vulnerabilities/VulnerabilityStore.cs"
click node_object_store "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Storage/IObjectStore.cs"
click node_s3 "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Storage/S3ObjectStore.cs"
click node_storage_keys "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Storage/StorageKeys.cs"
click node_json "https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Json/NuggetJson.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flat,node_registration,node_search,node_service_index,node_publish_api,node_vulnerability_api,node_http_helpers,node_nuget_clients toneBlue
class node_package_inspector,node_publisher,node_records,node_repository toneAmber
class node_catalog,node_summaries,node_sync,node_sync_service,node_change_feed,node_downloads,node_search_query toneMint
class node_object_store,node_s3,node_storage_keys,node_json toneRose
class node_vulnerability_store,node_uploaders,node_nuget_org toneIndigo
```

## Components

### NuGet API

- [Flat Container](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/FlatContainerEndpoints.cs): `Nugget.Api/Endpoints/FlatContainerEndpoints.cs`
- [Registrations](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/RegistrationEndpoints.cs): `Nugget.Api/Endpoints/RegistrationEndpoints.cs`
- [Search API](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/SearchEndpoints.cs): `Nugget.Api/Endpoints/SearchEndpoints.cs`
- [Service Index](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/ServiceIndexEndpoints.cs): `Nugget.Api/Endpoints/ServiceIndexEndpoints.cs`
- [Publish API](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/PublishEndpoints.cs): `Nugget.Api/Endpoints/PublishEndpoints.cs`
- [Vulnerability API](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/VulnerabilityEndpoints.cs): `Nugget.Api/Endpoints/VulnerabilityEndpoints.cs`
- [HTTP Helpers](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Endpoints/HttpHelpers.cs): `Nugget.Api/Endpoints/HttpHelpers.cs`

### Package Lifecycle

- [Package Inspector](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Packages/PackageInspector.cs): `Nugget.Api/Packages/PackageInspector.cs`
- [Package Publisher](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Packages/PackagePublisher.cs): `Nugget.Api/Packages/PackagePublisher.cs`
- [Package Records](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Packages/PackageRecord.cs): `Nugget.Api/Packages/PackageRecord.cs`
- [Metadata Repository](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Packages/PackageRepository.cs): `Nugget.Api/Packages/PackageRepository.cs`

### Catalog and Search

- [Package Catalog](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/PackageCatalog.cs): `Nugget.Api/Catalog/PackageCatalog.cs`
- [Package Summaries](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/PackageSummary.cs): `Nugget.Api/Catalog/PackageSummary.cs`
- [Catalog Synchronizer](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/CatalogSynchronizer.cs): `Nugget.Api/Catalog/CatalogSynchronizer.cs`
- [Sync Service](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/CatalogSyncService.cs): `Nugget.Api/Catalog/CatalogSyncService.cs`
- [Change Feed](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/ChangeFeed.cs): `Nugget.Api/Catalog/ChangeFeed.cs`
- [Download Statistics](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/DownloadStatistics.cs): `Nugget.Api/Catalog/DownloadStatistics.cs`
- [Search Query](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Catalog/SearchQuery.cs): `Nugget.Api/Catalog/SearchQuery.cs`

### S3 Persistence

- [Object Store Interface](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Storage/IObjectStore.cs): `Nugget.Api/Storage/IObjectStore.cs`
- [S3 Store](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Storage/S3ObjectStore.cs): `Nugget.Api/Storage/S3ObjectStore.cs`
- [Storage Keys](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Storage/StorageKeys.cs): `Nugget.Api/Storage/StorageKeys.cs`
- [JSON Serialization](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Json/NuggetJson.cs): `Nugget.Api/Json/NuggetJson.cs`

### Advisories

- [Vulnerability Store](https://github.com/linus-berg/nugget/blob/main/Nugget.Api/Vulnerabilities/VulnerabilityStore.cs): `Nugget.Api/Vulnerabilities/VulnerabilityStore.cs`

### Other components

- **NuGet Clients**
- **Package Uploaders**
- **NuGet Advisory Source**

## Connections

- NuGet Clients → Service Index: requests resources
- NuGet Clients → Flat Container: restores packages
- NuGet Clients → Registrations: requests metadata
- NuGet Clients → Search API: searches packages
- Package Uploaders → Publish API: uploads packages
- Publish API → Package Inspector: inspects upload (evidence: `Nugget.Api/Endpoints/PublishEndpoints.cs`)
- Publish API → Package Publisher: publishes versions (evidence: `Nugget.Api/Endpoints/PublishEndpoints.cs`)
- Publish API → Change Feed: records changes (evidence: `Nugget.Api/Endpoints/PublishEndpoints.cs`)
- Publish API → Package Catalog: updates catalog (evidence: `Nugget.Api/Endpoints/PublishEndpoints.cs`)
- Package Publisher → Metadata Repository: updates metadata (evidence: `Nugget.Api/Packages/PackagePublisher.cs`)
- Package Publisher → Object Store Interface: writes package (evidence: `Nugget.Api/Packages/PackagePublisher.cs`)
- Package Publisher → Change Feed: appends changes (evidence: `Nugget.Api/Packages/PackagePublisher.cs`)
- Metadata Repository → Object Store Interface: reads and writes (evidence: `Nugget.Api/Packages/PackageRepository.cs`)
- Metadata Repository → Package Records: loads records (evidence: `Nugget.Api/Packages/PackageRepository.cs`)
- Metadata Repository → Storage Keys: keys metadata (evidence: `Nugget.Api/Packages/PackageRepository.cs`)
- Flat Container → Metadata Repository: reads package records (evidence: `Nugget.Api/Endpoints/FlatContainerEndpoints.cs`)
- Flat Container → Package Catalog: reads package data (evidence: `Nugget.Api/Endpoints/FlatContainerEndpoints.cs`)
- Flat Container → Download Statistics: counts downloads (evidence: `Nugget.Api/Endpoints/FlatContainerEndpoints.cs`)
- Registrations → Package Catalog: reads package data (evidence: `Nugget.Api/Endpoints/RegistrationEndpoints.cs`)
- Registrations → Metadata Repository: reads records (evidence: `Nugget.Api/Endpoints/RegistrationEndpoints.cs`)
- Registrations → Vulnerability Store: adds advisories (evidence: `Nugget.Api/Endpoints/RegistrationEndpoints.cs`)
- Search API → Package Catalog: searches catalog (evidence: `Nugget.Api/Endpoints/SearchEndpoints.cs`)
- Search API → Download Statistics: uses download counts (evidence: `Nugget.Api/Endpoints/SearchEndpoints.cs`)
- Search API → Vulnerability Store: adds advisories (evidence: `Nugget.Api/Endpoints/SearchEndpoints.cs`)
- Service Index → Vulnerability Store: advertises advisories (evidence: `Nugget.Api/Endpoints/ServiceIndexEndpoints.cs`)
- Service Index → Package Catalog: reports package state (evidence: `Nugget.Api/Endpoints/ServiceIndexEndpoints.cs`)
- Vulnerability API → Vulnerability Store: serves advisory data
- Sync Service → Catalog Synchronizer: runs synchronization (evidence: `Nugget.Api/Catalog/CatalogSyncService.cs`)
- Catalog Synchronizer → Object Store Interface: loads snapshots (evidence: `Nugget.Api/Catalog/CatalogSynchronizer.cs`)
- Catalog Synchronizer → Metadata Repository: rebuilds from metadata (evidence: `Nugget.Api/Catalog/CatalogSynchronizer.cs`)
- Catalog Synchronizer → Package Catalog: applies changes (evidence: `Nugget.Api/Catalog/CatalogSynchronizer.cs`)
- Catalog Synchronizer → Download Statistics: publishes counts (evidence: `Nugget.Api/Catalog/CatalogSynchronizer.cs`)
- Catalog Synchronizer → Vulnerability Store: loads advisories (evidence: `Nugget.Api/Catalog/CatalogSynchronizer.cs`)
- Catalog Synchronizer → Change Feed: consumes changes (evidence: `Nugget.Api/Catalog/CatalogSynchronizer.cs`)
- Package Catalog → Package Summaries: indexes records (evidence: `Nugget.Api/Catalog/PackageCatalog.cs`)
- Package Catalog → Search Query: parses search terms (evidence: `Nugget.Api/Catalog/PackageCatalog.cs`)
- Change Feed → Object Store Interface: stores change entries (evidence: `Nugget.Api/Catalog/ChangeFeed.cs`)
- Vulnerability Store → Object Store Interface: stores advisories (evidence: `Nugget.Api/Vulnerabilities/VulnerabilityStore.cs`)
- Vulnerability Store → Storage Keys: keys advisory files (evidence: `Nugget.Api/Vulnerabilities/VulnerabilityStore.cs`)
- NuGet Advisory Source → Vulnerability Store: supplies mirrored data
- Object Store Interface → S3 Store: implemented by (evidence: `Nugget.Api/Storage/S3ObjectStore.cs`)
- HTTP Helpers → JSON Serialization: serializes responses (evidence: `Nugget.Api/Endpoints/HttpHelpers.cs`)