Architecture Overview¶

Status¶

Informational architecture entry point.

Purpose¶

This document is the primary navigation page for the CMonChoix Platform architecture.

It explains:

which documents are normative;
how responsibilities are separated;
where runtime, pipeline, projection, quality and vertical rules belong;
which reading path to follow before changing production code.

This page does not replace the normative contracts. It points to them.

Scope¶

The architecture documentation covers:

Platform Vision;
Architecture Principles;
Architecture Invariants;
Architecture Dependencies;
Boundary Architecture;
Identifier First;
Canonical Identity;
Domain Core;
Vertical Modules;
Read Services;
Write Services;
Pipeline;
Runtime;
Projection;
Media Quality;
Governance and operations.

Normative hierarchy¶

Documentation is interpreted in the following order:

Architecture invariants
        ↓
Dependency and boundary contracts
        ↓
Domain and service contracts
        ↓
Runtime and operational documentation
        ↓
Implementation notes and historical reports

When two documents disagree, the most fundamental and most recently certified contract takes precedence.

Historical certification notes describe how a boundary was reached. They do not override the current consolidated architecture.

Responsibility map¶

External sources
      ↓
Pipeline
      ↓
Domain Core + Vertical Modules
      ↓
Canonical Identity / normalized evidence
      ↓
Projection Builder
      ↓
Write Service
      ↓
Certified projection storage
      ↓
Frontend / API / exports / audits

Supporting responsibilities:

Read Services  → audit, simulation, comparison, validation
Runtime        → orchestration and execution
Infrastructure → technical implementations
Adapters       → translation of external interactions
Contracts      → stable interfaces and result shapes

Fundamental boundaries¶

Domain Core¶

Owns generic business concepts and deterministic decision mechanisms.

It must not depend on:

WordPress;
SQL implementations;
feeds;
frontend code;
runtime orchestration;
vertical-specific rules.

Vertical Modules¶

Own business knowledge specific to one product family.

A vertical may extend generic behavior through contracts but must not modify the Domain Core or depend on another vertical.

Read Services¶

Own audits, simulations, diagnostics and validation reports.

They are strictly read-only. No implicit repair or production mutation belongs in a Read Service.

Write Services¶

Own explicit, controlled and auditable business writes.

Legacy writers may remain behind this boundary as technical persistence details during migration.

Pipeline¶

Owns ingestion, normalization, enrichment and preparation of evidence.

It must not depend on the Frontend or redefine canonical business truth locally.

Runtime¶

Owns orchestration, scheduling, workers and execution context.

Runtime code may execute use cases but must not invent business rules.

Frontend¶

Consumes prepared projections.

It must not resolve identities, normalize feeds, calculate canonical quality truth or write business data directly.

Canonical result states¶

Decision-producing components should expose stable states rather than implicit booleans.

The common semantic vocabulary is:

State	Meaning
`resolved`	A deterministic result is supported by sufficient evidence
`unknown`	Evidence is absent or insufficient
`ambiguous`	Several plausible outcomes remain
`conflict`	Incompatible evidence prevents a safe decision

Each decision should expose reason codes and audit metadata whenever practical.

Absence of proof must never be silently converted into a positive match.

Read before write¶

Every significant correction follows this sequence:

Audit
  ↓
Simulation
  ↓
Comparison
  ↓
Validation
  ↓
Explicit write
  ↓
Post-write verification

This rule applies to projection rebuilds, identity corrections, governance changes and Media Quality operations.

Media Quality position¶

Media Quality is an evidence-evaluation capability, not an implicit destructive cleanup step.

Its default behavior is audit-first:

inspect the current main image;
compare it with normalized product evidence;
produce a stable status and reason code;
report a candidate replacement when one is proven;
avoid mutation unless an explicit write path is requested and certified.

A missing replacement is not permission to clear an existing image.

The canonical documentation is Media Quality Engine.

Determinism and reproducibility¶

The Platform expects identical validated inputs and configuration to produce identical business decisions and projections.

Every critical component should therefore make explicit:

input version;
ruleset or contract version;
result status;
reason codes;
execution metadata;
write scope, when a mutation occurs.

Time, network state and merchant ordering must not silently change a canonical decision unless they are explicit inputs.

Current migration model¶

The Platform evolves progressively.

The active strategy is:

identify an existing responsibility;
define or certify its boundary;
introduce a canonical contract or service;
keep compatibility wrappers only when necessary;
move consumers incrementally;
remove legacy code only after runtime evidence and certification.

Compatibility code is temporary infrastructure, not a second source of business truth.

Change checklist¶

Before introducing an architectural change, verify:

the owning layer is explicit;
dependency direction remains authorized;
generic and vertical knowledge remain separated;
reads and writes are not mixed;
result states are deterministic and auditable;
production mutation is explicit;
runtime entrypoints use certified services;
documentation and tests are updated together;
legacy compatibility does not become a parallel implementation.

None currently.

Future Evolution¶

This overview may evolve when a new document becomes a normative entry point. New sections must preserve the dependency rules, the read-before-write discipline and the single-source-of-truth principle.