Architecture

Bounded candidate reference — 2026-10-20: 0.2.0-rc.1 is committed locally through 84f415b3098af5653577b2c65eea31fca21df79c, unpublished and not production-approved; stable PHP >=8.5.11 <8.6.0 is required. This is documentation, not adoption: this knowledge base retains its installed 0.1.0-rc.1 dependency and PHP 8.2.11 local profile. Dated PHP 8.2 evidence is historical; earlier dirty-source reports retain their original test provenance, not retroactive clean-commit proof. Candidate examples are illustrative: API signatures were reviewed, but candidate code was not executed by this editorial update. See current checkpoint, open criteria and adoption boundary.

Clean Framework keeps policy in applications and mechanics in small framework objects. Bootstrap composition creates every dependency explicitly; the kernel does not open a database, start a session, call a provider, or render a view unless a selected handler or middleware requires it.

Runtime and compatibility surfaces

Top-level src/ is the refactored neutral runtime used by the skeleton's default bootstrap.php. The separately versioned compatibility/prosperous-pairs-legacy package preserves the original Core and Services layers with their historical namespaces and behavior. Only that optional package classmaps the original Services directory.

The preserved layer is not installed or booted automatically by the neutral front controller. Existing applications may require it and migrate against it incrementally; new applications should prefer neutral Clean\Framework\ contracts. A preserved service can still require its original tables, feature codes, provider configuration, routes, or domain policy.

Request lifecycle

flowchart LR
    A[Apache public DocumentRoot] --> B[public/app.php]
    B --> C[EnvironmentSource and Config Loader]
    C --> D[Application composition]
    D --> E[Request from globals]
    E --> F[Kernel middleware]
    F --> G[Router match]
    G --> H[Route middleware]
    H --> I[Controller or handler]
    I --> J[Native PHP view or JSON result]
    J --> K[Response]
    K --> L[Single send boundary]
    G --> M[ExceptionHandler]
    H --> M
    I --> M
    M --> K

Apache serves existing files without PHP. Nonexistent paths reach app.php. The front controller selects exactly one environment, validates immutable configuration, asks application composition for a Kernel, converts globals into a Request, sends exactly one returned Response, and then invokes best-effort termination hooks. The kernel owns and always resets one container scope per request. Protective buffers reject accidental bootstrap, handler, or termination output without retaining its contents.

Ownership boundaries

Optional ModulePolicy is a startup-loaded per-application snapshot, never a global registry. Trusted code defines supported adapters/graph constraints; application config requests activation; readiness and user/object authorization remain separate. Explicit lazy HTTP/CLI/queue/schedule guards deny before optional execution. Old unguarded APIs do not change automatically. See module contracts and lifecycle.

Framework-owned mechanics:

• explicit transient/singleton/request-or-job lifetimes, provider ordering, graph freezing, and resolution;
• HTTP value objects and response emission;
• route matching and ordered middleware;
• contained native-PHP rendering;
• deterministic configuration precedence;
• immutable schema-validated configuration and redacted secret wrappers;
• prepared-value database access and explicit transactions;
• migration discovery, ledger checksums, locking, and CLI output;
• provider-neutral authentication, authorization, anti-bot, and rate-limit contracts;
• local cache/private-storage mechanics and side-effect-free JSON/validation values;
• provider-neutral mail, audit, feature, outbox, structured-AI policy, and non-executing Assisted Action contracts;
• bounded media container signature detection; and
• optional public asset derivation.

Application-owned policy:

• routes, controllers, use cases, repositories, schemas, and migrations;
• identities, roles, permissions, object-level decisions, and login workflows;
• view copy/layouts and any frontend enhancement;
• provider adapters and secrets;
• trusted prompts, output schemas, action definitions/handlers, AI quotas, domain approvals, and reconciliation of ambiguous action outcomes;
• private-object metadata/authorization, upload scanning, operational retention, backup, queue workers/adapters, and deployment.

Dependency direction

Application code depends on framework contracts. The neutral src/ runtime does not depend on an application namespace, schema, route, role, provider, or view; historical dependencies exist only in the explicitly preserved compatibility layer. Controllers are resolved only after route middleware grants access, preventing denied requests from constructing database/provider dependencies.

Error boundary

Expected client failures use HttpException and safe status/messages. Other exceptions receive a random correlation ID, safe HTML or JSON output, and a structured server log record that excludes exception messages and SQL text. DEV/TEST debug mode may expose the exception class, never the raw message. RuntimeContext and ContextLogger attach bounded environment, version, release, and available correlation identifiers to structured logs.

Editorial provenance

Source: docs/ARCHITECTURE.md. Source SHA-256: 31ed31b932846d088a568a2bfd2516b55231efea7638de2474faf1a8d11727ed.

Framework candidate reference; editorial checkpoint 2026-10-20. See candidate status and adoption boundary.