Skip to content

Aggregate Roots

Target Architecture — Final-State Design

This page is the final-state domain model of the Knowledge Platform. It defines 32 aggregate roots grouped by their owning bounded context. Every aggregate carries the cross-cutting metadata fields (tenantId, projectId, moduleId, traceId, correlationId, agentId, skillId, artifactId, environment, version, createdAt, updatedAt, status) in addition to the fields listed below.

Aggregates follow the naming conventions: singular PascalCase roots, {Root}Repository repositories, persisted via ConnectSoft.Extensions.PersistenceModel.NHibernate for relational stores and dedicated adapters for vector/blob/git stores.

Knowledge Graph

KnowledgeNode

  • Purpose — a typed vertex in the knowledge graph representing any factory entity (tenant, project, blueprint, module, artifact, contract, event, agent, skill, commit, deployment, runtime signal, etc.).
  • Key fields — nodeId, nodeType, ref (external id), title, properties, tenantId.
  • Entities — NodeProperty (typed key/value).
  • Value objects — NodeType, NodeRef, GraphScope.
  • Invariants — (tenantId, nodeType, ref) is unique; nodeType is from the closed ontology; nodes are never cross-tenant.
  • Domain events — KnowledgeNodeUpserted.
  • Repository — KnowledgeNodeRepository.
  • Store — PostgreSQL / Azure SQL.

KnowledgeEdge

  • Purpose — a typed, directed relationship between two KnowledgeNodes (e.g. DERIVED_FROM, DEPENDS_ON, EMITS, PRODUCED_BY).
  • Key fields — edgeId, from, to, edgeType, weight, properties.
  • Entities — none (edge is atomic).
  • Value objects — EdgeType, EdgeDirection.
  • Invariants — both endpoints exist and share tenantId; (from, to, edgeType) unique; no dangling edges.
  • Domain events — KnowledgeEdgeUpserted.
  • Repository — KnowledgeEdgeRepository.
  • Store — PostgreSQL / Azure SQL.

GraphProjection

  • Purpose — a materialised neighbourhood/subgraph computed for a query or context build, cached for reuse.
  • Key fields — graphProjectionId, scope, rootRef, nodeIds, edgeIds, computedAt, ttlSeconds.
  • Entities — ProjectionNodeRef, ProjectionEdgeRef.
  • Value objects — TraversalSpec (edge types, direction, depth).
  • Invariants — references only existing nodes/edges; expires after ttlSeconds.
  • Domain events — GraphProjectionUpdated.
  • Repository — GraphProjectionRepository.
  • Store — PostgreSQL / Azure SQL (+ Redis cache).

Vector & Semantic Memory

VectorDocument

  • Purpose — the indexed embedding representation of a memory record (artifact, doc, code symbol) in a Qdrant collection.
  • Key fields — vectorDocumentId, memoryRecordId, collection, kind, modelVersion, chunkCount, contentHash.
  • Entities — VectorChunk (see below).
  • Value objects — CollectionName, EmbeddingModelVersion, DistanceMetric.
  • Invariants — one live document per (memoryRecordId, modelVersion); contentHash ties vectors to source content.
  • Domain events — VectorDocumentUpserted, VectorDocumentDeleted.
  • Repository — VectorDocumentRepository (Qdrant adapter).
  • Store — Qdrant (Azure AI Search alternative).

VectorChunk

  • Purpose — a single embedded chunk of content with its vector and positional metadata.
  • Key fields — vectorChunkId, vectorDocumentId, ordinal, text, vector, tokenCount, span.
  • Entities — none.
  • Value objects — ChunkSpan (start/end), Embedding (float[]).
  • Invariants — ordinal unique within document; vector dimensionality matches collection.
  • Domain events — covered by VectorDocumentUpserted.
  • Repository — VectorChunkRepository (Qdrant adapter).
  • Store — Qdrant.

