Coretsia [kɔˈrɛtsjɑ] / [ko-RET-si-ya] — from the Ukrainian word “серцевина” (core, foundation)
A deterministic PHP 8.4+ application framework with preset-driven module composition, reproducible artifacts, explicit runtime lifecycles, and machine-enforced package boundaries and framework architecture rules.
Start minimal. Add capabilities as the application grows. Keep the same foundation.
Warning
Coretsia is pre-release and is not production-ready.
The current repository is suitable for architecture review, framework development, and experimental evaluation. Stable Micro, Express, Hybrid, and Enterprise application releases are not available yet.
Coretsia is a modular PHP framework designed for applications that may begin as small APIs, command-line tools, or conventional web applications and later grow into systems with background workers, queues, scheduled workloads, broader integrations, and stricter operational requirements.
The framework is built around a single architectural premise:
Application capabilities should be composed explicitly and deterministically, rather than emerging from incidental registration order, filesystem discovery, or undocumented bootstrap behavior.
Coretsia therefore treats module composition, generated artifacts, package boundaries, runtime lifecycles, and architecture verification as parts of the framework itself.
Coretsia's framework composition model is based on explicit inputs:
selected mode preset
+ Composer installed package metadata
+ canonical Coretsia module metadata
↓
deterministic ModulePlan
↓
ordered provider planning
↓
compiled config, container, and module artifacts
↓
runtime
Runtime module discovery uses Composer metadata only. It does not scan package directories or source trees to infer application composition.
Coretsia defines four canonical framework modes:
A minimal runtime profile for:
- focused APIs;
- small services;
- lightweight CLI workloads;
- applications that need a small active framework surface.
A conventional application profile for:
- HTTP and web application workflows;
- routing and validation;
- persistence;
- filesystem and other common application IO concerns.
A mixed synchronous and asynchronous profile for:
- background processing;
- queues;
- events;
- scheduled workloads;
- more complex business workflows.
An extended platform profile for:
- stronger operational requirements;
- governance and observability;
- broader infrastructure integrations;
- larger and longer-lived systems.
Modes are capability profiles. They do not prescribe MVC, DDD, Clean Architecture, Vertical Slice Architecture, or another application architecture style.
An application may use a simple architecture in a broader mode or a highly structured architecture in micro. The application architecture remains an owner decision.
Coretsia keeps three concerns separate:
- a mode preset selects the active framework capability profile;
- an application target identifies an application entrypoint or execution surface, such as
web,api,console, orworker; - a runtime driver selects the execution mechanism, such as classic PHP, FrankenPHP, Swoole, or RoadRunner.
These concepts are related but are not interchangeable. An application target does not introduce a separate module-selection mechanism: module composition remains preset-driven.
Coretsia does not attempt to differentiate itself merely by providing a container, modules, middleware, queues, workers, or runtime adapters. Modern PHP frameworks already provide mature versions of those capabilities.
Its intended difference is the way those capabilities are composed and governed.
A mode preset and the installed Composer metadata resolve into one explicit ModulePlan.
The plan records:
- enabled modules;
- disabled modules;
- optional modules that are not installed;
- deterministic dependency order;
- deterministic warnings and exported diagnostics.
Generated framework artifacts use a common versioned envelope and deterministic serialization rules.
Artifacts:
- have explicit schema identities;
- contain deterministic fingerprints;
- do not contain timestamps or absolute paths;
- must be rerun-no-diff;
- are validated by schema and header semantics.
Coretsia uses a format-neutral Unit-of-Work model for runtime operations such as:
- HTTP requests;
- CLI invocations;
- worker jobs;
- queue messages;
- scheduler ticks.
Framework-managed Unit-of-Work-local state is reset after each operation so that participating services do not retain state from previous operations.
Runtime drivers are selected explicitly and checked against a canonical compatibility matrix.
The Kernel must not infer active runtimes from:
- loaded extensions;
- process names;
- open ports;
- filesystem contents;
- container services;
- reflection.
Runtime conflicts fail deterministically before the runtime entrypoint executes.
Coretsia architecture rules are backed by repository tooling and CI rather than documentation alone.
Enforcement covers package and dependency boundaries, DTO and public API policy, runtime/tooling separation, deterministic generated outputs, security checks, and publishing safety.
Development status by capability track:
- Bootstrap & prototypes — implemented. Repository bootstrap, packaging foundations, development tooling, CI/architecture verification, deterministic tooling primitives, prototypes, and initial CLI foundations are in place.
- Core — implemented. Contracts, Foundation, Kernel, the baseline persistent Worker runtime, and the supporting composition and runtime infrastructure are implemented.
- Micro release track — active development. Current work focuses on mode infrastructure, production CLI integration, target-aware application entrypoints, and the remaining runtime infrastructure required for the first complete
microapplication release. - Express release — planned.
- Hybrid release — planned.
- Enterprise extensions — planned.
- contracts, foundation, and Kernel package baseline;
- deterministic mode-preset and module-plan contracts;
- Composer-metadata module discovery;
- module dependency and conflict resolution;
- deterministic topological ordering;
- immutable module-resolution snapshots;
- configuration Kernel and merge policy;
- deterministic artifact generation and fingerprinting;
- cache verification;
- compiled container artifact baseline;
- format-neutral Unit-of-Work shapes and lifecycle;
- runtime context and reset orchestration;
- runtime-driver selection and compatibility guard.
- deterministic tooling and CI verification;
- package identity and structure checks;
- DTO policy and consistency checks;
- architecture and dependency-boundary checks;
- managed Composer workspace synchronization;
- lock-drift checks;
- Composer audit;
- secret leakage checks;
- split-package publishing checks;
- release and publishing safety checks;
- architecture generator idempotence verification.
Coretsia does not yet provide:
- long-term backward compatibility guarantees;
- stable upgrade paths;
- a mature third-party package ecosystem.
Product-level integration and release hardening remain in progress.
Coretsia prioritizes:
- a small initial application surface that can grow by adding capabilities without replacing the application foundation;
- deterministic module and artifact composition;
- consistent lifecycle behavior across classic and long-running runtimes;
- enforceable architecture boundaries without unnecessary application-level ceremony.
Coretsia may currently be relevant to:
- framework and platform engineers;
- maintainers of long-lived PHP systems;
- teams interested in reproducible framework artifacts;
- developers working with modular monoliths;
- engineers evaluating long-running PHP lifecycle safety;
- contributors interested in architecture tooling and enforceable package boundaries.
Coretsia should not currently be selected for a production application that requires a stable framework, broad ecosystem support, or proven long-term upgrade compatibility.
framework/
packages/
core/
platform/
integrations/
enterprise/
devtools/
presets/
tools/
skeleton/
docs/
framework/packages/<layer>/<slug>/— publishable framework packages;framework/tools/**— repository tooling, generators, and CI support;skeleton/**— local application workspace, fixtures, entrypoints, E2E tests, and runtime caches;docs/ssot/**— canonical invariants, schemas, ownership, and policies;docs/architecture/**— architecture guidance that refers to SSoT for normative truth;docs/ops/**— operational and repository-maintenance documentation.
Canonical package layers are:
core
platform
integrations
enterprise
devtools
presets
Framework packages are developed in this monorepo and published as split Composer packages.
Canonical package identity:
path: framework/packages/<layer>/<slug>/
package id: <layer>/<slug>
Composer name: coretsia/<layer>-<slug>
All Coretsia packages use one framework release train:
vMAJOR.MINOR.PATCH
Independent per-package version streams are intentionally not supported.
This keeps framework packages, runtime contracts, generated artifact schemas, documentation, and tooling aligned under one compatibility line.
See:
Requirements:
- PHP 8.4 or later;
- Composer 2.x.
Run commands from the repository root:
composer setup
composer cicomposer setupconfigures the repository development environment and managed Composer repositories;composer ciruns the full verification pipeline, including the test suite and architecture checks.
This is a framework-development workflow, not yet an end-user application installation flow.
- SSoT index
- Quickstart for repository development
- Developer onboarding checklist
- Dependency graph guide
- Canonical packaging strategy
- Repository structure
- Command catalog
- Git hooks and managed repositories
- Architecture generator idempotence evidence
- Security policy
Coretsia is currently seeking technical review of:
- architecture boundaries;
- consistency between SSoT, implementation, tests, and tooling;
- deterministic behavior;
- package ownership;
- runtime lifecycle;
- unclear documentation;
- unnecessary complexity.
The project is not currently seeking production adoption claims or comparisons positioning Coretsia as a replacement for established frameworks.
Architecture and design discussions are tracked through:
Licensed under the Apache License, Version 2.0.
See: