Aller au contenu

Application Infrastructure Contract

Status

Normative Architecture Contract

Purpose

This document defines the collaboration contract between the Application layer and the Infrastructure layer.

It makes explicit a boundary that was previously only implicit in the architecture documentation.

Scope

This contract applies to every Business Capability of CMonChoix Platform.

It applies before any infrastructure adapter, persistence implementation, merchant connector, runtime worker or executable entry point is introduced.

Core Rule

The Application layer does not depend directly on Infrastructure.

The Application layer depends only on stable contracts that express the needs of a use case.

The Infrastructure layer implements these contracts.

Allowed Direction

Application
        │
        ▼
Contracts
        ▲
        │
Infrastructure

The Application owns use case orchestration.

Infrastructure owns technical implementation.

Contracts define the collaboration boundary.

Application Responsibilities

Application is responsible for:

  • orchestrating use cases;
  • coordinating Domain objects;
  • invoking stable contracts;
  • returning explicit use case outcomes;
  • keeping technical details outside the use case.

Application must not:

  • call SQL directly;
  • call WordPress directly;
  • call Docker directly;
  • read files directly;
  • parse merchant-specific formats directly;
  • call external partner APIs directly;
  • depend on infrastructure classes;
  • depend on adapter classes;
  • define infrastructure behavior.

Infrastructure Responsibilities

Infrastructure is responsible for:

  • implementing stable contracts;
  • reading external resources;
  • writing to technical storage;
  • translating technical protocols;
  • isolating external systems;
  • preserving replaceability of technical implementations.

Infrastructure must not:

  • define business truth;
  • own Domain invariants;
  • orchestrate use cases;
  • decide product identity;
  • normalize products;
  • build projections;
  • leak technical details into Application.

Contracts Responsibilities

Contracts are responsible for defining stable collaboration boundaries.

A contract may define:

  • an interface required by a use case;
  • a stable input boundary;
  • a stable output boundary;
  • a technical-agnostic data shape.

A contract must not define:

  • SQL schemas;
  • WordPress behavior;
  • Docker behavior;
  • Awin-specific behavior;
  • CSV-specific behavior;
  • HTTP-specific behavior;
  • runtime execution details.

Data Crossing the Boundary

Data crossing the Application-Infrastructure boundary must be stable and technology-agnostic.

It must not expose:

  • CSV rows as the architectural contract;
  • XML nodes as the architectural contract;
  • HTTP responses as the architectural contract;
  • SQL records as the architectural contract;
  • WordPress objects as the architectural contract;
  • merchant-specific SDK objects as the architectural contract.

Technical formats may exist inside Infrastructure or Adapters, but they must be translated before crossing the boundary.

Domain Object Construction

Infrastructure must not be responsible for assembling Domain Entities.

Domain objects are constructed by Application orchestration using Domain factories and constructors.

Infrastructure provides the stable data required by the contract.

Domain enforces invariants.

Application coordinates the assembly.

Port Ownership

Use case ports belong to the Application boundary.

Infrastructure implementations satisfy those ports.

Domain does not own infrastructure ports unless a dedicated audit proves that the port is part of Domain reasoning.

Adapter Relationship

Adapters isolate external technologies.

Adapters may depend on Infrastructure and Contracts.

Adapters must not bypass Application use cases to mutate Domain state.

Adapters must not introduce business rules.

Runtime Relationship

Runtime may orchestrate execution.

Runtime may invoke Application use cases through Apps or executable entry points.

Runtime must not define business rules, Domain invariants, or infrastructure contracts.

Merchant Feed Intake Consequence

For Merchant Feed Intake:

  • Application owns the use case boundary;
  • Infrastructure must not return a fully assembled MerchantFeedPublication unless a contract explicitly requires it;
  • Infrastructure must not expose CSV, XML, HTTP, Awin or SQL details to Application;
  • Application must assemble Domain objects from stable contract data;
  • Stage writing must occur through a stable contract, not through direct SQL access.

Review Rules

A new Infrastructure implementation is compliant only if:

  • Application does not import Infrastructure classes;
  • Application depends only on Domain and Contracts;
  • Infrastructure implements a documented contract;
  • technical formats remain below the boundary;
  • Domain invariants remain inside Domain;
  • use case orchestration remains inside Application.

Architecture Decision

Decision: FOUNDATION

The Application-Infrastructure collaboration boundary is now explicit and normative.

All future Business Capabilities must respect this contract unless an audit demonstrates an objective exception.