Aggregate Roots¶
Target Architecture — Final-State Design
The 15 aggregate roots below are the planned domain model of the ConnectSoft.Factory.Templates.* services, built on ConnectSoft.Extensions.DomainModel DDD building blocks and persisted with ConnectSoft.Extensions.PersistenceModel.NHibernate over Azure SQL / PostgreSQL (with Azure Blob, Azure Artifacts, and Git for payloads). Naming follows Naming Conventions. Domain events use the canonical event envelope.
The platform's domain splits into the Template context (generators, versions, parameters, executions, validation, publication, upgrade) and the Library context (packages, versions, capabilities, dependencies, compatibility, publication). Each aggregate root is the consistency boundary for its own data and the sole emitter of its domain events.
erDiagram
Template ||--o{ TemplateVersion : owns
TemplateVersion ||--|| TemplateParameterSchema : defines
TemplateVersion ||--o{ TemplateCompatibilityRule : declares
TemplateVersion ||--o{ TemplateValidationResult : validated-by
Template ||--o{ TemplatePublication : published-via
Template ||--o{ TemplateExecution : executed-as
TemplateExecution ||--|| ScaffoldOutput : produces
Template ||--o{ TemplateUpgradePlan : upgraded-via
LibraryPackage ||--o{ LibraryVersion : owns
LibraryPackage ||--o{ LibraryCapability : exposes
LibraryVersion ||--o{ DependencyGraph : contributes
LibraryVersion ||--o{ PackagePublication : published-via
CompatibilityMatrix }o--o{ TemplateCompatibilityRule : rolls-upTemplate¶
Purpose — The stable, version-independent identity of a code generator (e.g. ConnectSoft.Template.Microservice). The root of the template aggregate and owner of its versions.
Fields — templateId, name, title, category, owner, status (Draft/Active/Deprecated/Retired), tags, createdAt, updatedAt, tenantId.
Entities — TemplateVersion (owned collection; the version history).
Value objects — TemplateName (enforces ConnectSoft.Template.* convention), TemplateCategory, OwnerRef, Tag.
Invariants — name is unique per tenant; category is immutable after creation; a Template cannot be Retired while it has Published versions still referenced by active products; status transitions are monotonic (Active → Deprecated → Retired).
Domain events — TemplateRegistered, TemplateDeprecated, TemplateRetired.
Repository — TemplateRepository.
Persistence — NHibernate over Azure SQL / PostgreSQL; hot catalog entries cached in Redis.
TemplateVersion¶
Purpose — An immutable, semantically versioned snapshot of a template's generator content. The reproducibility anchor for generation.
Fields — templateVersionId, templateId, semanticVersion, engineKind (DotnetNewTemplatePack/BaseTemplateFolder), sourceRef (Git), payloadBlobRef (Azure Blob), targetFramework, changelog, status (Draft/Validated/Published/Deprecated), createdAt.
Entities — TemplateParameterSchema (1:1 owned), TemplateCompatibilityRule (owned collection).
Value objects — SemanticVersion, SourceRef, BlobRef, TargetFramework.
Invariants — semanticVersion is unique within the template; once Published the version is immutable (no payload/schema mutation); a version cannot be Published without a passed TemplateValidationResult; targetFramework must satisfy declared RuntimeRequires rules.
Domain events — TemplateVersionCreated, TemplateVersionDeprecated.
Repository — TemplateVersionRepository.
Persistence — NHibernate (metadata) over Azure SQL; payload in Azure Blob; source in Git.
TemplateParameterSchema¶
Purpose — The typed input contract for a TemplateVersion, expressed as JSON Schema, used to validate parameter values before execution.
Fields — schemaId, templateVersionId, jsonSchemaRef, parameterCount, definedAt.
Entities — ParameterDefinition (owned; one per parameter: name, type, required, default, constraints).
Value objects — JsonSchemaDocument, ParameterConstraint, ConditionalRule (e.g. "includeAuthorization requires authority").
Invariants — schema is valid JSON Schema; every required parameter has a definition; conditional rules reference only declared parameters; schema is immutable once its TemplateVersion is Published.
Domain events — TemplateParameterSchemaDefined.
Repository — TemplateParameterSchemaRepository.
Persistence — NHibernate over Azure SQL (schema document stored as JSON column).
TemplateCompatibilityRule¶
Purpose — A single declarative compatibility constraint owned by a template (or library) version — runtime floors, required capabilities, and banned combinations.
Fields — ruleId, subjectRef (the version it constrains), constraintKind (RuntimeRequires/LibraryRequires/LibraryConflictsWith/TemplateConflictsWith/ParameterConstraint), expression, severity (Error/Warning), createdAt.
Entities — none (leaf within its subject version).
Value objects — ConstraintExpression, VersionRange, CapabilityRef.
Invariants — expression parses for its constraintKind; rules are versioned with their subject and immutable once the subject is Published; Error-severity rules block generation, Warning rules surface but do not block.
Domain events — CompatibilityRuleDeclared (recorded with version creation).
Repository — TemplateCompatibilityRuleRepository.
Persistence — NHibernate over Azure SQL.
TemplateExecution¶
Purpose — Tracks a single run of the Scaffold Engine from request to committed output. The unit of generation traceability.
Fields — executionId, templateId, templateVersionId, parameters, resolvedLibraries, target (repository/branch), agentTaskId, status (Requested/Validating/Rejected/Generating/Generated/Failed/Committed), scaffoldOutputId, requestedAt, completedAt, tenantId.
Entities — none owned directly; references ScaffoldOutput (separate aggregate produced by the execution).
Value objects — ParameterValues, LibrarySelection, TargetCoordinates, CorrelationRef (agent task- id).
Invariants — parameters must validate against the version's TemplateParameterSchema before leaving Validating; compatibility must pass before Generating; an execution produces at most one ScaffoldOutput; state transitions follow the lifecycle (no Generated without prior Generating); idempotency key prevents duplicate execution.
Domain events — TemplateExecutionRequested, TemplateExecutionRejected, TemplateExecutionFailed, TemplateExecuted.
Repository — TemplateExecutionRepository.
Persistence — NHibernate over Azure SQL (execution metadata); links to Blob/Git for output.
ScaffoldOutput¶
Purpose — The immutable result of a TemplateExecution — a complete, buildable solution artifact with full provenance.
Fields — scaffoldOutputId, executionId, templateVersionId, payloadBlobRef, gitCommitRef, provenanceManifest, contentHash, compositionManifestRef (for multi-template solutions), producedAt, tenantId.
Entities — GeneratedFileEntry (owned manifest entries describing the generated tree).
Value objects — ProvenanceManifest (template/library versions, parameters, engine), ContentHash, CommitRef, BlobRef.
Invariants — immutable once produced; contentHash matches the stored payload; provenanceManifest references only Published template and library versions; conforms to the artifact metadata model.
Domain events — ScaffoldGenerated.
Repository — ScaffoldOutputRepository.
Persistence — metadata in Azure SQL via NHibernate; payload in Azure Blob; committed to Git.
TemplateValidationResult¶
Purpose — The outcome of running validation checks against a TemplateVersion.
Fields — validationResultId, templateVersionId, checkSet, outcome (Passed/Failed), findings, validatedAt.
Entities — ValidationFinding (owned; per-check result: severity, message, location).
Value objects — CheckSet (StructuralLint/ParameterSchema/SampleGeneration), Outcome, Severity.
Invariants — outcome is Passed only when no Error-severity findings exist; result is tied to one templateVersionId; a Failed result blocks publishing.
Domain events — TemplateValidated.
Repository — TemplateValidationResultRepository.
Persistence — NHibernate over Azure SQL.
TemplatePublication¶
Purpose — Records the promotion of a validated TemplateVersion to Published, including any governance approval.
Fields — publicationId, templateId, templateVersionId, publishedBy, approvalRef, gitTagRef, publishedAt, status (Pending/Approved/Published/Rejected).
Entities — ApprovalStep (owned; governance approval chain when required).
Value objects — ApprovalRef, GitTagRef, Publisher.
Invariants — publication requires a Passed TemplateValidationResult; cannot move to Published without required approvals; publishing a version transitions the TemplateVersion to Published and is irreversible (a withdrawn version is Deprecated, not deleted).
Domain events — TemplatePublished.
Repository — TemplatePublicationRepository.
Persistence — NHibernate over Azure SQL; Git tag for the published source.
TemplateUpgradePlan¶
Purpose — A computed migration plan for moving dependent products from one template version to a newer one.
Fields — upgradePlanId, templateId, fromVersion, toVersion, impactedProducts, steps, riskLevel (Low/Medium/High), createdAt, status (Draft/Proposed/Accepted/Applied).
Entities — UpgradeStep (owned; ordered migration actions), ImpactedProductRef (owned).
Value objects — VersionDelta, RiskLevel, BreakingChange.
Invariants — fromVersion < toVersion; riskLevel is High when the delta crosses a major version with breaking parameter-schema changes; the plan references only Published versions.
Domain events — TemplateUpgradePlanCreated, TemplateUpgradePlanApplied.
Repository — TemplateUpgradePlanRepository.
Persistence — NHibernate over Azure SQL.
LibraryPackage¶
Purpose — The version-independent identity of a reusable library (e.g. ConnectSoft.Extensions.PersistenceModel.PostgreSQL). Root of the library aggregate; also the carrier of the API-client facet.
Fields — libraryId, packageName, area, owner, status (Active/Deprecated/Retired), isApiClient, upstreamApi (when client), tags, tenantId, createdAt.
Entities — LibraryVersion (owned collection), LibraryCapability (owned collection).
Value objects — PackageName (enforces ConnectSoft.{Area}.{Capability}), LibraryArea, UpstreamApiRef.
Invariants — packageName unique per tenant; area immutable; a package marked isApiClient must declare an upstreamApi; cannot be Retired while Published versions are referenced by active products.
Domain events — LibraryRegistered, ApiClientCataloged, LibraryDeprecated.
Repository — LibraryPackageRepository.
Persistence — NHibernate over Azure SQL / PostgreSQL; cached in Redis; capabilities indexed for search.
LibraryVersion¶
Purpose — An immutable semantically versioned release of a LibraryPackage, with its declared dependencies.
Fields — libraryVersionId, libraryId, semanticVersion, targetFramework, feedRef (Azure Artifacts), declaredDependencies, releaseNotes, status (Draft/Scanned/Published/Deprecated), createdAt.
Entities — DeclaredDependency (owned; package + version range).
Value objects — SemanticVersion, TargetFramework, VersionRange, FeedRef.
Invariants — semanticVersion unique within the package; immutable once Published; cannot publish without a completed DependencyScanned; declared dependency ranges must resolve in the DependencyGraph.
Domain events — LibraryVersionCreated, LibraryVersionDeprecated.
Repository — LibraryVersionRepository.
Persistence — NHibernate over Azure SQL (metadata); package binary in Azure Artifacts.
LibraryCapability¶
Purpose — A machine-consumable description of what a package provides (e.g. RelationalPersistence, MeteredBilling, McpToolHost), enabling capability-based discovery.
Fields — capabilityId, libraryId, name, contract (the abstraction/interface satisfied), description, declaredAt.
Entities — none (leaf within LibraryPackage).
Value objects — CapabilityName, ContractRef.
Invariants — name unique within the package; contract references a known abstraction; capabilities are indexed by the Knowledge Platform for search.
Domain events — LibraryCapabilityDeclared (recorded with registration).
Repository — LibraryCapabilityRepository.
Persistence — NHibernate over Azure SQL; replicated into the search index.
DependencyGraph¶
Purpose — The directed graph of library-to-library dependencies with resolved version ranges, powering transitive resolution, conflict detection, and impact analysis.
Fields — graphId, scope (global or composition), nodeCount, edgeCount, conflictCount, computedAt.
Entities — DependencyNode (owned; a library version), DependencyEdge (owned; node→node with version range).
Value objects — NodeRef, VersionRange, ConflictDescriptor.
Invariants — the graph is acyclic for resolvable compositions (cycles flagged as conflicts); each node references a known LibraryVersion; conflictCount reflects detected diamond/banned conflicts; recomputation is deterministic from current versions.
Domain events — DependencyScanned.
Repository — DependencyGraphRepository.
Persistence — NHibernate over Azure SQL (nodes/edges); resolved closures cached in Redis.
CompatibilityMatrix¶
Purpose — The rolled-up, queryable compatibility answer for a scope (template version, library version, or candidate composition), computed from rules and the dependency graph.
Fields — matrixId, scope, subjects (versions evaluated), compatible, violations, computedAt, cacheTtl.
Entities — ViolationEntry (owned; broken rule, offending versions, suggested resolution).
Value objects — Scope, Verdict, SuggestedResolution.
Invariants — compatible is true only when no Error-severity rule is violated; the matrix references the exact subject versions evaluated; a recompute supersedes the prior matrix for the same scope; cached copies expire per cacheTtl.
Domain events — CompatibilityEvaluated.
Repository — CompatibilityMatrixRepository.
Persistence — authoritative copy in Azure SQL via NHibernate; computed result cached in Redis.
PackagePublication¶
Purpose — Records the publication of a LibraryVersion to Azure Artifacts (NuGet), including approval.
Fields — packagePublicationId, libraryId, libraryVersionId, feedRef, publishedBy, approvalRef, publishedAt, status (Pending/Approved/Published/Rejected).
Entities — ApprovalStep (owned; governance chain when required).
Value objects — FeedRef, ApprovalRef, Publisher.
Invariants — publication requires a completed DependencyScanned; cannot move to Published without required approvals; a published version's feed entry is immutable (NuGet semantics); withdrawal deprecates rather than deletes.
Domain events — LibraryPublished.
Repository — PackagePublicationRepository.
Persistence — NHibernate over Azure SQL (publication record); binary in Azure Artifacts.