Skip to main content

Architecture overview

Omnitrix is distributed as three packages:

PackageNamespaceRole
omnitrix/omnitrixApp\ (yours)the application template: bootstrap.php, config/, routes/, src/, database/, the omnitrix command. Created once with composer create-project; from then on it is your code
omnitrix/coreOmnitrix\ and Omnitrix\Core\all framework logic, installed in vendor/: the framework applications build on (Omnitrix\) and the engine underneath it (Omnitrix\Core\)
omnitrix/installer—the global omnitrix new command, a thin wrapper around composer create-project

Your application requires omnitrix/core, configures it through config/ and the Application methods, and uses it through the framework's facades, models and console. Updating the framework is composer update omnitrix/core; the template is only used once, when the project is created.

Inside omnitrix/core the two layers stay separate:

LayerNamespaceContents
FrameworkOmnitrix\Application, routing, middleware, requests and responses, validation, security, rate limiting, observability, facades, models and migrations, the console, queue workers
EngineOmnitrix\Core\server runtime and worker lifecycle, request context, HTTP transport, concurrency primitives, connection pools, database driver and query builder, HTTP client, Redis, cache, queue storage, CPU process pool, coroutine I/O

The engine never uses the framework layer.

request ─▶ OpenSwoole Http\Server (process mode) ─▶ worker coroutine ┐
request context bound, failures contained, deferred cleanup │ Core
HTTP transport: body limit, timeout, request id ┘
HttpKernel: Router (FastRoute) ─▶ middleware pipeline ─▶ handler ┐
handler uses: DB / Http / Redis / Cache / Queue / Cpu facades, │ Framework
Async ┘
│ pooled, owned per coroutine, bounded, cancellable
▼
MariaDB/MySQL (PDO + mysqlnd) · upstream APIs · Redis · CPU pool processes

Framework modules​

NamespaceContents
OmnitrixApplication (configuration, routes, middleware, lifecycle hooks, CPU pool, metrics, health)
Omnitrix\HttpRequest, Response, Stream, Cookie, HttpKernel, exceptions, middleware pipeline
Omnitrix\RoutingRouter, Route, handler resolution
Omnitrix\FacadesDB, Http, Redis, Cache, Queue, Cpu, Async
Omnitrix\ValidationValidator, ValidationException
Omnitrix\SecurityBearerTokenAuth, Authorize, Identity, SecurityHeaders
Omnitrix\RateLimitRateLimit middleware, shared-memory and Redis limiters
Omnitrix\ObservabilityAccessLog, health checks
Omnitrix\DatabaseModel, ModelQuery, Collection, Paginator, relations, Schema, Blueprint, Migration, Migrator, Seeder
Omnitrix\ConsoleConsole, Command and the built-in commands
Omnitrix\QueueWorker
Omnitrix\ConfigEnv, Config
Omnitrix\SupportStr

Engine types that appear in the public API​

Some values the framework returns or throws are defined in Core. They are stable, documented types; applications use them but do not construct the underlying services:

TypeWhere you meet it
Omnitrix\Core\Runtime\Context\RequestContext$request->context()
Omnitrix\Core\Runtime\Worker\WorkerContextarguments of onWorkerStart, onWorkerStop, configureContainer
Omnitrix\Core\Runtime\Config\InvalidConfigurationExceptionthrown by Application::create() and Env
Omnitrix\Core\Database\DatabaseManager, Database, Query\Builder, Query\Expression, Exception\*DB facade, ModelQuery::toBase()
Omnitrix\Core\HttpClient\PendingRequest, Response, Exception\*Http facade
Omnitrix\Core\Redis\RedisClient, Omnitrix\Core\Redis\Exception\*Redis facade
Omnitrix\Core\Cache\CacheCache::store()
Omnitrix\Core\Concurrency\TaskScope, Task, Outcome, CancellationToken, TimeoutException, CancelledExceptionAsync facade
Omnitrix\Core\Process\CpuException and subclassesCpu::run()
Omnitrix\Core\Queue\Jobsecond argument of queue handlers
Omnitrix\Core\Log\JsonLoggerdefault logger; can be passed to Application::create()
Omnitrix\Core\IO\*optional coroutine socket, DNS and file helpers (Sockets and files)

Everything else in Core — the server runtime, transport adapter, pools, drivers, schedulers and process plumbing — is an implementation detail and may change between Core releases without notice. Classes and methods marked @internal in either package are not part of the public API.

Design principles​

  • One coroutine per request, cooperative I/O everywhere. OpenSwoole runtime hooks make PDO, phpredis, sockets and file access suspend only the calling coroutine.
  • Owned, bounded resources. Every connection belongs to one coroutine at a time; pools, fan-out and CPU queues have explicit limits and fail with typed exceptions instead of queueing without bound.
  • Structured concurrency. Child tasks never outlive the operation that started them; timeouts and failures cancel siblings.
  • Fail closed, report safely. Configuration is validated at boot; client-visible errors carry safe messages and a request id; details stay in the logs.
  • Worker-scoped state. Services are created per worker after the fork; nothing that holds a socket crosses process boundaries.

The engine's internal design is described in The engine.