Skip to content

ddd-model.md

Latest commit

 

History

History
306 lines (259 loc) · 14 KB

ddd-model.md

File metadata and controls

306 lines (259 loc) · 14 KB

Evolith Tracker: DDD Model - Artifacts Module

Bilingual Navigation: English (this document) · Versión en Español

This document defines the tactical and strategic design for the Artifacts Bounded Context. It is a supporting subdomain that governs the lifecycle of every artifact and evidence record produced across the 5 Phase Gates — the durable, auditable proof that each gate was legitimately passed. Artifact definitions are inherited from Evolith Core (Conformist); artifact instances and evidence are produced locally. Aggregate sources: TAD §3. Strategic relationships: Bounded Context Map.

1. Ubiquitous Language

  • Artifact Definition: The canonical schema/template of an artifact type (e.g., Discovery Canvas, ADR, Technical Blueprint, Test Summary), inherited from Evolith Core. Immutable upstream.
  • Artifact Instance: A concrete artifact produced by a gate against a definition, bound to a tenant and an SDLC execution.
  • Evidence Record: Immutable proof that links an artifact instance (or external result) to the gate decision it justified. The backbone of auditability (BR-009).
  • Evidence Chain: The ordered set of evidence records that traces an initiative from idea to deployment.
  • Validation Result: The outcome of checking an artifact instance against its definition and Evolith Core rulesets.

2. Conceptual Maps and Aggregates (Mermaid)

2.0. Visual Legends and Glossary

Symbol/Stereotype Meaning
<<Aggregate Root>> Transactional root entity.
<<Entity>> Identity-bearing object dependent on its root.
<<Value Object>> Immutable object without intrinsic identity.
<<Shared Kernel Shell>> Cross-cutting module injected by application/infrastructure.
*-- (Solid line) Composition.
..> (Dotted line) Dependency.

2.1. View 1: Artifacts Core (Aggregates and Entities)

classDiagram
    class ArtifactDefinition {
        <<Aggregate Root>>
        +UUID id
        +String code
        +String name
        +String coreSchemaUrl
        +SDLCPhase phase
        +String version
        +Boolean isMandatory
        +syncFromCore(CoreArtifactSchema)
        +deprecate()
    }

    class ArtifactInstance {
        <<Aggregate Root>>
        +UUID id
        +String tenantId
        +UUID artifactDefinitionId
        +UUID sdlcExecutionId
        +SDLCPhase phase
        +ArtifactFormat format
        +String contentRef
        +ArtifactStatus status
        +submit(UUID umsUserId)
        +validate(ValidationResult)
        +supersede(UUID newInstanceId)
    }

    class EvidenceRecord {
        <<Aggregate Root>>
        +UUID id
        +String tenantId
        +UUID sdlcExecutionId
        +SDLCPhase phase
        +EvidenceType type
        +UUID artifactInstanceId
        +String sourceSystem
        +Date capturedAt
        +capture(UUID umsUserId)
    }

    class ValidationResult {
        <<Entity>>
        +Boolean isCompliant
        +List~String~ violations
        +String validatedAgainstRuleset
        +Date validatedAt
    }

    ArtifactDefinition "1" --> "0..*" ArtifactInstance : templates
    ArtifactInstance "1" *-- "0..1" ValidationResult : validated by
    ArtifactInstance "1" --> "0..*" EvidenceRecord : evidenced by
Loading

2.2. View 2: Evidence Chain & Audit (Value Objects)

classDiagram
    class EvidenceChain {
        <<Value Object>>
        +List~UUID~ orderedEvidenceIds
        +append(UUID evidenceRecordId)
        +isComplete(SDLCPhase) Boolean
    }

    class ContentReference {
        <<Value Object>>
        +String storageProvider
        +String uri
        +String checksum
    }

    class AuditControl {
        <<Value Object>>
        +String createdBy
        +Date createdAt
        +String modifiedBy
        +Date modifiedAt
    }

    class ArtifactInstance {
        <<Aggregate Root>>
    }
    class EvidenceRecord {
        <<Aggregate Root>>
    }

    ArtifactInstance "1" *-- "1" ContentReference : stored as
    ArtifactInstance "1" *-- "1" AuditControl : tracked by
    EvidenceRecord "1" *-- "1" AuditControl : tracked by
    EvidenceRecord "1" --> "1" EvidenceChain : participates in
Loading

2.3. View 3: Cross-Cutting Infrastructure (Shells)

