BlueprintService

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-02 Blueprint
Platform / plane	Template & Library / Software Factory pack
Deployment granularity	module of host · host TemplateCatalogHost
Status	target · ConnectSoft.Factory.Templates.Blueprints
Built from	connectsoft-microservice · libraries: connectsoft-extensions-saas-abstractions, connectsoft-extensions-messaging-model, connectsoft-extensions-persistence-model-nhibernate
Decisions	ADR-0021
Traceability	FR-02 FR-03 FUX-01 FUX-03 NFR-11 XL-07

Purpose and responsibilities

BlueprintService makes blueprints executable inputs rather than prose. Each blueprint version is a descriptor document of one kind (vision, service, module, frontend and frontend library, backend library and API library, API gateway, database, security, pipeline, observability, integration, infrastructure, documentation, localization, mobile, test, UX, agent microservice, agentic SaaS product, SaaS descriptor) stored as an artifact and validated against the kind's JSON Schema in the descriptor registry and the kind's rule set; findings carry rule ids. For service and module kinds the validator derives a context map (contexts, relationships, published-language events) and a domain model per context (aggregates, entities, value objects, invariants, events) — the typed inputs of generation. A validated version is submitted to Asset Publication (BC-04), passes its evaluation gate (ADR-0021) and becomes a Published blueprint release that recipes may use.

It absorbs the June-2026 parser, validator, context-map and domain-model rows.

Context and boundaries

