Skip to content

ddd-model.md

Latest commit

 

History

History
254 lines (216 loc) · 9.39 KB

ddd-model.md

File metadata and controls

254 lines (216 loc) · 9.39 KB

DDD Model - Construction Module

Bilingual Navigation: English (this document) · Versión en Español Required Phase: Phase 3 — Construction Primary Audience: Software Architects, Developers, AI Agents

1. Ubiquitous Language

Strict terminology shared between business and technical domains within this context:

  • Implementation Cycle: The transactional container for a time-boxed development effort (equivalent to a Sprint or Milestone).
  • Technical Story: An atomic execution unit taken by developers or AI Agents. It originates from an approved User Story, Technical Contract, or initiative checkpoint (in initiative-only mode).
  • Code Branch: Logical reference to the physical branch in the Git repository (e.g., GitHub/GitLab).
  • Peer Review: Formal code review checkpoint, populated asynchronously via webhooks (e.g., a Pull Request).
  • Construction Gate: Formal criteria or "Definition of Done" ensuring all code is peer-reviewed and covered before transitioning to QA.
  • Backlog Refinement Lock: Exclusive lock acquired during backlog refinement sessions to prevent concurrent edits. Released after commit or 30min inactivity timeout. Applicable only in generate mode. In initiative-only mode, no refinement lock is needed — checkpoint ordering is managed at the initiative level.

2. Conceptual Maps and Aggregates (Mermaid)

2.0. Visual Legends and Glossary

Symbol/Stereotype Meaning
<<Aggregate Root>> Transactional root entity. Governs the persistence and consistency of its internal entities.
<<Entity>> Domain object with a unique identity, dependent on its Aggregate Root.
<<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.

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

classDiagram
    class ImplementationCycle {
        <<Aggregate Root>>
        +UUID id
        +UUID blueprintId
        +String tenantId
        +String name
        +String sprintGoal
        +Date startDate
        +Date endDate
        +Int totalCapacityHours
        +Int completedPoints
        +CycleStatus status
        +List~UUID~ technicalStoryIds
        +List~ExternalReference~ externalRefs
        +startCycle(UUID umsUserId)
        +freezeCode(UUID umsUserId)
        +updateSchedule(Date start, Date end, UUID umsUserId)
        +recalculateMetrics()
        +closeCycle(ConstructionGate, UUID umsUserId)
    }

    class TechnicalStory {
        <<Aggregate Root>>
        +UUID id
        +UUID cycleId
        +UUID parentSourceId
        +StoryStatus status
        +UUID peerReviewId
        +UUID developerId_umsUserId
        +Int complexity
        +Int estimatedHours
        +Int loggedHours
        +List~String~ labels
        +List~ExternalReference~ externalRefs
        +assignDeveloper(UUID umsUserId)
        +logTime(Int hours, UUID umsUserId)
        +updateProgress(UUID umsUserId)
        +linkBranch(CodeBranch)
        +submitForReview(UUID umsUserId)
        +markAsDone(UUID umsUserId)
        +reopen(String reason, UUID umsUserId)
        +revertStatus(StoryStatus previousStatus, String reason, UUID umsUserId)
    }

    class CodeBranch {
        <<Value Object>>
        +String repositoryUrl
        +String branchName
        +String latestCommitHash
    }

    class PeerReview {
        <<Aggregate Root>>
        +UUID id
        +UUID technicalStoryId
        +String externalId
        +ReviewStatus reviewStatus
        +String pullRequestUrl
        +String sourceBranch
        +String targetBranch
        +String ciPipelineStatus
        +Boolean mergeConflict
        +List~ExternalReference~ externalRefs
        +updateCiStatus(String status)
        +flagConflict()
        +registerReviewDecision(ReviewerDecision)
    }

    class ReviewerDecision {
        <<Value Object>>
        +String reviewerId_umsUserId
        +String comment
        +Date approvedAt
    }

    class ExternalReference {
        <<Value Object>>
        +ExternalSystem system
        +String externalId
        +String url
        +ReferenceType type
        +String label
        +Date linkedAt
        +Map metadata
    }

    ImplementationCycle "1" --> "0..*" TechnicalStory : orchestrates
    TechnicalStory "1" *-- "0..1" CodeBranch : mapped to
    TechnicalStory "1" --> "0..1" PeerReview : referenced by
    PeerReview "1" *-- "0..*" ReviewerDecision : contains
    ImplementationCycle "1" *-- "0..*" ExternalReference : mapped to
    TechnicalStory "1" *-- "0..*" ExternalReference : mapped to
    PeerReview "1" *-- "0..*" ExternalReference : mapped to