EmbeddingJob

  • Purpose — the unit of work that embeds chunks and tracks lifecycle/retry.
  • Key fields — embeddingJobId, memoryRecordId, chunkRefs, modelVersion, attempt, status.
  • Entities — ChunkEmbeddingResult.
  • Value objects — RetryPolicy, JobStatus.
  • Invariants — terminal once Completed/Failed; attempts bounded by RetryPolicy.
  • Domain events — EmbeddingCompleted, EmbeddingFailed, EmbeddingRefreshed.
  • Repository — EmbeddingJobRepository.
  • Store — PostgreSQL / Azure SQL (+ Qdrant for output).

Artifact Memory

ArtifactMemory

  • Purpose — the durable memory of a factory artifact, linking metadata to its stored body and versions.
  • Key fields — artifactMemoryId, artifactId, artifactType, currentVersion, classification, storageRef.
  • Entities — ArtifactVersion, ArtifactSnapshot.
  • Value objects — ArtifactReference, ContentHash, Classification.
  • Invariants — currentVersion points to an existing ArtifactVersion; classification set before serving.
  • Domain events — ArtifactIngested.
  • Repository — ArtifactMemoryRepository.
  • Store — Azure Blob (body) + PostgreSQL / Azure SQL (metadata).

ArtifactVersion

  • Purpose — an immutable version of an artifact body.
  • Key fields — artifactVersionId, artifactId, version (semver), contentHash, storageRef, supersedes.
  • Entities — none.
  • Value objects — SemVer, ContentHash.
  • Invariants — immutable once published; version unique per artifact; supersedes chains to prior.
  • Domain events — ArtifactVersionCreated.
  • Repository — ArtifactVersionRepository.
  • Store — Azure Blob + SQL.

ArtifactSnapshot

  • Purpose — a point-in-time capture of an artifact's state tied to a trace (for replay/diff).
  • Key fields — artifactSnapshotId, artifactId, version, atTraceId, capturedAt.
  • Entities — none.
  • Value objects — SnapshotReason.
  • Invariants — references an existing ArtifactVersion; immutable.
  • Domain events — ArtifactSnapshotCaptured.
  • Repository — ArtifactSnapshotRepository.
  • Store — Azure Blob + SQL.

Code Knowledge

CodeRepository

  • Purpose — a registered source repository indexed for code knowledge.
  • Key fields — codeRepositoryId, ref (Azure DevOps Git url), branch, lastIndexedCommit, language.
  • Entities — IndexedFile.
  • Value objects — GitRef, CommitSha.
  • Invariants — unique per (tenantId, ref, branch); index advances monotonically by commit.
  • Domain events — RepositoryIndexed.
  • Repository — CodeRepositoryRepository.
  • Store — PostgreSQL / Azure SQL.

CodeSymbol

  • Purpose — an extracted code symbol (type, method, interface, contract) for code-aware retrieval.
  • Key fields — codeSymbolId, codeRepositoryId, kind, fqName, filePath, signature, span.
  • Entities — SymbolReference.
  • Value objects — SymbolKind, SourceSpan, FullyQualifiedName.
  • Invariants — fqName unique within repository+commit; span within file.
  • Domain events — CodeSymbolExtracted.
  • Repository — CodeSymbolRepository.
  • Store — PostgreSQL / Azure SQL (+ Qdrant for embeddings).

CodeIndexJob

  • Purpose — tracks a repository indexing run across symbol, dependency, and embedding stages.
  • Key fields — codeIndexJobId, codeRepositoryId, commit, stages, progress, status.
  • Entities — IndexStageResult.
  • Value objects — IndexStage, JobStatus.
  • Invariants — resumable by stage; terminal once all stages complete or fail.
  • Domain events — CodeDependencyGraphBuilt, RepositoryIndexed.
  • Repository — CodeIndexJobRepository.
  • Store — PostgreSQL / Azure SQL.

Documentation Knowledge

Documentation Knowledge does not own a dedicated aggregate; it operates on shared MemoryRecord and VectorDocument aggregates, producing heading-aware chunks via the MarkdownChunkingWorker. Documentation provenance (source site, section path) is stored as MemoryRecord properties and projected as KnowledgeNodes of type Documentation.

