Component Map¶

Status¶

Reference Architecture Document

Purpose¶

This document provides the official high-level map of the logical components of CMonChoix Platform.

It helps readers understand responsibility ownership, collaboration directions and the separation between read paths, write paths and runtime orchestration.

It does not replace the normative dependency contract in dependances.md.

Scope¶

This map covers logical Platform components and their main collaboration directions.

It does not define:

physical directories;
deployment topology;
container boundaries;
runtime scheduling;
SQL schemas;
WordPress bootstrap order.

Global View¶

                              Platform
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        │                         │                         │
    Contracts                Domain Core             Infrastructure
        │                         │                         │
        │                  Vertical Modules                │
        │                         │                         │
        ├───────────────┬─────────┴─────────┬───────────────┤
        │               │                   │               │
  Read Services    Write Services       Pipeline        Adapters
        │               │                   │               │
        │               └──────────┬────────┘               │
        │                          │                        │
        │                       Runtime                     │
        │                          │                        │
        └─────────────────── Projections ───────────────────┘
                                   │
                               Frontend

The diagram expresses logical responsibilities, not implementation folders.

Component Responsibilities¶

Component	Primary responsibility
Contracts	Stable interfaces, DTOs, statuses and collaboration boundaries
Domain Core	Generic business concepts and deterministic business reasoning
Vertical Modules	Product-family-specific knowledge and policies
Read Services	Audits, diagnostics, simulations, comparisons and reports
Write Services	Explicit, auditable and controlled business-data mutations
Pipeline	Ingestion, normalization, enrichment and preparation of write inputs
Runtime	Operational orchestration of validated workflows
Infrastructure	Technical implementations such as persistence and external services
Adapters	Translation between external technologies and Platform operations
Projections	Prepared consumer-facing representations derived from authoritative data
Frontend	Rendering and interaction based only on prepared projections

Authorized Dependency Summary¶

Component	May depend on
Contracts	No implementation layer
Domain Core	Contracts
Vertical Modules	Domain Core, Contracts
Read Services	Domain Core, Contracts, Vertical Modules, read-only ports
Write Services	Domain Core, Contracts, Vertical Modules, persistence ports
Pipeline	Domain Core, Contracts, Vertical Modules, approved Write Services
Runtime	Application orchestration, Infrastructure and Adapters
Infrastructure	Contracts
Adapters	Contracts, Infrastructure and approved application facades
Projections	Authoritative resolved data and projection contracts
Frontend	Projections only

The complete normative rules remain defined in dependances.md.

Forbidden Dependency Summary¶

The following directions remain forbidden:

Domain Core → Frontend, Runtime, Pipeline, WordPress, SQL or merchant adapters;
Contracts → Infrastructure, Runtime, Adapters or implementation DTO namespaces;
Vertical Module → another Vertical Module;
Read Service → SQL mutation or Write Service execution;
Pipeline → Frontend;
Frontend → feeds, identity resolution, matching, Domain Core or Runtime;
Adapters → business truth or transport-specific peer adapters;
Runtime → new business rules.

No component may bypass an established contract to reach an implementation detail directly.

Main Write Flow¶

Merchant Feed / External Source
              │
              ▼
           Adapter
              │
              ▼
           Pipeline
              │
              ▼
   Domain + Vertical Rules
              │
              ▼
       Explicit Decision
              │
              ▼
        Write Service
              │
              ▼
         Persistence
              │
              ▼
         Projection
              │
              ▼
          Frontend

Writes are never implied by an audit or by a projection read.

Read and Audit Flow¶

Authoritative Data
        │
        ▼
   Read Service
        │
        ├── Audit
        ├── Simulation
        ├── Comparison
        ├── Validation report
        └── Operational diagnostics

Read Services remain non-destructive.

A result may expose statuses such as:

resolved;
unknown;
ambiguous;
conflict.

These statuses describe evidence and decision state. They do not authorize mutation by themselves.

Projection Flow¶

Canonical / Authoritative Data
              │
              ▼
      Projection Builder
              │
              ▼
      Projection Write Service
              │
              ▼
      Projection Persistence
              │
              ▼
     Frontend / API / Export

A projection is a derived view. It never becomes a second source of business truth.

Projection construction must remain deterministic and reproducible for identical inputs and configuration.

Media Quality Position¶

Media Quality is a quality capability applied to media evidence and prepared projection data.

Its default mode is audit-first:

Media Evidence
      │
      ▼
Media Quality Engine
      │
      ├── status
      ├── reason codes
      ├── evidence
      └── proposed action

The engine must not silently clear, replace or rewrite media fields.

Any approved correction must cross an explicit Write Service or certified projection-write boundary.

Runtime Position¶

Runtime coordinates validated components. It may:

schedule work;
invoke application services;
handle retries and locks;
collect metrics;
expose operational status.

Runtime must not:

redefine identity;
invent conflict rules;
recalculate business truth independently;
bypass Write Services;
turn an audit finding into an implicit mutation.

Migration Flow¶

Legacy Behavior
      │
      ▼
Evidence and Usage Audit
      │
      ▼
Boundary Classification
      │
      ▼
Canonical Replacement
      │
      ▼
Compatibility Wrapper, if required
      │
      ▼
Validation and Observation
      │
      ▼
Legacy Removal after proof of non-use

Legacy removal requires evidence. Folder age or apparent duplication is not sufficient proof.

Observability¶

Each operational component should expose enough information to answer:

what was processed;
which component made the decision;
which rule or version was used;
which status was produced;
why the result was produced;
whether a write occurred;
how to reproduce or roll back the operation.

Recommended shared dimensions include:

capability or vertical;
merchant or source;
run identifier;
contract or rule version;
status;
reason code;
processed, skipped, failed and changed counts.

Fundamental Invariants¶

The component map is valid only while these invariants remain true:

Business truth has one authoritative owner.
Read paths never mutate business data.
Write paths are explicit and auditable.
Domain Core remains independent from technical execution.
Vertical Modules remain isolated from one another.
Frontend consumes projections instead of reconstructing business logic.
Runtime orchestrates but does not decide business truth.
Projections are derived and reproducible.
Media Quality is non-destructive by default.
Dependency direction remains explicit and acyclic.

Decision¶

This map is the official orientation document for Platform components.

Any evolution must remain compatible with:

the normative dependency contract;
architecture invariants;
read/write separation;
deterministic projection behavior;
audit-first quality capabilities.

None currently.

Future Evolution¶

This component map may evolve when a new Platform component becomes a stable architectural concept.

Any addition must define responsibility ownership, authorized dependencies, read/write behavior, observability requirements and compatibility with existing invariants.