Loading

2.2. View 2: Workflow and Audit Components

classDiagram
    class RequirementChecklist {
        <<Value Object>>
        +List~RequirementItem~ items
        +isReadyForApproval() Boolean
    }

    class RequirementItem {
        <<Value Object>>
        +String code
        +Boolean isMandatory
        +RequirementStatus status
    }

    class StateTransition {
        <<Value Object>>
        +CycleStatus fromState
        +CycleStatus toState
        +Date transitionDate
        +String triggeredBy
    }

    class ConstructionGate {
        <<Value Object>>
        +String techLeadId
        +GateDecision decision
        +Date decidedAt
    }

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

    class RefinementLock {
        <<Value Object>>
        +UUID backlogId
        +UUID acquiredBy_umsUserId
        +Date acquiredAt
        +Date expiresAt
        +Boolean isReleased
        +release()
        +isExpired() Boolean
    }

    class ImplementationCycle {
        <<Aggregate Root>>
    }

    class TechnicalStory {
        <<Aggregate Root>>
    }

    ImplementationCycle "1" *-- "1" RequirementChecklist : validates against
    RequirementChecklist "1" *-- "1..*" RequirementItem : contains
    ImplementationCycle "1" *-- "1" AuditControl : tracked by
    ImplementationCycle "1" *-- "0..*" StateTransition : workflow history
    ImplementationCycle "1" *-- "0..1" ConstructionGate : governed by
    TechnicalStory "1" *-- "1" AuditControl : tracked by
    ImplementationCycle "1" *-- "0..1" RefinementLock : locked by
Loading

RefinementLock Mode Note: Applicable only in generate mode. In initiative-only mode, no refinement lock is needed — checkpoint ordering is managed at the initiative level.

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

classDiagram
    class WorkflowEngine {
        <<Shared Kernel Shell>>
        +validateTransition()
        +evaluateApprovalGate()
    }

    class TenantConfigShell {
        <<Shared Kernel Shell>>
        +getTenantWorkflowRules()
    }

    class IntegrationFabric {
        <<Shared Kernel Shell>>
        +listenToGithubWebhooks()
        +listenToGitlabWebhooks()
    }

    class UMS_SDK {
        <<Cross-Cutting>>
        +RequiresDomainAccess()
    }

    class PeerReview {
        <<Aggregate Root>>
    }

    class ImplementationCycle {
        <<Aggregate Root>>
    }

    ImplementationCycle ..> TenantConfigShell : reads optional rules
    ImplementationCycle ..> WorkflowEngine : delegates state logic
    ImplementationCycle ..> UMS_SDK : secured via
    PeerReview ..> IntegrationFabric : asynchronously hydrated by
Loading

3. Tactical Design

3.1. Aggregate Roots (Small Aggregates)

The module employs the Small Aggregates pattern stipulated by Evolith's corporate rules (R-21) to maximize performance and prevent optimistic concurrency lock-outs:

  1. ImplementationCycle: Does not physically nest stories; instead, it tracks them via a List<UUID> technicalStoryIds.
  2. TechnicalStory: Isolated atomic task worked on by a single developer or AI agent.
  3. PeerReview: Elevated to an independent Aggregate Root. This ensures external webhooks from Git repositories (via the IntegrationFabric) can impact its state asynchronously without locking heavy transactions on the ImplementationCycle or the TechnicalStory.

3.2. Value Objects

  • RequirementChecklist: (Corporate rule R-22). Validates dynamic workflows injected by Tenant configuration natively at the domain level.
  • CodeBranch: Immutable object that explicitly defines the repository and branch of the work.
  • RefinementLock: Value Object for exclusive backlog refinement sessions (US-CON-012). Acquired on session start, released on commit or 30min inactivity expiry. Applicable only in generate mode. In initiative-only mode, no refinement lock is needed — checkpoint ordering is managed at the initiative level.

3.3. External Integration & Webhooks (R-20)

Unlike previous phases, Construction relies heavily on real-world Git operations. The IntegrationFabric plays a pivotal role, capturing GitHub, GitLab, or Bitbucket webhooks and translating them into domain commands (e.g., UpdatePeerReviewCommand) that hydrate local PeerReview aggregates.