Prompt & Decision Memory

PromptTemplate

  • Purpose — a reusable, version-controlled prompt bound to a skill.
  • Key fields — promptTemplateId, name, linkedSkillId, currentVersion, gitRef.
  • Entities — PromptVersion.
  • Value objects — TemplateName, GitRef.
  • Invariants — currentVersion exists; templates are source-controlled in Git.
  • Domain events — PromptTemplateRegistered.
  • Repository — PromptTemplateRepository.
  • Store — Azure DevOps Git + SQL.

PromptVersion

  • Purpose — an immutable version of a prompt body.
  • Key fields — promptVersionId, promptTemplateId, version, body, variables, commit.
  • Entities — none.
  • Value objects — SemVer, PromptVariable.
  • Invariants — immutable once published; declared variables resolvable at run time.
  • Domain events — PromptVersionPublished.
  • Repository — PromptVersionRepository.
  • Store — Azure DevOps Git + SQL.

PromptRun

  • Purpose — a recorded execution of a prompt version (inputs, model, outcome) for learning.
  • Key fields — promptRunId, promptVersionId, taskId, modelInvocationId, outcome, tokensUsed.
  • Entities — RunInput, RunOutput.
  • Value objects — RunOutcome, ModelRef.
  • Invariants — links to an existing PromptVersion; immutable after record.
  • Domain events — PromptRunRecorded.
  • Repository — PromptRunRepository.
  • Store — PostgreSQL / Azure SQL.

DecisionRecord

  • Purpose — an architectural decision record (ADR) capturing context, choice, and consequences.
  • Key fields — decisionRecordId, title, context, decision, consequences, status.
  • Entities — DecisionAlternative.
  • Value objects — DecisionStatus (Proposed/Accepted/Superseded/Rejected).
  • Invariants — exactly one chosen alternative when Accepted; supersedes chain is acyclic.
  • Domain events — DecisionRecorded.
  • Repository — DecisionRecordRepository.
  • Store — Azure DevOps Git + SQL.

DecisionAlternative

  • Purpose — a considered option for a decision, with pros/cons and a chosen flag.
  • Key fields — decisionAlternativeId, decisionRecordId, title, pros, cons, chosen.
  • Entities — none.
  • Value objects — TradeOff.
  • Invariants — belongs to one DecisionRecord; at most one chosen=true per record.
  • Domain events — DecisionAlternativeAdded.
  • Repository — DecisionAlternativeRepository.
  • Store — Azure DevOps Git + SQL.

Runtime Memory & Feedback

RuntimeSignal

  • Purpose — a runtime observation (latency, error, saturation, cost) ingested from Observability and linked to producing artifacts.
  • Key fields — runtimeSignalId, kind, metric, value, unit, environment, linkedArtifactId.
  • Entities — SignalDimension.
  • Value objects — SignalKind, MetricRef, Environment.
  • Invariants — immutable; environment valid; linked artifact exists when provided.
  • Domain events — RuntimeSignalRecorded.
  • Repository — RuntimeSignalRepository.
  • Store — App Insights / OTEL (telemetry) + SQL (index).

IncidentMemory

  • Purpose — a captured production incident with timeline, root cause, and resolution for future grounding.
  • Key fields — incidentMemoryId, severity, summary, rootCause, resolution, linkedSignals.
  • Entities — IncidentTimelineEntry.
  • Value objects — Severity, IncidentStatus.
  • Invariants — at least one linked RuntimeSignal; timeline ordered.
  • Domain events — IncidentMemoryCaptured.
  • Repository — IncidentMemoryRepository.
  • Store — PostgreSQL / Azure SQL.

FeedbackItem

  • Purpose — explicit human or automated feedback about an artifact, agent output, or decision.
  • Key fields — feedbackItemId, source, targetRef, sentiment, comment, rating.
  • Entities — none.
  • Value objects — FeedbackSource, Sentiment, Rating.
  • Invariants — targetRef resolvable; rating within range.
  • Domain events — FeedbackItemRecorded.
  • Repository — FeedbackItemRepository.
  • Store — PostgreSQL / Azure SQL.

