Skip to content

ddd-model.md

Latest commit

 

History

History
175 lines (147 loc) · 6.92 KB

ddd-model.md

File metadata and controls

175 lines (147 loc) · 6.92 KB

Evolith Tracker: DDD Model - Integration Module

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

This document defines the tactical and strategic design for the Integration Bounded Context. It is a supporting subdomain that acts as the system-wide Anti-Corruption Layer (ACL): it ingests data from external systems (GitHub, GitLab, Jira, Trello, .harness) and exports Tracker artifacts outward, translating every external shape into canonical domain events — so no external type ever penetrates a core context. Aggregate sources: TAD §3. Strategic relationships: Bounded Context Map.

1. Ubiquitous Language

  • Integration Endpoint: A configured connection to an external system for a tenant (provider, credentials ref, direction, scope).
  • ACL Adapter: The translator that maps an external payload into a canonical Tracker domain event (and vice versa for export).
  • Sync Record: An immutable trace of a single inbound/outbound synchronization, including the canonical result and idempotency key.
  • Canonical Event: The Tracker-internal domain event produced from an external payload (e.g., CodeCommittedEvent from a GitHub webhook).
  • Egress / Ingress: The direction of data flow relative to the Tracker.

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: Integration Core (Aggregates and Entities)

classDiagram
    class IntegrationEndpoint {
        <<Aggregate Root>>
        +UUID id
        +String tenantId
        +ExternalProvider provider
        +SyncDirection direction
        +String credentialsRef
        +EndpointStatus status
        +configure(UUID umsUserId)
        +enable()
        +disable()
        +rotateCredentials(String newRef)
    }

    class SyncRecord {
        <<Aggregate Root>>
        +UUID id
        +String tenantId
        +UUID integrationEndpointId
        +SyncDirection direction
        +String idempotencyKey
        +SyncStatus status
        +String canonicalEventType
        +Date syncedAt
        +record(UUID umsUserId)
        +markFailed(String reason)
    }

    class ACLAdapter {
        <<Entity>>
        +ExternalProvider provider
        +String adapterVersion
        +ingest(ExternalPayload) CanonicalEvent
        +export(CanonicalArtifact) ExternalPayload
    }

    IntegrationEndpoint "1" *-- "1" ACLAdapter : uses
    IntegrationEndpoint "1" --> "0..*" SyncRecord : produces
Loading

2.2. View 2: Translation & Audit (Value Objects)

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

    class WebhookSignature {
        <<Value Object>>
        +String algorithm
        +String signature
        +Boolean verified
    }

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

    class IntegrationEndpoint {
        <<Aggregate Root>>
    }
    class SyncRecord {
        <<Aggregate Root>>
    }

    SyncRecord "1" *-- "0..1" WebhookSignature : verified by
    SyncRecord "1" *-- "1" ExternalReference : links to
    SyncRecord "1" *-- "1" AuditControl : tracked by
    IntegrationEndpoint "1" *-- "1" AuditControl : tracked by
Loading

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

classDiagram
    class IntegrationFabric {
        <<Shared Kernel Shell>>
        +ingestFromWebhook()
        +exportToExternalSystem()
    }
    class EventBusShell {
        <<Shared Kernel Shell>>
        +publish(CanonicalEvent)
    }
    class UMS_SDK {
        <<Cross-Cutting>>
        +RequiresDomainAccess()
    }

    class IntegrationEndpoint {
        <<Aggregate Root>>
    }
    class ACLAdapter {
        <<Entity>>
    }

    ACLAdapter ..> IntegrationFabric : delegates transport
    ACLAdapter ..> EventBusShell : publishes canonical events
    IntegrationEndpoint ..> UMS_SDK : secured via
Loading

3. Tactical Design

3.1. Aggregate Roots (Small Aggregates)

  1. IntegrationEndpoint: Per-tenant external connection config. Credentials are held by reference only (the secret lives in the secret manager — Security Spec §8), never inline.
  2. SyncRecord: Immutable, idempotent trace of one sync. The idempotencyKey guarantees at-least-once inbound delivery does not double-apply (aligns with TAD §13.1 consumer-idempotency rule).

3.2. Entities & Value Objects

  • ACLAdapter (Entity): The provider-specific translator; versioned so a provider format change is an adapter-version bump, not a domain change.
  • ExternalReference (VO): Shared with Discovery, Construction, QA (Shared Kernel) — the canonical link to an external object.
  • WebhookSignature (VO): HMAC verification of inbound webhooks (Security Spec SEC-D4 ⊕ proposal) — guards against payload forgery (STRIDE Tampering).

3.3. Anti-Corruption Layer Discipline

  • No external type crosses the boundary. Every inbound payload becomes a canonical DomainEvent; every export starts from a canonical artifact. Core contexts never import GitHub/Jira types. This is the system's primary ACL, complementing the UmsSecurityAdapter ACL for auth.

3.4. Direction & Idempotency

  • Ingress: webhook/CSV → verified → normalized → canonical event published on the bus.
  • Egress: canonical artifact → adapter → external API (Standalone Mode export).
  • Both directions persist a SyncRecord with an idempotency key.

4. Context Mapping (Boundary Integration)

  • Anti-Corruption Layer (upstream of Discovery): ingests external initiatives → InitiativeImport.
  • Anti-Corruption Layer (peer of Construction): GitHub/GitLab PR & commit webhooks → CodeCommittedEvent, PeerReviewUpdatedEvent.
  • Bridges .harness ↔ QA: relays CI/test payloads (the QA context owns the .harness result contract; Integration handles transport).
  • Conformist to external providers: adapts to their formats; never asks them to change.

5. Domain Events

  • IntegrationEndpointConfiguredEvent
  • InboundSyncReceivedEvent
  • OutboundSyncCompletedEvent
  • SyncFailedEvent
  • WebhookRejectedEvent (signature verification failure)
  • ExternalCheckpointRegisteredEvent (initiative-only checkpoint advancement)