The Project Layer — Project\

Documentation repository. These files document the Project\ layer, whose code currently lives in the kernel repository under projects/ (hkm-kernel). They were moved out because the kernel repo's documentation covers the kernel (src/) and the packages it runs on (modules/) — and nothing else.

Namespace Project\ → projects/ (composer psr-4 "Project\\": "projects/").

The directory layout here mirrors projects/ in the kernel repo, so a path in one maps to the same path in the other.

The third of the Three Worlds:

┌─────────────────────────────────────────────────┐
│  PROJECT LAYER  (wiring only — no business logic)│
│  ┌─────────────────────────────────────────────┐ │
│  │  MODULE / PLUGIN LAYER (bounded domains)    │ │
│  │  ┌───────────────────────────────────────┐  │ │
│  │  │  KERNEL (boot, security, DI, ports)   │  │ │
│  │  └───────────────────────────────────────┘  │ │
│  └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

The project knows everything and contains no business logic. It decides which project is served, which plugins are active, which port implementations back the kernel's interfaces, and how output is shaped — nothing more. Domain logic lives in plugins/.

Sub-docs for the deeper Support areas: Support/Casting/README.md · Support/Entity/README.md · Support/Seo/README.md.

A registered project may live outside this directory — projects.json records an absolute path, so a standalone project created with hkm new is booted from its own tree (EntryHelpers::bootstrapPathForContext() handles both layouts).

// projects/platform.json — which subdomain means which face
{ "subdomains": { "admin": ["app", "admin"], "api": ["api"] } }

// projects/projects.json — host → project
{
  "shop": {
    "name": "shop", "version": "1.0.0",
    "path": "/abs/path/to/psp-shop",
    "domains": ["shop.com"]
  }
}

Both are deploy-time artifacts: DomainResolver caches them per worker and never invalidates on the hot path. A redeploy spawns new workers.

Paths::var()/logs()/cache()/userdata()/config() resolve under the project root when withProjectPath() is set, and under the base roots otherwise.

1. Which project serves a request — DomainResolver (Host header) → HKM_PROJECT → 'admin'.
2. Which ports back the kernel interfaces — ->withPorts([...]) with the adapters in Infrastructure/ (or a plugin's).
3. Which plugins are active — ->withModules([...]), plus ->withEssentialModules([...]) / proj.json essentials[] for the always-on ones.
4. Which routes exist — proj.json routes[] (project routes override plugin routes) and routePolicy.disable[] (veto a plugin route without forking it).
5. What the environment is — the .env cascade and the pre-kernel error net.

✓ Wiring only — every business rule belongs to a plugin.
✓ Project resources (routes, views) override plugin resources by default.
✓ Port implementations are bound in bootstrap and injected — never instantiated inside a module.
✓ Support/ classes are DI-free and safe to call from any layer.
✗ Business logic in projects/ — if it is reusable it is a plugin, if it is project-only it goes in projects/<name>/src/.
✗ New local modules under projects/ — use plugins/ with the Plugins\ namespace.
✗ Routes defined in PHP — declare them in proj.json / withRoutes().
✗ DomainContext in a container — it rides on the immutable Request.
✗ Kernel code importing anything from Project\ — the dependency only points inward.