Platform Blueprint¶

Status¶

Foundational Architecture Blueprint

Purpose¶

This document defines the target logical architecture of CMonChoix Platform.

It describes the architectural destination independently from the historical WordPress plugin, deployment topology and temporary compatibility layers.

Scope¶

This blueprint applies to the logical Platform architecture:

Contracts;
Domain Core;
Business Capabilities and Vertical Modules;
Read Services;
Write Services;
Pipeline;
Projection;
Runtime;
Adapters;
Infrastructure;
Governance;
Media Quality.

It does not define a physical directory layout, a deployment unit or a migration schedule.

Central Decision¶

The Platform architecture is defined independently from WordPress.

The canonical plugin at:

plugins/ccx-feeds-industrial

is the current production integration surface and an important source of business knowledge, but it does not define the target architecture.

Migrated, rewritten or newly created components must follow this blueprint while preserving validated runtime compatibility.

Target Model¶

External Sources
      │
      ▼
Adapters / Ingestion
      │
      ▼
Pipeline
      │
      ├── normalization
      ├── enrichment
      └── evidence collection
      │
      ▼
Domain Core + Vertical Knowledge
      │
      ├── candidates
      ├── resolution
      ├── canonical identity
      ├── conflicts
      └── quality decisions
      │
      ▼
Projection Builders
      │
      ▼
Write Services
      │
      ▼
Certified Projections
      │
      ├── Frontend
      ├── SEO
      ├── API
      ├── Export
      └── Read Services

The Runtime orchestrates this flow but never creates business truth.

Architecture Principles¶

Platform First¶

The Platform defines the architecture.

Legacy code can inform migration decisions but never defines the target boundaries.

Domain First¶

Business truth belongs to the Domain Core and specialized business capabilities.

The Domain Core must not depend on WordPress, frontend code, pipeline code, runtime code or concrete persistence.

Evidence First¶

Product identity and quality decisions are established from observable evidence.

Identifiers, titles, attributes, source context and media signals are evidence. None of them becomes canonical truth in isolation.

Identifier First¶

Available identifiers contribute to identity resolution:

EAN / GTIN;
merchant SKU;
manufacturer reference;
brand;
model;
technical attributes;
source trust signals.

EAN is a strong signal, not a universal authority.

Canonical Identity¶

Each resolved product owns one stable Canonical Identity.

Merchant data, variants and projections remain attached to that identity without redefining it.

Read / Write Separation¶

Read Services audit, simulate, compare and report.

They never mutate business data.

Write Services are the only authorized business mutation boundary. Every write must be explicit, auditable and reversible whenever possible.

Projection Separation¶

Projection Builders construct deterministic representations.

They do not persist data. Persistence is delegated to Write Services.

Business Capability First¶

Each business capability owns its specific rules.

Smartphone, Photo and future vertical knowledge must remain isolated from the generic Domain Core.

A capability must never depend on another capability.

Audit Before Mutation¶

Every significant change follows this sequence:

audit
  ↓
simulation
  ↓
comparison
  ↓
validation
  ↓
explicit write
  ↓
post-write verification

Production mutation is never the discovery mechanism.

Explicit Dependencies¶

Every dependency must be visible, justified and compatible with the dependency contract.

Hidden dependencies, circular dependencies and direct access to legacy writers are forbidden.

Determinism¶

Identical certified inputs and configuration must produce identical decisions and projections.

Results must expose stable statuses, reason codes and evidence suitable for audit.

Layer Responsibilities¶

Layer	Owns	Must not own
Contracts	Stable interfaces, DTOs, statuses and reason conventions	Business rules or technical execution
Domain Core	Generic business concepts and invariants	Vertical or transport-specific logic
Vertical Modules	Product-family knowledge and local conflict rules	Generic orchestration or cross-vertical dependencies
Pipeline	Transformation, normalization and evidence preparation	Canonical business truth
Read Services	Audit, simulation, comparison and reports	Writes
Projection Builders	Deterministic representations	Persistence or identity resolution
Write Services	Explicit business mutations	Frontend rendering or hidden rule evaluation
Runtime	Orchestration, retries, scheduling and execution context	New business rules
Adapters	Translation between external systems and Platform contracts	Business decisions
Infrastructure	Persistence and technical mechanisms	Use-case orchestration
Frontend	Consumption and display of certified projections	Identity, quality or feed recalculation

Result Model¶

Cross-layer decisions should use a stable result model containing, where relevant:

status;
reason code;
evidence;
confidence or severity;
source context;
rule and engine version;
audit metadata.

Canonical decision states include:

State	Meaning
`resolved`	Sufficient evidence supports one stable result
`unknown`	Evidence is insufficient
`ambiguous`	Several plausible outcomes remain
`conflict`	Incompatible evidence blocks a safe decision

Layers may expose more precise local sub-statuses, but they must map unambiguously to these canonical states.

Media Quality Position¶

Media Quality is a quality capability operating on projection-ready evidence.

Its default mode is audit-first and non-destructive:

projection evidence
      │
      ▼
media-quality engine
      │
      ├── matched
      ├── mismatched
      ├── unknown
      └── ambiguous
      │
      ▼
audit / simulation / report

A rule may recommend a replacement or cleanup action, but it must not directly mutate projection data.

Any applied correction must cross an explicit Write Service or certified rebuild path.

Runtime and Compatibility¶

The Runtime may compose Application, Infrastructure and Adapters to execute certified workflows.

Compatibility wrappers and shims may remain temporarily when they:

preserve existing runtime behavior;
expose no new business truth;
remain documented;
have a bounded migration purpose;
do not create new dependencies from foundational layers toward legacy code.

Legacy is removed only after proof of non-usage and post-removal validation.

Target Logical Structure¶

platform/
  contracts/
  domain-core/
  business-capabilities/
  vertical-modules/
  read-services/
  write-services/
  pipeline/
  projection/
  media-quality/
  runtime/
  adapters/
  infrastructure/
  governance/

This structure represents logical responsibilities, not necessarily physical directories.

Architectural Tests¶

The blueprint is expected to be enforced through tests and automated checks covering at least:

forbidden namespace dependencies;
Read Service write prohibition;
projection determinism;
stable result statuses and reason codes;
absence of frontend business recalculation;
explicit Write Service boundaries;
vertical isolation;
audit-first Media Quality behavior;
compatibility wrapper loading where still required.

Documentation alone is not sufficient evidence of compliance.

None currently.

Future Evolution¶

This blueprint may evolve when new architectural boundaries are validated by implementation, tests and operational evidence.

Any evolution must preserve dependency direction, audit-before-write behavior, deterministic results and the independence of business truth from technical adapters.