Techcle Wiki

Initial Thoughts

5 min read

Platform Domain API + Event Strategy Integration Platform Architecture Position Status: Draft v1.0 Audience: Architecture, Platform Engineering, Integration Engineering, Product Owner: Platform Architecture

  1. Purpose This document defines the strategy for: Designing Domain APIs that span multiple backend systems Managing distributed ownership of data at field level Orchestrating cross-system workflows Emitting reliable, business-meaningful domain events Establishing the platform as the semantic authority The objective is to enable scalable, predictable, and evolvable integrations across modern, SaaS, custom, and legacy systems.
  2. Context The platform integrates heterogeneous backend systems with: Independent data models Inconsistent lifecycle semantics Varying reliability Partial functional overlap Backend systems do not align with business domains. As a result: Platform domains are synthetic constructs Domain resources span multiple systems No single backend represents the complete business truth Therefore, business semantics must be owned and managed at the platform layer.
  3. Architectural Position 3.1 Platform as Semantic Authority The platform operates as a virtual system of record. While physical data remains in backend systems, the platform owns: Canonical models Lifecycle definitions Field-level authority Reconciliation rules Event semantics Backends are treated as authoritative only for explicitly delegated fields. 3.2 Separation of Concerns Layer Responsibility Backend Systems Physical persistence, local transactions Connectors Protocol adaptation, ingestion, normalization Domain Layer Canonical state, orchestration, semantics Event Layer Domain event publication Consumers Business workflows, analytics, automation Only the Domain Layer may express business truth.
  4. Domain API Model 4.1 Domains Domains represent business capabilities, not systems. Examples: Customer Management Billing Order Fulfillment Case Management Each domain is a bounded context with: Defined ownership Canonical vocabulary Lifecycle governance 4.2 Resources Resources are canonical business entities. Example: Customer Invoice Order Case Resources may be composed from multiple backends. Each resource definition includes: Identity model Lifecycle states Mutability rules Authority mapping Sync/async semantics 4.3 Field-Level Authority Data ownership is defined per field. Example: Customer: email: authority: MarketingPlatform creditScore: authority: RiskEngine legalName: authority: CRM This governs: Write routing Conflict resolution Event emission Validation No resource is assumed to have a single system of record. 4.4 Commands Commands represent business intent. Examples: ApproveInvoice SuspendCustomer MergeAccounts Commands: Are idempotent May be asynchronous Are processed via orchestration Support compensation API Pattern: POST /v1/{domain}/{resource}/{id}/commands
  5. Orchestration and Sagas 5.1 Role of Orchestration All multi-system writes are coordinated through sagas. Responsibilities: Step sequencing Retry policies Compensation Timeout handling State tracking Sagas implement domain workflows. 5.2 Write Path All write operations follow: API Command → Saga → Backend Updates → Reconciliation → Domain State Update → Domain Event No backend is updated directly by consumers.
  6. Domain State Management 6.1 Canonical State Store The platform maintains a domain state store containing: Canonical entity snapshots Field provenance Last-updated timestamps Confidence indicators (optional) This supports: Event emission Read APIs Auditing Recovery 6.2 Provenance Each field records its origin: “email”: { “value”: “a@b.com”, “source”: “crm”, “updatedAt”: “2026-01-10” } Provenance is optional in external APIs but mandatory internally. 6.3 Reconciliation Background processes reconcile domain state with sources: Periodic refresh Drift detection Repair workflows This maintains long-term consistency.
  7. Event Strategy 7.1 Event Ownership Only the Domain Layer emits Domain Events. Backend systems emit Integration Signals. These are distinct. Type Producer Consumer Integration Signal Backend Platform Domain Event Platform External Consumers 7.2 Why Domain Events Are Platform-Owned Backend events are: Partial Vendor-specific Uncorrelated Semantically incomplete Only the platform can: Aggregate changes Apply authority rules Resolve conflicts Interpret lifecycle meaning Therefore, domain events must originate in the platform. 7.3 Event Emission Rule A domain event is emitted when: The effective canonical state changes. Not when a backend changes. Example: Multiple backend updates → no canonical change → no event. 7.4 Event Reliability (Internal Outbox) All domain events are published via an internal outbox. Pattern: State Update + Outbox Write (Atomic) → Publisher → Broker / Webhooks This guarantees: No lost events Replayability Consistency
  8. External Event Ingestion 8.1 Ingress Journal All external events are journaled before processing. Receive → Persist → Acknowledge → Process Benefits: Replay Audit Recovery Forensics 8.2 Inbox / Deduplication Deduplication keys: Source Vendor Event ID Hash fallback Prevents duplicate processing. 8.3 Normalization External signals are transformed into canonical internal events before use. Consumers never see raw vendor payloads.
  9. Event Types 9.1 Domain Events Business-level events: CustomerActivated InvoicePaid OrderCancelled Properties: Versioned Immutable At-least-once delivery Correlated 9.2 Integration Events Raw system events. Used only for: Debugging Replay Reconciliation Not exposed externally.
  10. API and Event Versioning 10.1 APIs Major version in URL Additive changes only Deprecation policy 10.2 Events Schema versioning Backward-compatible evolution Parallel streams if needed
  11. Governance Model 11.1 Domain Ownership Each domain has: Business owner Technical owner Change authority 11.2 Change Management All changes to: Domains Resources Core fields Events Require lightweight RFC review. 11.3 Registry A central registry stores: Domain definitions Schemas Authority mappings Event catalogs Owners
  12. Operational Guarantees The platform commits to: At-least-once domain event delivery Idempotent command handling Replay capability End-to-end correlation Auditable state changes
  13. Target Maturity Model Phase 1: Foundation Canonical models Orchestration framework Outbox/inbox Basic registry Phase 2: Scale Full provenance Automated reconciliation Contract testing SDKs Phase 3: Optimization Predictive recovery Auto-mapping Intelligent routing Self-healing workflows
  14. Summary Principles Domains are platform constructs Resources span systems Authority is field-level Writes are orchestrated Domain events are platform-owned External events are signals Reliability is enforced at boundaries Semantics are centralized
  15. Key Position Statement The integration platform is the authoritative interpreter of business truth. Backend systems provide data. The platform provides meaning. All Domain APIs and events must conform to this principle.

Graph View