Bilingual Navigation: English (this document) · Versión en Español
This document defines the tactical and strategic design for the Design Bounded Context based on Domain-Driven Design (DDD) principles. This module enforces the Spec-as-Source principle.
Strict terminology shared between business and technical code within this context:
- Technical Blueprint: The master package grouping all approved design artifacts for a specific initiative.
- Technical Contract: A formal, immutable technical specification (e.g., OpenAPI YAML, AsyncAPI) generated from User Stories.
- ADR (Architectural Decision Record): A formal document capturing a technical decision, context, and consequences.
- Data Schema: The entity-relationship definition or database schema design.
- Architecture Gate: A formal review checkpoint to prevent Architecture Drift.
- C4 Generator: Cross-context tool that generates C4 architecture diagrams (Context, Container, Component, Code) from internal model data.
- STRIDE Analyzer: Cross-context tool that applies STRIDE threat modeling to architecture models during Design review.
To improve readability and font sizing, the model has been split into multiple architectural views.
| Symbol/Stereotype | Meaning |
|---|---|
<<Aggregate Root>> |
Transactional root entity. Governs the persistence and consistency of its internal entities. |
<<Value Object>> |
Immutable object without intrinsic identity. Represents a structural property. |
<<Shared Kernel Shell>> |
Cross-cutting module external to the domain, injected by the application/infrastructure layer. |
*-- (Solid line) |
Composition. The child element cannot exist without the parent. |
..> (Dotted line) |
Dependency. The element interacts with or delegates to another component. |
Tip
Viewing Options: If the diagrams appear small in your current Markdown viewer, copy the code block into the Mermaid Live Editor to enable zooming, infinite panning, and high-res SVG exporting.
Displays the main Aggregate Roots. The central Aggregate is TechnicalBlueprint, but artifacts are separate Aggregate Roots to allow concurrent O(1) editing.
classDiagram
class TechnicalBlueprint {
<<Aggregate Root>>
+UUID id
+UUID initiativeId
+String tenantId
+DesignStatus status
+String version
+UUID authorId_umsUserId
+List~UUID~ reviewerIds_umsUserId
+List~String~ tags
+List~UUID~ contractIds
+List~UUID~ adrIds
+List~UUID~ schemaIds
+List~UUID~ epicIds
+List~ExternalReference~ externalRefs
+submitForApproval()
+approve(ArchitectureGate, UUID umsUserId)
+reject(String reason, UUID umsUserId)
+addReviewer(UUID umsUserId)
+createNewVersion(UUID umsUserId)
}
class TechnicalContract {
<<Aggregate Root>>
+UUID id
+UUID blueprintId
+ContractType type
+String contentPayload
+String format
+Date deprecationDate
+Boolean isActive
+List~UUID~ linkedStoryIds
+List~ExternalReference~ externalRefs
+List~VersionEntry~ versionHistory
+updatePayload(String content, UUID umsUserId)
+deprecate(UUID umsUserId)
+restoreVersion(String versionId, UUID umsUserId)
}
class VersionEntry {
<<Value Object>>
+String versionId
+Int versionNumber
+String authorId_umsUserId
+Date date
+String diffSummary
+String contentSnapshot
}
class ADR {
<<Aggregate Root>>
+UUID id
+UUID blueprintId
+String title
+String context
+String decision
+String consequences
+UUID authorId_umsUserId
+List~String~ tags
+List~ExternalReference~ externalRefs
+updateContent(UUID umsUserId)
}
class DataSchema {
<<Aggregate Root>>
+UUID id
+UUID blueprintId
+String schemaPayload
+String version
+UUID authorId_umsUserId
+updatePayload(UUID umsUserId)
}
class ExternalReference {
<<Value Object>>
+ExternalSystem system
+String externalId
+String url
+ReferenceType type
+String label
+Date linkedAt
+Map metadata
}
class VersionEntry {
<<Value Object>>
+String versionId
+Int versionNumber
+String authorId_umsUserId
+Date date
+String diffSummary
+String contentSnapshot
}
TechnicalBlueprint "1" --> "0..*" TechnicalContract : referenced by
TechnicalBlueprint "1" --> "0..*" ADR : referenced by
TechnicalBlueprint "1" --> "0..*" DataSchema : referenced by
TechnicalBlueprint "1" *-- "0..*" ExternalReference : mapped to
TechnicalContract "1" *-- "0..*" ExternalReference : mapped to
TechnicalContract "1" *-- "0..*" VersionEntry : version history
ADR "1" *-- "0..*" ExternalReference : mapped to
Zooms in on the Value Objects used by the TechnicalBlueprint to maintain transactional progress.
classDiagram
class RequirementChecklist {
<<Value Object>>
+List~RequirementItem~ items
+isReadyForApproval() Boolean
+markItemCompleted(String code)
}
class RequirementItem {
<<Value Object>>
+String code
+Boolean isMandatory
+RequirementStatus status
}
class StateTransition {
<<Value Object>>
+DesignStatus fromState
+DesignStatus toState
+Date transitionDate
+String triggeredBy
+String reason
}
class ArchitectureGate {
<<Value Object>>
+String leadArchitectId
+GateDecision decision
+String justification
+Date decidedAt
}
class AuditControl {
<<Value Object>>
+String createdBy
+Date createdAt
}
class TechnicalBlueprint {
<<Aggregate Root>>
}
TechnicalBlueprint "1" *-- "1" RequirementChecklist : validates against
RequirementChecklist "1" *-- "1..*" RequirementItem : contains
TechnicalBlueprint "1" *-- "1" AuditControl : tracked by
TechnicalBlueprint "1" *-- "0..*" StateTransition : workflow history
TechnicalBlueprint "1" *-- "0..1" ArchitectureGate : governed by
Describes the interaction between the Design domain and the Shared Kernels.
classDiagram
class WorkflowEngine {
<<Shared Kernel Shell>>
+validateTransition()
+evaluateApprovalGate()
}
class TenantConfigShell {
<<Shared Kernel Shell>>
+getTenantWorkflowRules()
}
class IntegrationFabric {
<<Shared Kernel Shell>>
+exportBlueprintPayload()
}
class UMS_SDK {
<<Cross-Cutting>>
+RequiresDomainAccess()
}
class TechnicalBlueprint {
<<Aggregate Root>>
}
%% Infrastructure Dependencies
TechnicalBlueprint ..> TenantConfigShell : reads dynamic rules (isMandatory)
TechnicalBlueprint ..> WorkflowEngine : delegates state machine
TechnicalBlueprint ..> UMS_SDK : secured via
TechnicalBlueprint ..> IntegrationFabric : exported via
TechnicalBlueprint: Encapsulates the design phase lifecycle. Instead of physically containing all contracts, it holdsUUIDreferences. This avoids concurrency locks.- Individual Artifacts (
TechnicalContract,ADR,DataSchema): Independent technical specifications.
RequirementChecklist/RequirementItem: Injected by theWorkflowEngineto track mandatory/optional steps (e.g. Threat Modeling) based on Tenant config. Blocks progression if pending.AuditControl: Mandatory Evolith standard.StateTransition: Immutable record of a status change.ArchitectureGate: Encapsulates the strict approval criteria.VersionEntry: Immutable record of a contract version snapshot, enabling full version history with restore capability (US-DES-007).
- Application Layer & SDK: The UMS SDK is utilized at the Application Services layer.
- Pure Domain Execution: The Aggregate Roots do not depend on the UMS SDK.
- The Design module listens for the
BacklogGeneratedEvent(in "generate" backlog mode) OR theInitiativeApprovedEvent(in "initiative-only" mode) via the local In-Memory Event Bus to initialize aTechnicalBlueprintin DRAFT status.
- Emits a
DesignApprovedEventintercepted by the Construction module to generate source code scaffolding.