Pattern Catalog

KnowledgePattern

  • Purpose — a reusable, recurring solution discovered across projects and promoted for reuse.
  • Key fields — knowledgePatternId, name, category, description, occurrences, confidence, currentVersion.
  • Entities — PatternVersion, PatternOccurrence.
  • Value objects — PatternCategory, Confidence.
  • Invariants — promoted only above a confidence/occurrence threshold; currentVersion exists.
  • Domain events — KnowledgePatternDiscovered.
  • Repository — KnowledgePatternRepository.
  • Store — Azure DevOps Git + SQL.

PatternVersion

  • Purpose — an immutable version of a pattern's canonical form and exemplar.
  • Key fields — patternVersionId, knowledgePatternId, version, exemplarRef, applicability.
  • Entities — none.
  • Value objects — SemVer, Applicability.
  • Invariants — immutable once published; references a real exemplar artifact.
  • Domain events — PatternVersionPublished.
  • Repository — PatternVersionRepository.
  • Store — Azure DevOps Git + SQL.

Knowledge Governance

MemoryAccessPolicy

  • Purpose — a declarative rule set governing who may access which memory under which conditions.
  • Key fields — memoryAccessPolicyId, name, rules, appliesTo, effectDefault.
  • Entities — PolicyRule.
  • Value objects — PolicyEffect (Allow/Deny/RedactRequired), PolicyScope.
  • Invariants — deterministic evaluation; explicit deny wins; tenant-scoped.
  • Domain events — MemoryAccessPolicyUpdated.
  • Repository — MemoryAccessPolicyRepository.
  • Store — PostgreSQL / Azure SQL.

MemoryAccessDecision

  • Purpose — the evaluated outcome of applying policy to a request over a set of resources.
  • Key fields — policyDecisionId, subject, resources, effects, purpose, evaluatedAt.
  • Entities — ResourceEffect.
  • Value objects — Subject, PolicyEffect.
  • Invariants — every requested resource has an effect; immutable record.
  • Domain events — MemoryAccessEvaluated.
  • Repository — MemoryAccessDecisionRepository.
  • Store — PostgreSQL / Azure SQL.

MemoryAccessAudit

  • Purpose — the immutable audit trail of access decisions for compliance.
  • Key fields — memoryAccessAuditId, policyDecisionId, subject, resources, traceId, recordedAt.
  • Entities — none.
  • Value objects — AuditOutcome.
  • Invariants — append-only; never deleted before retention; linked to a decision.
  • Domain events — MemoryAccessAudited.
  • Repository — MemoryAccessAuditRepository.
  • Store — PostgreSQL / Azure SQL.

MemoryClassification

  • Purpose — the assigned sensitivity and labels of a memory record.
  • Key fields — memoryClassificationId, memoryRecordId, classification, labels, confidence, classifierVersion.
  • Entities — none.
  • Value objects — Classification (Public/Internal/Confidential/Secret), Label.
  • Invariants — one live classification per record; Secret content never stored as artifact body.
  • Domain events — MemoryClassified.
  • Repository — MemoryClassificationRepository.
  • Store — PostgreSQL / Azure SQL.

KnowledgeQualityAssessment

  • Purpose — the scored evaluation of a memory record against quality rules.
  • Key fields — assessmentId, memoryRecordId, score, violations, ruleSetVersion.
  • Entities — RuleViolation.
  • Value objects — QualityScore, Severity.
  • Invariants — score within [0,1]; references existing QualityRules.
  • Domain events — KnowledgeQualityAssessed.
  • Repository — KnowledgeQualityAssessmentRepository.
  • Store — PostgreSQL / Azure SQL.

