ADR-004: Package layout — application template and one framework package
Status: Accepted (2026-11-14)
Context
Applications need a starting point they own (configuration, routes, models, migrations, a command line) and framework logic they do not have to read or change. The framework layer (application object, routing, middleware, facades, models, console) and the runtime engine (server lifecycle, pools, drivers, concurrency) are released together and tested together; publishing them as separate packages added version coordination without benefit to applications.
Decision
omnitrix/omnitrixis the application template (Composer typeproject), installed withcomposer create-project omnitrix/omnitrix my-apioromnitrix new my-api. It contains no framework logic.omnitrix/corecontains all framework logic, installed invendor/:- the framework layer, namespace
Omnitrix\, insrc/; - the engine, namespace
Omnitrix\Core\, insrc/Core/.
- the framework layer, namespace
- The engine never uses the framework layer. The transport depends on
Http\HttpErrorInterfacerather than on framework exception classes; the framework'sHttpExceptionimplements it. - Engine types that appear in the framework's public API (request context, worker context,
query builder, HTTP client responses, typed exceptions, concurrency handles) are documented
as stable. Everything else in the engine is an implementation detail; plumbing that must be
publicfor technical reasons is marked@internal. omnitrix/installerprovides theomnitrix newcommand.
Consequences
- One version number covers framework and engine; an application updates both with
composer update omnitrix/core. - The layering is enforced by namespaces,
@internalmarkers and code review rather than by separate packages.