flowchart LR
    S["BlueprintService"]
    GenerationRecipeService["GenerationRecipeService"] -->|grpc| S
    AgentRuntimeWorker["AgentRuntimeWorker"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    S -->|grpc| ArtifactService["ArtifactService"]
    S -->|grpc| AgentRegistryService["AgentRegistryService"]
    S -->|grpc| EnvelopeRegistryService["EnvelopeRegistryService"]
    S -. "BlueprintValidated" .-> E_BlueprintValidated(("event"))
    S -. "BlueprintSubmitted" .-> E_BlueprintSubmitted(("event"))
    S -. "BlueprintPublished" .-> E_BlueprintPublished(("event"))
    S -. "ContextMapDerived" .-> E_ContextMapDerived(("event"))
    S -. "DomainModelDerived" .-> E_DomainModelDerived(("event"))

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

People author blueprints in the Studio; agents author them in generation runs through the write-file and propose-change-set tools, so a blueprint written by an agent carries run provenance like any artifact. Derived models are never edited: a change is a blueprint change. The 22 blueprint pages and their schemas are specified in design plan B1.

Domain model

BlueprintVersion — One version of one blueprint document of a kind for a project: the descriptor content as an artifact, its schema version, validation state and report, derived context map and domain model references, the asset release it became, and provenance to the run or person that authored it. (catalog entry)

Field	Type	Required	Description
blueprintId	string	yes
version	string	yes
tenantId	string	yes
projectId	string	yes
kind	enum:BlueprintKind	yes
schemaVersion	string	yes
documentRef	string	yes	Artifact reference of the descriptor.
documentHash	string	yes
state	enum:BlueprintState	yes
validationReportRef	string	no
contextMapRef	string	no
domainModelRef	string	no
releaseId	string	no
authoredBy	string	yes	user or run id
createdAt	datetime	yes

Invariants:

• A blueprint is Validated only when its document passes its kind's JSON Schema and every rule of the kind's validation rule set; findings carry rule ids.
• Service and module blueprints must reference a context map and a domain model derived from them; a change to the document invalidates the derived artifacts.
• Publication goes through Asset Publication (BC-04) and its evaluation gate; this service never marks Published on its own.

stateDiagram-v2
    Draft --> Validated : ValidationPassed
    Validated --> Draft : DocumentChanged
    Validated --> Submitted : SubmitForPublication
    Submitted --> Published : AssetReleasePublished
    Published --> Deprecated : AssetReleaseDeprecated

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

Events: BlueprintValidated, BlueprintSubmitted, BlueprintPublished · Tables: BlueprintVersions, ValidationFindings · Repository: BlueprintVersionRepository

ContextMap — The bounded contexts, relationships (upstream, downstream, shared kernel, anti-corruption layer) and published-language events derived from a vision or service blueprint; the source of the generated product's bounded-context catalog. (catalog entry)

Field	Type	Required	Description
contextMapId	guid	yes
tenantId	string	yes
projectId	string	yes
blueprintId	string	yes
blueprintVersion	string	yes
contexts	json	yes
relationships	json	yes
publishedEvents	json	yes
derivedAt	datetime	yes

Invariants:

• Derived, never edited; a change is a blueprint change.

Events: ContextMapDerived · Tables: ContextMaps · Repository: ContextMapRepository

DomainModel — Aggregates, entities, value objects, invariants and events per bounded context derived from a service or module blueprint; the typed input of the entity-model, persistence and API generation. (catalog entry)

Field	Type	Required	Description
domainModelId	guid	yes
tenantId	string	yes
projectId	string	yes
blueprintId	string	yes
blueprintVersion	string	yes
contextId	string	yes
aggregates	json	yes
events	json	yes
derivedAt	datetime	yes

Invariants:

• Every aggregate has a root entity, an identity and at least one invariant; every event names its aggregate.

Events: DomainModelDerived · Tables: DomainModels · Repository: DomainModelRepository

erDiagram
    BlueprintVersion {
        string blueprintId PK
        string version
        string tenantId
        string projectId
        enum_BlueprintKind kind
        string schemaVersion
        string documentRef
        string documentHash
        enum_BlueprintState state
        string validationReportRef
        string contextMapRef
        string domainModelRef
        string releaseId
        string authoredBy
        datetime createdAt
    }
    ContextMap {
        guid contextMapId PK
        string tenantId
        string projectId
        string blueprintId
        string blueprintVersion
        json contexts
        json relationships
        json publishedEvents
        datetime derivedAt
    }
    DomainModel {
        guid domainModelId PK
        string tenantId
        string projectId
        string blueprintId
        string blueprintVersion
        string contextId
        json aggregates
        json events
        datetime derivedAt
    }
    ValidationFinding {
        string ruleId

        string severity

        string path

        string message

    }
    BlueprintVersion ||--o{ ValidationFinding : contains

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

Entities and value objects

ValidationFinding (entity, in BlueprintVersion) — One validation finding with rule id and severity.

Field	Type	Required	Description
ruleId	string	yes
severity	string	yes	error
path	string	yes
message	string	yes

Data model and storage

Store	Role	Engine / profile	Tables
Template & Library store	primary	azure-sql / nhibernate-sqlserver	BlueprintVersions, ValidationFindings, ContextMaps, DomainModels
Artifact content store	blob	blob / azure-blob	—

Table	Owner	Columns	Indexes
dbo.BlueprintVersions	BlueprintVersion	15	1
dbo.ValidationFindings	ValidationFinding	8	0
dbo.ContextMaps	ContextMap	9	1
dbo.DomainModels	DomainModel	9	1

Full DDL: appendix.

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/factory/blueprints	ListBlueprints	factory.blueprints.read	read	natural	GW-03	Blueprints of a project by kind and state with versions.
GET	/factory/blueprints/{blueprintId}/versions/{version}	GetBlueprintVersion	factory.blueprints.read	read	natural	GW-03	One version with document, validation report, context map and domain model references.
POST	/factory/blueprints	CreateBlueprintVersion	factory.blueprints.write	shared-write	key-header	GW-03	Store a descriptor document as a new Draft version (people through the Studio; agents through the write-file and propose-change-set tools under their run).
POST	/factory/blueprints/{blueprintId}/versions/{version}/validate	ValidateBlueprint	factory.blueprints.write	shared-write	natural	GW-03	Validate against the kind's schema and rules; derive the context map and domain model; store the report.
POST	/factory/blueprints/{blueprintId}/versions/{version}/submit	SubmitBlueprint	factory.blueprints.publish	publication	natural	GW-03	Submit a Validated version to Asset Publication as a blueprint release candidate.

gRPC service	Method	Streaming	Visibility	Side effects	Summary
Blueprints	GetDerivedModel	none	internal	read	Context map and domain model for a blueprint version (generation recipes and agents read it).

Messages

Event	Topic	Scope / v	Aggregate	Consumers	Summary
BlueprintValidated	blueprints.versions.v1.blueprint-validated	integration / 1	BlueprintVersion	StudioBff, RunControlService, GenerationRecipeService, AuditService	A version passed (or failed) validation with a report.
BlueprintSubmitted	blueprints.versions.v1.blueprint-submitted	integration / 1	BlueprintVersion	AgentRegistryService, StudioBff, AuditService	A validated version was submitted to Asset Publication.
BlueprintPublished	blueprints.versions.v1.blueprint-published	integration / 1	BlueprintVersion	GenerationRecipeService, StudioBff, AuditService, DashboardService	The version is Published as an asset release.
ContextMapDerived	blueprints.models.v1.context-map-derived	integration / 1	ContextMap	GenerationRecipeService, StudioBff	A context map was derived.
DomainModelDerived	blueprints.models.v1.domain-model-derived	integration / 1	DomainModel	GenerationRecipeService, StudioBff	A domain model was derived for a context.

BlueprintValidated payload:

Field	Type	Required	Description
blueprintId	string	yes
version	string	yes
tenantId	string	yes
projectId	string	yes
kind	enum:BlueprintKind	yes
passed	bool	yes
validationReportRef	string	yes

BlueprintSubmitted payload:

Field	Type	Required	Description
blueprintId	string	yes
version	string	yes
tenantId	string	yes
projectId	string	yes

BlueprintPublished payload:

Field	Type	Required	Description
blueprintId	string	yes
version	string	yes
tenantId	string	yes
projectId	string	yes
releaseId	string	yes

ContextMapDerived payload:

Field	Type	Required	Description
contextMapId	guid	yes
tenantId	string	yes
projectId	string	yes
blueprintId	string	yes
blueprintVersion	string	yes
contexts	int	yes

DomainModelDerived payload:

Field	Type	Required	Description
domainModelId	guid	yes
tenantId	string	yes
projectId	string	yes
blueprintId	string	yes
contextId	string	yes
aggregates	int	yes

Command	Handled by	Result events	Summary
CreateBlueprintVersion	BlueprintVersion	—
ValidateBlueprint	BlueprintVersion	BlueprintValidated, ContextMapDerived, DomainModelDerived
SubmitBlueprint	BlueprintVersion	BlueprintSubmitted

Event	Producer	Handler	Purpose
AssetReleasePublished	AgentRegistryService	MarkPublished	Blueprint releases published by Asset Publication.
AssetReleaseDeprecated	AgentRegistryService	MarkDeprecated	Deprecated blueprint releases.
ArtifactValidated	ArtifactService	AttachValidation	Artifact-level validators of descriptor documents.

Workers and jobs

Worker	Trigger	Output events	Retry	Idempotency key	Summary
Validator	event	BlueprintValidated, ContextMapDerived, DomainModelDerived	fixed	blueprintId + version + documentHash	Runs schema validation and the kind's rule set, derives the context map and domain model for service and module kinds, and writes the report as an artifact.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

stateDiagram-v2
    [*] --> Draft
    Draft --> Validated: ValidationPassed (schema + rules; models derived)
    Validated --> Draft: DocumentChanged
    Validated --> Submitted: SubmitForPublication
    Submitted --> Published: AssetReleasePublished (BC-04 gate)
    Published --> Deprecated: AssetReleaseDeprecated
    Deprecated --> [*]

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

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Templates:Blueprints	SchemaRegistryPath	string	reference/schemas	no	no	Where blueprint JSON Schemas are registered (descriptor registry).
Templates:Blueprints	FailOnWarnings	bool	false	yes	no	Treat warnings as validation failures.

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.blueprints.versions	counter	{version}	tenant, kind, state	Blueprint versions by kind and state.
connectsoft.factory.blueprints.validation_failures	counter	{finding}	kind, ruleId	Findings by rule.

Security

Authentication	client-credentials
Scopes	factory.blueprints.read (Read blueprints and derived models.); factory.blueprints.write (Create and validate versions (Requester, Asset maintainer, agents under a run).); factory.blueprints.publish (Submit for publication (Asset maintainer).)
Roles	Requester, AssetMaintainer, Reviewer, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	confidential
Max side-effect class	publication
Secrets	—

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
ArtifactService	grpc	Descriptor documents, reports, derived models.	fail-fast	yes
AgentRegistryService	grpc	Submit blueprint release candidates.	fail-fast	yes
EnvelopeRegistryService	grpc	Validate published-language events of a context map against the topic registry conventions.	degrade	no

Inbound

Target	Kind	Purpose	Failure mode	Required
GenerationRecipeService	grpc	Derived models for recipes.	—	yes
AgentRuntimeWorker	grpc	Agents read and derive during generation runs.	—	yes
StudioBff	sync-http	Blueprint views.	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Schema for a kind missing or stale	validator cannot resolve the schema version	validation fails with the schema id; the descriptor registry is corrected (B1)	none	0

NFR targets

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment

Granularity	module of host · host TemplateCatalogHost
Topologies	saas-default, hybrid, on-prem
Runtime	—; replicas —–—
Ports	—

Current implementation

22 blueprint pages exist as narrative; dsls.md describes descriptor languages; no schema, validator or derived model exists. B1 adds the JSON Schemas.

Later capabilities

Blueprint diffing between versions with impact on generated modules; blueprint linting agents proposing fixes as change sets; cross-project blueprint reuse through the marketplace.

Decisions and traceability

Family	Ids
FR	FR-02, FR-03
FUX	FUX-01, FUX-03
NFR	NFR-11
XL	XL-07

Related

• Overview · Workflows · Blueprints overview · DSLs · AgentRegistryService

• Template & Library microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map