Boundary Architecture¶
Status¶
Normative Architecture Boundary Contract
Purpose¶
This document defines the logical boundaries between CMonChoix Platform layers.
It answers one question:
Which layer owns a responsibility, and which dependencies are allowed to cross that boundary?
The goal is to prevent circular dependencies, hidden coupling, technology leakage, accidental writes, and duplicated business truth.
Scope¶
This contract applies to:
- Domain Core;
- Contracts;
- Knowledge;
- Application;
- Infrastructure;
- Adapters;
- Apps;
- Runtime;
- Vertical Modules;
- Read Services;
- Write Services;
- Pipeline;
- Frontend;
- Projection;
- Media Quality.
It defines logical architecture boundaries, not deployment topology or physical folders.
Central Principle¶
Each responsibility has one owner.
A component may only collaborate with another layer through an explicit, documented boundary.
Physical proximity, historical convenience, or legacy availability never authorizes a dependency.
Responsibility Matrix¶
| Layer | Primary responsibility |
|---|---|
| Domain Core | Generic business concepts and deterministic business reasoning |
| Contracts | Stable input, output, status, reason-code, and collaboration shapes |
| Knowledge | Business meaning, taxonomies, and reference knowledge |
| Application | Use-case orchestration |
| Infrastructure | Technical implementations and persistence details |
| Adapters | Translation between external systems and Platform contracts |
| Apps | Executable entry points such as CLI, HTTP, workers, and cron |
| Runtime | Operational orchestration and execution |
| Vertical Modules | Product-family-specific rules and evidence interpretation |
| Read Services | Audits, simulations, comparisons, previews, and reports |
| Write Services | Explicit, auditable, controlled business-data mutation |
| Pipeline | Data transformation and enrichment flow |
| Projection | Consumer-oriented representations derived from business truth |
| Frontend | Projection consumption and presentation |
| Media Quality | Audit-first media evidence evaluation and reasoned quality decisions |
Authorized Dependency Direction¶
A dependency may point only toward a more fundamental layer or an explicitly authorized contract.
| Layer | May depend on |
|---|---|
| Domain Core | Internal contracts and language-level utilities |
| Contracts | No implementation details |
| Knowledge | Domain Core, Contracts |
| Application | Domain Core, Knowledge, Contracts |
| Infrastructure | Contracts |
| Vertical Modules | Domain Core, Contracts |
| Read Services | Domain Core, Contracts, Vertical Modules, read-only ports |
| Write Services | Domain Core, Contracts, Vertical Modules, explicit persistence ports |
| Pipeline | Domain Core, Contracts, Vertical Modules, approved services |
| Projection | Canonical business outputs, Contracts, approved read models |
| Adapters | Contracts, Infrastructure, Application facades |
| Apps | Application, Adapters |
| Runtime | Application, Infrastructure, Adapters, approved Write Services |
| Frontend | Prepared projections only |
The detailed dependency matrix remains defined in Architecture Dependencies.
Domain Boundary¶
The Domain Core owns generic business reasoning.
It never owns:
- WordPress integration;
- SQL or storage details;
- HTTP, CLI, cron, or worker execution;
- feed parsing;
- frontend rendering;
- runtime orchestration;
- merchant-specific behavior;
- product-family-specific rules.
A vertical-specific rule must remain outside the Domain Core unless reuse across multiple verticals is proven and formally extracted.
Contract Boundary¶
Contracts define stable collaboration shapes.
They may contain:
- DTOs;
- interfaces;
- normalized statuses;
- reason codes;
- evidence structures;
- compatibility rules;
- versioned result shapes.
They never contain:
- SQL;
- WordPress APIs;
- concrete adapters;
- runtime orchestration;
- heavy business logic;
- frontend behavior.
A compatibility wrapper may preserve a legacy name, but the canonical contract must remain implementation-neutral.
Vertical Boundary¶
Vertical Modules interpret product-family-specific evidence.
They may define:
- local attributes;
- domain-specific normalization;
- candidate evidence;
- conflict classification;
- scoring inputs;
- reason codes;
- family-specific guards.
They must never:
- depend on another vertical;
- write directly to production data;
- bypass the Resolver;
- redefine canonical statuses;
- own global projections;
- introduce frontend logic.
Read / Write Boundary¶
Read Services are strictly read-only.
They may audit, simulate, compare, preview, explain, and report. They must never perform INSERT, UPDATE, DELETE, implicit state mutation, or runtime writes.
Write Services are the only services allowed to mutate business data. Every write must be:
- explicit;
- authorized;
- auditable;
- measurable;
- bounded in scope;
- reversible whenever possible.
No audit result becomes a write merely because confidence appears high.
Projection Boundary¶
Projection transforms approved business truth into consumer-oriented representations.
Projection may format, select, aggregate, and expose data. It must never:
- resolve identity;
- hide
unknown,ambiguous, orconflictstates; - create a new identity;
- recalculate vertical policy;
- write directly to persistence without a Write Service boundary.
The Frontend consumes projections and does not reconstruct them from raw feeds or domain internals.
Runtime Boundary¶
Runtime orchestrates execution.
It may schedule, invoke, retry, monitor, and coordinate approved services. It must never:
- invent business rules;
- reinterpret canonical statuses;
- bypass contracts;
- call legacy SQL writers directly when a Write Service exists;
- turn an audit-only engine into an implicit mutation path.
Runtime behavior must remain observable through counters, structured outcomes, and stable error reporting.
Media Quality Boundary¶
Media Quality is audit-first.
Its default behavior is to evaluate evidence and return a deterministic result such as:
matched;mismatched;unknown;ambiguous;not_applicable.
The result must include stable reasons and enough evidence for audit.
Media Quality rules may detect a better candidate image or a conflict, but they must not silently replace, clear, or mutate production media fields. Any approved correction must cross an explicit Write Service or certified projection-write boundary.
Legacy image-quality code may remain during migration, but it must not become a second source of truth.
Frontend Boundary¶
The Frontend consumes prepared projections.
It must never depend directly on:
- feeds;
- Candidate;
- Resolver;
- Conflict Policy;
- raw matching logic;
- normalization engines;
- Runtime;
- Write Services;
- merchant persistence tables.
Presentation fallback behavior may improve readability, but it must not hide unresolved business states or manufacture missing truth.
Boundary Decision Test¶
Before introducing or moving code, answer these questions:
- Which layer owns this responsibility?
- Is the dependency direction authorized?
- Is there already a contract for the collaboration?
- Does the change mix read and write behavior?
- Does it introduce technical knowledge into Domain or Knowledge?
- Does it duplicate an existing business truth?
- Are
unknown,ambiguous, andconflictpreserved explicitly? - Is the behavior deterministic and observable?
- Could the same goal be reached through a narrower boundary?
If ownership or dependency direction remains unclear, the design is not ready.
Enforcement¶
Boundary rules should be enforced through:
- namespace and import checks;
- architecture tests;
- read-only SQL guards;
- contract tests;
- deterministic fixtures;
- CLI audit commands;
- projection and write-path integration tests;
- code review checklists;
- documented exceptions with an owner and removal plan.
A legacy exception is transitional debt, not a new architectural precedent.
Prohibited Practices¶
The following practices are forbidden:
- Domain Core depending on WordPress, SQL, Runtime, Frontend, or a Vertical Module;
- one Vertical Module depending on another;
- Read Services writing data;
- Frontend resolving identity or recomputing quality;
- Adapters defining business truth;
- Runtime bypassing Application or Write Service boundaries;
- Projection hiding conflict states;
- Contracts importing implementation namespaces;
- audit engines mutating production data implicitly;
- duplicate canonical writers for the same field.
Invariants¶
The following invariants must remain true:
- business truth has one authoritative owner;
- dependencies point inward or through explicit contracts;
- reads and writes remain separated;
- vertical rules remain isolated;
- unresolved states remain explicit;
- projections are derived, not authoritative identity sources;
- writes are explicit and auditable;
- Media Quality remains audit-first by default;
- legacy compatibility does not redefine target architecture.
Related Documents¶
- Platform Vision
- Architecture Overview
- Platform Blueprint
- Architecture Principles
- Architecture Invariants
- Architecture Dependencies
- Contracts
- Read Services
- Write Services
- Media Quality Engine
Related ADR¶
None currently.
Future Evolution¶
New layers or exceptions may be introduced only when ownership, dependency direction, observability, migration strategy, and compatibility impact are explicitly documented and tested.