Skip to content

Library Registry

Target Architecture — Final-State Design

The LibraryRegistryService, LibraryVersionService, DependencyAnalyzerService, and ApiClientCatalogService described here are the planned ConnectSoft.Factory.Templates.* services governing the library catalog. The packages they catalog are real, implemented ConnectSoft.Extensions.* (and related) assets (see the Implemented callout below).

The Library Registry is the catalog of reusable building blocks — the NuGet packages that templates depend on and that generated services compose to gain persistence, messaging, observability, SaaS, AI, and integration capabilities. Where the Template Registry governs generators, the Library Registry governs the parts they assemble. It is the reuse backbone of the factory: agents and templates select libraries by capability, not by guessing package names, and every selection is checked for version compatibility.

Aggregate roots

erDiagram
    LibraryPackage ||--o{ LibraryVersion : "has versions"
    LibraryPackage ||--o{ LibraryCapability : "exposes"
    LibraryVersion ||--o{ DependencyGraph : "contributes to"
    LibraryPackage {
        string libraryId
        string packageName
        string area
        string status
    }
    LibraryVersion {
        string libraryVersionId
        string semanticVersion
        string targetFramework
        string feedRef
    }
    LibraryCapability {
        string capabilityId
        string name
        string contract
    }
Hold "Alt" / "Option" to enable pan & zoom

LibraryPackage

LibraryPackage is the version-independent identity of a reusable library — for example ConnectSoft.Extensions.PersistenceModel.PostgreSQL. It carries the canonical package name, an area (persistence, messaging, saas, observability, ai, integration, security, mapping, validation), an owner, lifecycle status, and discovery tags. It owns its LibraryVersion and LibraryCapability children. See Aggregate Roots.

LibraryVersion

LibraryVersion is an immutable semantically versioned release of a package. It records the semanticVersion, the target framework (e.g. net10.0), the Azure Artifacts feed reference (feedRef), the declared dependencies on other libraries (with version ranges), and the release notes. Published versions are immutable so dependency resolution is reproducible.

LibraryCapability

LibraryCapability describes what a package provides in machine-consumable terms — a named capability (e.g. RelationalPersistence, MessageBus, TenantResolution, MeteredBilling, StructuredLogging, McpToolHost) with the contract/abstraction it satisfies. Capabilities are indexed by the Knowledge Platform so agents can search "find a library that provides metered billing for multi-tenant" and resolve to ConnectSoft.Extensions.Saas.Metering.

Registration and versioning

Libraries are registered with LibraryRegistryService (POST /libraries), which enforces the ConnectSoft.{Area}.{Capability} naming convention and persists the LibraryPackage identity and declared capabilities. New releases are added by LibraryVersionService, which records the version, target framework, and declared dependencies, then triggers the DependencyScanWorker and LibraryIndexingWorker (see Workers) to scan the dependency graph and index the package for search.

sequenceDiagram
    participant Author as "Author / Agent"
    participant Reg as "LibraryRegistryService"
    participant Ver as "LibraryVersionService"
    participant Dep as "DependencyAnalyzerService"
    participant Pub as "PackagePublisherService"
    Author->>Reg: POST /libraries
    Reg-->>Author: libraryId (LibraryRegistered)
    Author->>Ver: register version + dependencies
    Ver->>Dep: scan dependency graph
    Dep-->>Ver: DependencyScanned
    Ver->>Pub: publish to Azure Artifacts
    Pub-->>Author: LibraryPublished
Hold "Alt" / "Option" to enable pan & zoom

Dependency intelligence

DependencyAnalyzerService builds and maintains the DependencyGraph aggregate (see Aggregate Roots): a directed graph of which library versions depend on which others, with the resolved version ranges. This graph is what powers:

  • Transitive resolution — given a set of requested libraries, compute the full transitive closure and detect version conflicts (the classic "diamond" problem) before generation.
  • Impact analysis — when a library version is deprecated or a CVE is reported, find every dependent package and every generated product affected.
  • Upgrade advice — PackageUpgradeAdvisorService walks the graph to compute safe upgrade plans.

The graph feeds the Compatibility Model, which combines library dependency data with template and runtime constraints into the CompatibilityMatrix.

API client catalog

ApiClientCatalogService is a specialized facet of the library registry for external integration clients — generated and hand-written API clients that wrap third-party services. It catalogs each client package, the upstream API it targets, the authentication mode, and the capability it exposes, so agents building an integration can discover an existing client instead of generating a new one.

Implemented

The following API client libraries exist in the codebase and are cataloged here: Deputy, Braze, and Bill clients, plus the SMS provider clients ConnectSoft.Sms.Providers.*. New clients are generated from ApiLibraryTemplate.

The real ConnectSoft.Extensions.* ecosystem

Implemented

The libraries below exist in the ConnectSoft codebase as NuGet packages published to Azure Artifacts, targeting .NET 10. The Library Registry is the final-state catalog that versions, indexes, and governs them. They are the building blocks every template composes.

Library Area Capability
ConnectSoft.Extensions.PersistenceModel.NHibernate persistence Relational persistence (primary ORM)
ConnectSoft.Extensions.PersistenceModel.EntityFramework persistence Relational persistence (EF Core)
ConnectSoft.Extensions.PersistenceModel.Dapper persistence Micro-ORM data access
ConnectSoft.Extensions.PersistenceModel.PostgreSQL persistence PostgreSQL provider integration
ConnectSoft.Extensions.PersistenceModel.MongoDb persistence Document persistence
ConnectSoft.Extensions.PersistenceModel.Redis persistence Cache / key-value persistence
ConnectSoft.Extensions.PersistenceModel.ElasticSearch persistence Search persistence
ConnectSoft.Extensions.MessagingModel.MassTransit messaging Message bus (primary)
ConnectSoft.Extensions.MessagingModel.NServiceBus messaging Message bus (alternative)
ConnectSoft.Extensions.Saas.Abstractions saas Multi-tenant abstractions
ConnectSoft.Extensions.Saas.AspNetCore saas Tenant resolution middleware
ConnectSoft.Extensions.Saas.Billing saas Billing primitives
ConnectSoft.Extensions.Saas.Metering saas Metered usage
ConnectSoft.Extensions.Saas.Options saas Per-tenant options
ConnectSoft.Extensions.Saas.Orleans saas Tenant-aware Orleans actors
ConnectSoft.Extensions.Saas.NHibernate saas Tenant-scoped persistence
ConnectSoft.Extensions.Observability observability OpenTelemetry observability
ConnectSoft.Extensions.Telemetry observability Telemetry primitives
ConnectSoft.Extensions.Logging.Serilog observability Structured logging
ConnectSoft.Extensions.DomainModel domain DDD building blocks
ConnectSoft.Extensions.Validation.FluentValidation validation Input validation
ConnectSoft.Extensions.ObjectMapping.* mapping Object-to-object mapping
ConnectSoft.Extensions.Http.OAuth2 security OAuth2 HTTP message handling
ConnectSoft.Extensions.WebSecurity security Web security hardening
ConnectSoft.Extensions.AI.* ai AI model + agent integration
ConnectSoft.Extensions.ModelContextProtocol ai MCP tool host/client
Deputy / Braze / Bill clients integration Third-party API clients
ConnectSoft.Sms.Providers.* integration SMS provider clients

See the implementation reference: Library Catalog.

How the registry serves the factory

  • Capability-based discovery — agents search by LibraryCapability, not package strings, making selection robust to renames.
  • Compatibility-safe composition — the dependency graph and compatibility matrix prevent conflicting version sets from reaching generation.
  • Reuse over regeneration — the API client catalog and capability index steer agents to existing assets first.
  • Provenance — LibraryRegistered, LibraryPublished, and DependencyScanned events flow through the event envelope, feeding artifact metadata and Knowledge indexing.