classDiagram
    class CoreIntegrationShell {
        <<Shared Kernel Shell>>
        +getArtifactDefinitions(phase)
        +validateAgainstRuleset()
    }
    class TenantConfigShell {
        <<Shared Kernel Shell>>
        +getMandatoryArtifacts(phase)
    }

    class ArtifactDefinition {
        <<Aggregate Root>>
    }
    class ArtifactInstance {
        <<Aggregate Root>>
    }

    ArtifactDefinition ..> CoreIntegrationShell : synced from Core
    ArtifactInstance ..> CoreIntegrationShell : validated via ruleset
    ArtifactInstance ..> TenantConfigShell : mandatory check
Loading

3. Tactical Design

3.1. Aggregate Roots (Small Aggregates)

  1. ArtifactDefinition: Mirror of a Core artifact schema. Synced from Evolith Core (Conformist); never invented locally (BR-005). Per [Catalog Contract rule R-16], carries code, value, and description.
  2. ArtifactInstance: A produced artifact bound to a tenant + execution. Holds a ContentReference (the payload lives in object storage, not the row).
  3. EvidenceRecord: Immutable, append-only proof. Once captured, never mutated (supports the append-only tracker_audit discipline and BR-009).

3.2. Value Objects

  • EvidenceChain: Ordered evidence trail per execution; the spine of end-to-end traceability.
  • ContentReference: Pointer + checksum to externally stored artifact content.
  • ValidationResult: Outcome of compliance checking against a Core ruleset.

3.3. Core Integration (Conformist)

  • Artifact definitions are fetched at runtime from Evolith Core (no second source of truth, per TAD §17). When Core's artifact schema URLs are published (currently "Under Construction"), this context consumes them directly. Until then, see UPSTREAM_PROPOSALS.

3.4. Immutability & Audit

  • EvidenceRecord is write-once. Tenant-scoped and RLS-enforced (Security Spec §5, §7 DP-5).

4. Context Mapping (Boundary Integration)

  • Conformist to Evolith Core: inherits ArtifactDefinition schemas.
  • Customer of all 5 gates (Customer-Supplier): receives ArtifactInstance / EvidenceRecord payloads emitted as gate work completes.
  • Supplier to Governance: PhaseGateState references EvidenceRecord IDs to authorize gate transitions.
  • Supplier to Metrics: evidence timestamps feed lead-time / DORA computations.

Artifact Registry

The following ArtifactDefinitions are synced from Evolith Core. Each entry represents a Core-defined artifact schema that the Tracker instantiates, validates, and displays via tenant-configurable views.

Phase 1: Discovery

ArtifactDefinition ID Name Required Has Template Has Schema
prd PRD — Product Requirements Document Y Y Y
discovery-canvas Discovery Canvas Y Y Y
business-case-roi Business Case (ROI) Y Y Y
ballpark-estimation Ballpark Estimation Y Y Y
evolith-user-story Evolith User Story Y Y Y
agile-backlog Agile Backlog Y Y Y
cli-impact-analysis CLI Impact Analysis Y Y Y
architectural-directives Architectural Directives Y Y —
repository-taxonomy Repository Taxonomy Y Y —
agnostic-baseline Agnostic Baseline (Tech Stack) Y Y —
adr-0047-monolith ADR-0047 — Modular Monolith Selection Y Y —
engineering-manifesto Engineering Manifesto Y Y —
moscow-prioritization MoSCoW Prioritization Matrix Y — —

Optional: | evolutionary-roadmap | Evolutionary Strategy Roadmap | — | Y | — | | maturity-assessment | Maturity Assessment | — | Y | — | | architecture-communication-strategy | Architecture Communication Strategy | — | Y | — | | ums-reference-model | UMS Reference Model | — | Y | — |

Phase 2: Design

ArtifactDefinition ID Name Required Has Template Has Schema
api-contracts API/Event Contracts Y — Y
adr ADR (Decision Record) Y Y Y
data-schema Data Schema Definition Y — —
technical-blueprint Technical Blueprint Y — —
reference-blueprint Reference Blueprint Y Y —
authoritative-tech-stack Authoritative Tech Stack Y Y —
adr-decision-matrix ADR Decision Matrix Y Y —
adr-0002-hexagonal ADR-0002 — Hexagonal Architecture Y Y —
adr-0018-testing-pyramid ADR-0018 — Testing Pyramid Y Y —
adr-0031-schema-context ADR-0031 — Schema-per-Context Y Y —
adr-0032-protocol-matrix ADR-0032 — Protocol Selection Matrix Y Y —
adr-0056-naming-conventions ADR-0056 — Naming and Design Conventions Y Y —
functional-story Functional Story Y Y Y
functional-story-standard Functional Story Writing Standard Y Y —
sdlc-doc-best-practices SDLC Documentation Best Practices Y Y —
simplicity-checklist-p1 Simplicity Checklist (Phase 1) Y Y —
bounded-context-map Bounded Context Map (C4) Y — —

