Coretsia Framework (Monorepo)

Coretsia [kɔˈrɛtsjɑ] / [ko-RET-si-ya] — from the Ukrainian word “серцевина” (core, foundation)

A modular, deterministic-by-default PHP framework monorepo with strict compile-time boundaries and SSoT-driven development

Status

Coretsia Framework is in active development.

Roadmap status:

• Prelude: implemented
• Phase 0 — Spikes and prototypes: implemented
• Phase 1 — Core: active development
• Phase 2 — Mode Infrastructure & CLI: planned
• Phase 3 — RELEASE: micro: planned
• Phase 4 — RELEASE: express: planned
• Phase 5 — RELEASE: hybrid: planned
• Phase 6+ — RELEASE: enterprise (extensions): planned
• Stable production release: not available yet

Current public implementation baseline:

• deterministic tooling and gates
• managed Composer workspace/repository synchronization
• publishing rails policy
• public split-package publishing baseline
• canonical CLI ports
• prod-safe CLI base
• Phase 0 devtools command pack
• Phase 1 contracts baseline
• DTO policy and package compliance rails
• architecture and quality verification rails

Authoritative planning and invariants:

• Roadmap (canonical)
• Single Source of Truth (invariants/shapes/policies)
• Security policy

Repository layout (canonical)

• framework/ — framework meta-package + all framework packages
  • packages: framework/packages/<layer>/<slug>/
  • layers: core|platform|integrations|enterprise|devtools|presets
• skeleton/ — local workspace app sandbox
  • fixtures, entrypoints, E2E tests, runtime caches (skeleton/var/**)
• docs/ — documentation
  • docs/roadmap/** — task-first roadmap (phases/epics)
  • docs/ssot/** — Single Source of Truth (invariants, shapes, policies)
  • docs/architecture/**, docs/ops/** — non-SSoT guides (must link to SSoT for truth)
• framework/tools/ — tooling, gates, CI rails, spikes (Phase 0 / Prelude)

Canonical rules (selected highlights)

Monorepo packaging law (MUST)

• Package path: framework/packages/<layer>/<slug>/
• Package id: <layer>/<slug>
• Composer name: coretsia/<layer>-<slug>
• Monorepo-wide versioning via git tags vMAJOR.MINOR.PATCH (no per-package versions)
• Canonical packaging strategy (single-choice)

Canonical entrypoints (MUST)

Run commands from the repo root. Canonical scripts:

composer setup
composer test
composer ci

Managed Composer repositories (MUST NOT edit manually)

repositories blocks in root/framework/skeleton composer.json files are managed only through the canonical repo-root commands:

composer sync:check
composer sync:repos

Manual edits are forbidden by policy and enforced by pre-commit/CI drift checks.

See:

• Command catalog
• Git hooks + managed repositories policy

Lock determinism (MUST)

• lock files are committed for root/framework/skeleton
• CI uses composer install and fails on lock drift
• drift check for managed repositories runs before installs

SSoT config shape invariant (cemented)

• config/<name>.php returns a subtree (no wrapper repeating the root key).
  • Example: config/foundation.php returns ['container' => ...], not ['foundation' => ...].
• Runtime reads from global config under that root key (e.g. foundation.container.*).

Runtime discovery (MUST)

• Runtime module discovery uses Composer metadata only.
• Runtime discovery MUST NOT do filesystem scanning.
• Tooling package indexes MUST NOT be used as runtime input.

Spikes boundary (MUST)

• The only spikes root is framework/tools/spikes/**.
• Spikes must not import runtime packages (core/*, platform/*, integrations/*) nor path-import framework/packages/**/src/**.
• Single exception: coretsia/devtools-internal-toolkit (tooling-only) used only via Composer autoload.

Requirements

• PHP: >= 8.4
• Composer: 2.x

Quick start (monorepo dev)

Run everything from the repository root. Canonical entrypoints:

composer setup
composer test
composer ci

• composer setup enables .githooks/ (sets core.hooksPath) and ensures managed Composer repositories policy.
• composer test runs the baseline test suite.
• composer ci runs the CI-style pipeline locally.

Documentation index

Guides

• Quickstart (clean clone → working baseline)
• Command catalog (canonical)
• Developer onboarding checklist
• Git hooks + managed repositories policy
• Dependency graph (conceptual; truth is in SSoT)
• Releasing (GitHub Release + Packagist)
• Packagist split publishing

References

• Packaging strategy (canonical)
• Repository structure
• Roadmap
• Canonical condensed rules (normative)
• SSoT index
• Branding spec
• Architecture generator idempotence evidence

The dedicated architecture-evidence workflow collects lightweight architecture generator idempotence evidence by repeatedly running architecture generator checks and verifying that tracked generated architecture files do not drift.

This evidence is not an application benchmark, not a production framework comparison, and not a claim of production runtime determinism.

Community RFCs

Website Design RFC

Coretsia is collecting open-source ideas for the official website design direction.

The discussion is focused on translating the canonical Coretsia branding specification into a practical website concept, including the homepage, documentation section, news/blog section, and community pages.

Design discussion and direction are tracked in:

• Website design RFC

Accepted website and visual implementation decisions are recorded in:

• Coretsia website decision records

Website implementation work happens through scoped issues and pull requests in:

• Coretsia website repository

Website proposals must align with:

• Branding specification

License

Licensed under the Apache License, Version 2.0. See LICENSE.
See NOTICE for attribution and third-party notices (if applicable).