rules-architecture

name	rules-architecture
description	Non-negotiable Jardis architecture rules — five constitutional pillars, hexagonal dependency direction, Closure-Orchestrator pattern. Consult before authoring any new class or reviewing existing code.
zone	crosscut
prerequisites	[]
next	[]

Scope

Applies to Jardis packages (JardisAdapter/*, JardisSupport/*, JardisTools/*) and library code inside the hexagonal cake. The five pillars (§1) also hold on the Designer-generated Domain layer, but the physical directory contract there is different — see platform-implementation.

1. Five pillars

1. Separation of Concerns — different responsibilities → different components. Cross-cutting via Decorator/Middleware.
2. Single Responsibility — one class = one reason to change. "And"-test: description contains "and" → split.
3. Composition over Inheritance — interfaces, Constructor Injection, runtime replaceability. No traits. abstract only for Exception hierarchies. static only for VO named constructors.
4. Data-Behavior Separation — DTOs / Entities / VOs hold data. Services operate on data. Persistence external via Repository. Entities have no business methods.
5. Explicit Dependencies — Constructor Injection for everything. Infrastructure behind interfaces. No implicit access to outside state.

PHP 8.3+ | declare(strict_types=1) | PHPStan Level 8 | PSR-4/PSR-12 | Coverage ≥ 80%

2. Hexagonal layout

Dependency arrows point inward to the Core. Core never imports Adapter code.

JardisCore\*              -> Domain Layer
JardisSupport\Contract\*  -> Contracts (interfaces, ports)
JardisSupport\*           -> Application / Support
JardisAdapter\*           -> Infrastructure
JardisTools\*             -> Development Tools

JardisTools -> JardisAdapter -> JardisSupport -> JardisCore
                    |               |              |
          JardisSupport\Contract <-<-<-----------<-<

Adapters implement Contracts. Any inner-layer use pointing outward is a review blocker.

3. Closure-Orchestrator pattern

Closure — atomic unit. Class with __invoke() as the only public entry point. Name = what it does (BuildKey, ValidatePath). IPO. No run() / execute() / handle(). No second public method.

final class BuildKey
{
    public function __invoke(string $prefix, string $path): string
    {
        return $this->normalize($prefix) . '/' . ltrim($path, '/');
    }
    private function normalize(string $prefix): string { return rtrim($prefix, '/'); }
}

Orchestrator — composition. Consumes Closures, no own logic. Closures bound in constructor via first-class callable syntax.

final class Filesystem
{
    private readonly Closure $buildPath;
    private readonly Closure $validatePath;

    public function __construct(string $root)
    {
        $this->buildPath    = (new BuildFullPath($root))->__invoke(...);
        $this->validatePath = (new ValidatePath())->__invoke(...);
    }

    public function read(string $path): string
    {
        $fullPath = ($this->buildPath)($path);
        return file_get_contents(($this->validatePath)($fullPath));
    }
}

Multi-method interfaces (hash/verify/needsRehash) → each method delegates to its own Closure. Closures may wrap other Closures (Decorator: Retry wraps Transport).

4. Directory structure

src/
├── Orchestrator1.php         ← root-namespace Orchestrator
├── Handler/                  ← ALL Closures, category subdirs
│   └── Feature1/DoSomething.php
├── Data/                     ← VOs, Enums, Builders
└── Exception/
tests/Support/                ← Test fakes (NOT in src/)

5. Anti-patterns

Anti-pattern	Solution
Private method identical in 3+ classes	Extract Closure
Closure with 2+ public methods	Split
Orchestrator with own business logic	Move to Closure
Closure > 150 lines	Extract sub-Closures
Handlers scattered in feature dirs	Centralise under Handler/
VOs/Enums in feature dirs	Centralise under Data/
Test fakes in src/	Move to tests/Support/
new Handler() direct call	Bind via (new Handler())->__invoke(...)

6. Per-class checklist

• PHP 8.3+, declare(strict_types=1), PHPStan Level 8 passes
• PSR-4 namespace matches path
• Correct layer, dependency direction respected
• Orchestrator (logic-free, root ns) or Closure (__invoke, under Handler/)
• All dependencies via Constructor Injection
• No trait, no abstract (except Exception), no static (except VO named constructor)
• If Decorator: outer wraps inner via same signature