Optional: | adr-0010-multitenancy | ADR-0010 — Multi-Tenancy | — | Y | — | | adr-0045-extraction-readiness | ADR-0045 — Extraction Readiness Criteria | — | Y | — | | c4-topology-spec | C4 Topology Spec | — | — | — | | cap-strategic-analysis | CAP Strategic Analysis | — | Y | — | | observability-architecture-flow | Observability Architecture Flow | — | Y | — | | canonical-patterns | Canonical Patterns | — | Y | — |

Phase 3: Construction

ArtifactDefinition ID Name Required Has Template Has Schema
technical-story Technical Story Y Y Y
drift-report Drift Report Y — —
code-coverage-report Code Coverage Report Y — —
peer-review-summary Peer Review Summary Y — —
definition-of-done Definition of Done Checklist Y Y —
documentation-delta Documentation Delta Y — —
engineering-manifesto Engineering Manifesto Y Y —
sdlc-framework-construction SDLC Framework (Construction SS3-4) Y Y —
sdlc-quality-gates SDLC Quality Gates Y Y —
adr-0005-cicd ADR-0005 — CI/CD Pipeline Y Y —
adr-0018-testing-pyramid ADR-0018 — Testing Pyramid Y Y —
adr-0049-naming-semantics ADR-0049 — Naming Semantics and Clean Code Y Y —
adr-0050-gitflow ADR-0050 — GitFlow Branching Strategy Y Y —
sdlc-doc-best-practices SDLC Documentation Best Practices Y Y —
canonical-patterns Canonical Patterns Y Y —
ci-pipeline-evidence CI Pipeline Evidence Y — —
coverage-report-external Coverage Report Y — —

Phase 4: QA

ArtifactDefinition ID Name Required Has Template Has Schema
test-summary-report Test Summary Report Y Y Y
sdlc-quality-gates SDLC Quality Gates Y Y —
adr-0018-testing-pyramid ADR-0018 — Testing Pyramid Y Y —
adr-0052-unit-testing-isolation ADR-0052 — Unit Testing Isolation Strategy Y Y —
adr-0053-integration-e2e-testing ADR-0053 — Integration/E2E Testing Strategy Y Y —
acceptance-validation Acceptance Validation Y — —
security-scan-report Security Scan Report Y — —
pyramid-distribution-evidence Pyramid Distribution Evidence Y — —

Optional: | contract-testing-guideline | Contract Testing Guideline | — | Y | — | | adr-0037-performance-chaos | ADR-0037 — Performance/Chaos Verification | — | Y | — | | vendor-risk-assessment | Vendor Risk Assessment | — | Y | — | | observability-architecture-flow | Observability Architecture Flow | — | Y | — |

Phase 5: Release

ArtifactDefinition ID Name Required Has Template Has Schema
release-notes Release Notes Y Y Y
rollback-procedure Rollback Procedure Y Y —
deployment-evidence Deployment Evidence Y — —
adr-0007-otel-loki ADR-0007 — OTel and Loki Observability Y Y —
adr-0013-cloud-topology-dr ADR-0013 — Cloud Topology and DR Y Y —
adr-0005-cicd ADR-0005 — CI/CD Pipeline Y Y —
operations-hub Operations Hub Y Y —
infrastructure-hub Infrastructure Hub Y Y —
sdlc-doc-best-practices SDLC Documentation Best Practices Y Y —
observability-validation Observability Validation Y — —

Cross-cutting

ArtifactDefinition ID Name Required Has Template Has Schema
agnostic-baseline Agnostic Baseline Y Y —
reference-blueprint Reference Architecture Blueprint Y Y —
engineering-manifesto Engineering Manifesto Y Y —
definition-of-done Definition of Done Y Y —
repository-taxonomy Repository Taxonomy Y Y —
gate-evidence Gate Evidence Y — Y

Note: ArtifactDefinitions marked with "Has Schema" have JSON schemas published in Evolith Core's rulesets/schema/ directory. Those without schemas are documented as templates in 04-artifact-templates/. The Tracker's CoreIntegrationService fetches both at runtime — see US-ART-001.

5. Domain Events

  • ArtifactDefinitionSyncedEvent
  • ArtifactInstanceSubmittedEvent
  • ArtifactValidatedEvent / ArtifactValidationFailedEvent
  • EvidenceCapturedEvent
  • ArtifactSupersededEvent