QualityRule

  • Purpose — a configurable rule defining a knowledge-quality expectation (completeness, freshness, consistency, lineage).
  • Key fields — qualityRuleId, name, dimension, expression, severity, enabled.
  • Entities — none.
  • Value objects — QualityDimension, RuleExpression.
  • Invariants — expression compiles; severity valid; versioned as a rule set.
  • Domain events — QualityRuleUpdated.
  • Repository — QualityRuleRepository.
  • Store — PostgreSQL / Azure SQL.

Context Building

ContextBuildRequest

  • Purpose — the captured request to assemble a Context Package for an agent task.
  • Key fields — contextBuildRequestId, taskId, agentId, skillId, intent, scope, retrieval.
  • Entities — RetrievalSpec.
  • Value objects — TokenBudget, Scope, Intent.
  • Invariants — tokenBudget > 0; scope tenant-consistent; one package per successful request.
  • Domain events — ContextBuildRequested.
  • Repository — ContextBuildRequestRepository.
  • Store — PostgreSQL / Azure SQL.

ContextPackage

  • Purpose — the assembled, governed, budgeted bundle of knowledge delivered to an agent (see schema).
  • Key fields — contextPackageId, contextBuildRequestId, sources, tokenBudget, tokensUsed, ttlSeconds, policyDecisionId, graphProjectionId.
  • Entities — ContextSource.
  • Value objects — TokenBudget, Ttl.
  • Invariants — tokensUsed <= tokenBudget; every source access-checked; linked to a MemoryAccessDecision.
  • Domain events — ContextPackageBuilt.
  • Repository — ContextPackageRepository.
  • Store — Redis (hot) + PostgreSQL / Azure SQL (durable record).

ContextSource

  • Purpose — a single ranked, access-checked knowledge item included in a Context Package.
  • Key fields — contextSourceId, kind, ref, title, score, classification, tokens, origin.
  • Entities — none.
  • Value objects — SourceKind, RetrievalOrigin (graph/semantic/metadata/pinned), RelevanceScore.
  • Invariants — classification allows inclusion (or redacted form); tokens counted toward budget.
  • Domain events — covered by ContextPackageBuilt.
  • Repository — ContextSourceRepository.
  • Store — Redis + SQL.

Ingestion

MemoryRecord

  • Purpose — the canonical unit of memory: the normalised, deduplicated record created for every artifact, doc, prompt, decision, code symbol, or signal that enters the platform. It is the anchor every other context references.
  • Key fields — memoryRecordId, kind, sourceRef, artifactId, contentHash, classification, qualityScore, lineage.
  • Entities — LineageLink, IngestionStageResult.
  • Value objects — MemoryKind, ContentHash, Lineage.
  • Invariants — contentHash unique per tenant (dedup); classification assigned before any read serves it; lineage links resolvable.
  • Domain events — MemoryRecordCreated, ArtifactIngested, MemoryMarkedStale.
  • Repository — MemoryRecordRepository.
  • Store — PostgreSQL / Azure SQL (with pointers to Blob/Qdrant/Git).

Aggregate-to-Context Summary

Bounded Context Aggregate Roots Count
Knowledge Graph KnowledgeNode, KnowledgeEdge, GraphProjection 3
Vector & Semantic Memory VectorDocument, VectorChunk, EmbeddingJob 3
Artifact Memory ArtifactMemory, ArtifactVersion, ArtifactSnapshot 3
Code Knowledge CodeRepository, CodeSymbol, CodeIndexJob 3
Documentation Knowledge (shared MemoryRecord / VectorDocument) 0
Prompt & Decision Memory PromptTemplate, PromptVersion, PromptRun, DecisionRecord, DecisionAlternative 5
Runtime Memory & Feedback RuntimeSignal, IncidentMemory, FeedbackItem 3
Pattern Catalog KnowledgePattern, PatternVersion 2
Knowledge Governance MemoryAccessPolicy, MemoryAccessDecision, MemoryAccessAudit, MemoryClassification, KnowledgeQualityAssessment, QualityRule 6
Context Building ContextBuildRequest, ContextPackage, ContextSource 3
Ingestion MemoryRecord 1
Total 32