Knowledge Graph

Target Architecture — Final-State Design

This page describes the final-state knowledge graph: the typed, multi-tenant graph that connects every meaningful entity the factory produces. It is owned by KnowledgeGraphService and persisted in PostgreSQL / Azure SQL via NHibernate.

The knowledge graph is the structural memory of the AI Software Factory. Where vector memory answers "what is similar?", the graph answers "what is connected?" — how a deployment traces back to a blueprint, which decisions shaped a module, what runtime signals a given artifact has generated, and which agent and skill produced any output. It is the backbone of traceability and reuse: a single traceId plus the graph lets any query walk from business intent to running SaaS and back.

Ontology

flowchart TB
    Tenant["Tenant"] --> Project["Project"]
    Project --> Blueprint["Blueprint"]
    Project --> BoundedContext["BoundedContext"]
    Blueprint --> BoundedContext
    BoundedContext --> Module["Module"]
    Module --> Artifact["Artifact"]
    Module --> Contract["Contract"]
    Module --> Event["Event"]
    Artifact --> Contract
    Artifact --> Event

    AgentTask["AgentTask"] --> Artifact
    Agent["Agent"] --> AgentTask
    Skill["Skill"] --> AgentTask
    AgentTask --> Skill

    Artifact --> Commit["Commit"]
    Commit --> PullRequest["PullRequest"]
    PullRequest --> Pipeline["Pipeline"]
    Pipeline --> Deployment["Deployment"]
    Deployment --> Module

    Deployment --> RuntimeSignal["RuntimeSignal"]
    RuntimeSignal --> FeedbackItem["FeedbackItem"]
    FeedbackItem --> Artifact
    RuntimeSignal --> Module

Hold "Alt" / "Option" to enable pan & zoom

The ontology is a closed set of node types so that queries and projections are predictable. Every node belongs to exactly one Tenant and (where applicable) one Project.

Node Types

Node Type	Represents	Key ref
Tenant	An isolated customer/organisation	tenant slug
Project	A factory project (the SaaS being produced)	proj-*
Blueprint	An architecture/service blueprint	bp-*
BoundedContext	A DDD bounded context within a project	context name
Module	A microservice, UI, worker, or library	module-*
Artifact	Any produced artifact (see artifact metadata)	art-*
Contract	An API or event contract	contract id
Event	A domain/integration event type	event type
AgentTask	A unit of agent work	task-*
Agent	An agent identity	ConnectSoft.Agent.*
Skill	A skill identity	ConnectSoft.Skill.*
Commit	A source commit	commit sha
PullRequest	A pull request	PR id
Pipeline	A CI/CD pipeline run	pipeline id
Deployment	A deployment to an environment	deployment id
RuntimeSignal	A runtime observation	rs-*
FeedbackItem	Human/automated feedback	feedback-*

Additional supporting node types (DecisionRecord, KnowledgePattern, PromptTemplate, Documentation, CodeSymbol) are projected from their owning contexts so the graph remains a complete map of factory knowledge.

Edge Types

Edge Type	From → To	Meaning
OWNS	Tenant → Project	Tenancy ownership
CONTAINS	Project → BoundedContext, BoundedContext → Module	Structural containment
DEFINES	Blueprint → BoundedContext / Module	Blueprint defines structure
PRODUCES	Module → Artifact / Contract / Event	Module produces an output
DERIVED_FROM	Artifact → Artifact	Lineage between artifacts
EXPOSES	Module → Contract	Module exposes a contract
EMITS	Module / Artifact → Event	Emits an event type
PRODUCED_BY	Artifact → AgentTask	Which task produced it
EXECUTED_BY	AgentTask → Agent	Which agent executed it
USED_SKILL	AgentTask → Skill	Which skill was used
RESULTED_IN	AgentTask → Commit	Task to commit
INCLUDED_IN	Commit → PullRequest	Commit to PR
BUILT_BY	PullRequest → Pipeline	PR to pipeline
DEPLOYED_BY	Pipeline → Deployment	Pipeline to deployment
RUNS	Deployment → Module	Deployment runs a module
GENERATED	Deployment / Module → RuntimeSignal	Runtime observation
TARGETS	FeedbackItem → Artifact	Feedback about an artifact
DEPENDS_ON	Module → Module / CodeSymbol → CodeSymbol	Dependency
INFORMED_BY	AgentTask → DecisionRecord / KnowledgePattern	Grounding used

All edges are directed, tenant-scoped, and uniquely keyed by (tenantId, from, to, edgeType). See Aggregate Roots for the KnowledgeNode/KnowledgeEdge/GraphProjection aggregates.

How the Graph Is Built

The graph is projected, not authored. The GraphProjectionWorker consumes domain/integration events (MemoryRecordCreated, ArtifactIngested, AgentTaskCompleted, RuntimeSignalRecorded, DecisionRecorded, …) and upserts the corresponding nodes and edges idempotently. Because every event carries the canonical envelope, the projection is deterministic and replayable via the KnowledgeReplayWorker.

flowchart LR
    Events["Envelope events"] --> GPW["GraphProjectionWorker"]
    GPW -->|upsert| Node["KnowledgeNode"]
    GPW -->|upsert| Edge["KnowledgeEdge"]
    Node --> SQL[("PostgreSQL / Azure SQL")]
    Edge --> SQL
    Query["graph/query"] --> Proj["GraphProjection (cached)"]
    Proj --> SQL

Hold "Alt" / "Option" to enable pan & zoom

Graph Query API

POST /knowledge/graph/query exposes neighbourhood and path traversal. The builder uses it to gather structural context; Factory Studio uses it for the Artifact Lineage Browser.

Request:

{
  "tenantId": "connectsoft",
  "projectId": "proj-booking-saas",
  "start": { "nodeType": "Deployment", "ref": "deploy-reservations-prod-44" },
  "traverse": {
    "edgeTypes": ["RUNS", "DEPLOYED_BY", "BUILT_BY", "INCLUDED_IN", "RESULTED_IN", "PRODUCED_BY"],
    "direction": "both",
    "maxDepth": 4
  },
  "returnNodeTypes": ["Module", "Artifact", "AgentTask", "Agent", "Blueprint"],
  "limit": 200
}

Response:

{
  "graphProjectionId": "gp-9001",
  "nodes": [
    { "nodeId": "kn-301", "nodeType": "Artifact", "ref": "art-serviceblueprint-reservations-1", "title": "Reservations service blueprint" },
    { "nodeId": "kn-415", "nodeType": "AgentTask", "ref": "task-4d21", "title": "Design reservations blueprint" }
  ],
  "edges": [
    { "edgeId": "ke-77", "from": "kn-301", "to": "kn-415", "edgeType": "PRODUCED_BY" }
  ]
}

Common Queries

• Lineage — "what produced this deployment?" (walk RUNS → DEPLOYED_BY → BUILT_BY → INCLUDED_IN → RESULTED_IN → PRODUCED_BY).
• Impact — "what depends on this contract?" (inbound EXPOSES/DEPENDS_ON).
• Reuse — "which projects used this pattern?" (INFORMED_BY to KnowledgePattern).
• Attribution — "which context/decisions shaped this artifact?" (PRODUCED_BY → INFORMED_BY).
• Feedback — "what runtime signals does this module generate?" (RUNS → GENERATED).

Relationship to Existing Implementation

Implemented

The graph schema, indices, and query design are grounded in the existing implementation docs:

• Knowledge & Memory Graph
• Knowledge & Memory Indices
• Knowledge & Memory System

Related Pages

• Aggregate Roots
• Data Model
• Context Builder
• Artifact Metadata
• APIs — graph/query