Apps Overview¶

Status¶

Normative Architecture Document

Purpose¶

This document defines the responsibility of Apps in CMonChoix Platform.

It formalizes a responsibility already present in the architecture boundary model: Apps are executable entry points.

Scope¶

This document applies to every executable entry point of CMonChoix Platform, including:

CLI commands;
HTTP entry points;
workers;
cron entry points;
operational commands.

It does not define Runtime internals, Infrastructure implementations, Adapter behavior, Domain rules, or deployment topology.

Core Definition¶

Apps are executable entry points located at the edge of the Platform.

They prepare and trigger execution without owning business logic.

An App exists to expose a Platform capability through an executable surface.

Main Responsibility¶

Apps are responsible for:

receiving an execution request from the outside world;
selecting the executable path to trigger;
preparing execution parameters;
invoking authorized Platform components;
returning or exposing an execution outcome;
keeping the entry point thin and explicit.

Apps must remain small.

An App is not a business component.

An App is not an Infrastructure implementation.

An App is not a Runtime engine.

What Apps May Do¶

Apps may:

call Application use cases;
call authorized Adapters;
expose CLI, HTTP, worker, cron, or operational entry points;
translate entry-point arguments into stable Application inputs;
trigger an execution flow;
present a technical execution result to the outside world.

What Apps Must Never Do¶

Apps must never:

define business rules;
enforce Domain invariants;
construct business truth;
normalize merchant data;
decide product identity;
build projections;
implement Infrastructure details;
call SQL directly;
call WordPress directly;
call Docker directly;
parse merchant-specific formats directly;
bypass Application use cases to mutate Domain state.

Authorized Dependencies¶

Apps may depend on:

Application;
Adapters.

This follows the certified boundary model.

Apps must not depend directly on:

Domain;
Knowledge;
Infrastructure;
Contracts;
Runtime;
SQL;
WordPress;
Docker.

Relationship with Application¶

Application owns use case coordination.

Apps may invoke Application use cases, but they do not own the use case logic.

Apps translate external execution intent into Application-level invocation.

Application remains responsible for orchestrating Domain objects and stable contracts.

Relationship with Adapters¶

Adapters isolate external technologies.

Apps may call Adapters when an executable entry point needs an external-facing bridge.

Adapters must not introduce business logic.

Apps must not use Adapters to bypass Application use cases.

Relationship with Runtime¶

Runtime owns operational orchestration.

Apps are executable entry points.

Runtime may invoke Application use cases through Apps or executable entry points when an operational flow requires it.

Apps do not define Runtime behavior.

Runtime does not transfer business responsibility to Apps.

Relationship with Infrastructure¶

Infrastructure owns technical implementations.

Apps must not depend directly on Infrastructure.

When an App needs technical behavior, that behavior must be exposed through authorized Adapters or through an Application use case using stable contracts.

Object Graph and Dependency Creation¶

The current Platform architecture does not assign Apps a general responsibility to build the full object graph.

Apps may perform minimal local wiring required by a concrete executable entry point only when that wiring does not introduce business rules, Infrastructure ownership, or hidden dependencies.

A broader composition responsibility must not be introduced unless a dedicated audit demonstrates that it is necessary.

Execution Cycle¶

A compliant App follows this execution cycle:

receive an external execution request;
validate only entry-point-level parameters;
translate parameters into stable Application inputs;
invoke an authorized Application use case or Adapter;
expose the execution outcome;
stop without owning long-lived business state.

Examples¶

Examples of Apps:

a CLI command that triggers a feed intake use case;
an HTTP endpoint that triggers a read use case;
a worker entry point that starts a scheduled execution;
a cron command that delegates to Runtime or Application through an authorized path;
an operational command that exposes a controlled Platform action.

These examples describe entry-point surfaces, not business responsibilities.

Business Capability Progression¶

This document defines the architectural pattern of executable Apps.

It does not define the implementation order of Business Capabilities.

A concrete App may be implemented when:

the corresponding Business Capability has been certified;
its responsibilities are documented;
its dependencies comply with the Platform boundary model.

The examples presented in this document illustrate authorized executable entry points.

They do not establish a mandatory implementation sequence between Feed, Read, Write, Worker, Cron, HTTP or Operational Apps.

Implementation priorities are decided by dedicated Business Capability certification, not by this document.

Invariants¶

Apps are executable entry points.
Apps remain thin.
Apps do not own business logic.
Apps do not own Infrastructure implementations.
Apps do not own Domain invariants.
Apps do not bypass Application use cases.
Apps depend only on authorized layers.
Apps must remain replaceable by another executable surface.

Review Rules¶

An App is compliant only if:

it has a clear executable purpose;
it does not contain business logic;
it does not import Domain directly;
it does not import Infrastructure directly;
it does not import Runtime directly;
it invokes only authorized Application or Adapter components;
it keeps entry-point concerns separate from use case orchestration.

Architecture Decision¶

Decision: FOUNDATION

Apps are now explicitly defined as executable entry points of CMonChoix Platform.

They prepare and trigger execution at the edge of the system without owning business logic, Infrastructure implementation, Runtime behavior, or Domain invariants.