Appiyon Architectural Laws

Version: 3.0 Last Updated: 2025-10-24 Framework: Symfony 7.3 + Doctrine ORM Purpose: Die fundamentalen architektonischen Gesetze von Appiyon für KI-Agenten und Entwickler

🏗️ Die 6 Layer

Infrastructure  → Admin-System (separater Guard, KEINE Principals)
    ↓
Shared          → Enums, Traits, Identity (teams, principals, users, CRM)
    ↓
Foundation      → Basis-Bausteine (Tenant, User, Media, Communication)
    ↓
Core            → Primitive Data Models (Country, Language, Category)
    ↓
Domain          → Business Logic (App, Developer, Review)
    ↓
Dev             → Framework-Integration (Controllers, Commands, EventSubscribers)

🔴 Critical Laws (NIEMALS brechen)

Law 1: Layer Dependencies

Layers dürfen nur tiefere Layers importieren

✅ Domain → Core → Foundation → Shared → Infrastructure
❌ Core → Domain
❌ Foundation → Core
❌ Shared → Foundation

Beispiele:

php

// ✅ RICHTIG - Domain importiert Core
namespace App\Appi\Domain\App\UseCase;
use App\Appi\Core\Category\Entity\Category;

// ❌ FALSCH - Core importiert Domain
namespace App\Appi\Core\Category\UseCase;
use App\Appi\Domain\App\Entity\App; // VERBOTEN!

Grund: Verhindert zirkuläre Abhängigkeiten und hält die Architektur sauber.

Law 2: Event-Only Cross-Domain Communication

Domains kommunizieren NUR via Events

php

// ❌ FALSCH - Direkter Domain-zu-Domain Call
namespace App\Appi\Domain\Finance;
use App\Appi\Domain\Automotive\Service\RepairService;

class InvoiceService {
    public function __construct(
        private RepairService $repairService // VERBOTEN!
    ) {}
}

// ✅ RICHTIG - Via Events
namespace App\Appi\Domain\Finance;

class InvoiceListener {
    #[AsEventListener]
    public function onRepairCompleted(RepairCompletedEvent $event): void {
        // Erstelle Rechnung basierend auf Event
    }
}

Innerhalb EINES Domain-Moduls: Synchrone Calls erlaubt

Grund: Domains bleiben entkoppelt und können unabhängig entwickelt werden.

Law 3: Infrastructure Layer Isolation

Infrastructure = Separates Admin-System

php

// ✅ RICHTIG - Infrastructure mit eigener admins-Tabelle
namespace App\Appi\Infrastructure\Admin\Entity;

#[ORM\Entity]
#[ORM\Table(name: 'admins')]
class Admin {
    // Eigene Tabelle, KEIN Principal
}

// ❌ FALSCH - Admin als Principal
class Admin {
    #[ORM\OneToOne(targetEntity: Principal::class)]
    private Principal $principal; // NEIN!
}

Infrastructure-Layer:

✅ Hat eigene admins Tabelle
✅ Hat eigenen Authentication Guard
✅ Zugriff auf GLOBALE Infrastruktur
❌ NIEMALS Zugriff auf Mandanten-Daten
❌ KEINE Verwendung von Principal-System

Grund: Admins verwalten Infrastruktur, nicht Mandanten-Daten.

Law 4: Shared Layer = Identity + Utilities

Shared enthält universelle Komponenten

Shared Layer enthält:

✅ Identity-System: teams, principals, users, crm_entries
✅ Enums: PrincipalType, EntityStatus, LocationType, CommunicationType
✅ Traits: AuditableTrait, SoftDeleteTrait
✅ Contracts: Interfaces für alle Layer
✅ Exceptions: DomainException, ApplicationException
✅ Events: BaseDomainEvent, AuditableInterface
✅ Audit-System: AuditLog Entity

Grund: Shared stellt fundamentale Bausteine für alle Layer bereit.

Law 5: Principal-Based Identity

Principal = Universelle Identität (in Shared Layer)

php

#[ORM\Entity]
#[ORM\Table(name: 'principals')]
class Principal {
    #[ORM\Column(type: 'string')]
    private string $principalType; // 'person' or 'organization'
}

#[ORM\Entity]
#[ORM\Table(name: 'users')]
class User {
    #[ORM\Id]
    private int $principalId; // Primary Key = Principal ID
}

#[ORM\Entity]
#[ORM\Table(name: 'crm_entries')]
class CrmEntry {
    private int $principalId;
    private int $teamId;
    private int $roleTypeId; // customer, supplier, employee, developer
}

// ❌ FALSCH - Separate Tables
#[ORM\Entity]
class Customer { } // NEIN! Nutze CrmEntry

Grund: Eine Person/Organisation = Ein Principal mit vielen Rollen.

Law 6: No team_id in Foundation/Core/Domain

team_id existiert NUR in Dev Layer

php

// ❌ FALSCH - team_id in Core
namespace App\Appi\Core\Category\Entity;
class Category {
    private int $teamId; // VERBOTEN!
}

// ✅ RICHTIG - Core ohne team_id
namespace App\Appi\Core\Category\Entity;
class Category {
    // Universell, KEIN team_id
}

// ✅ RICHTIG - Dev mit team_id
namespace App\Appi\Dev\Catalog\Entity;
class Item {
    private int $teamId; // OK in Dev!
    private int $categoryId; // Referenz zu Core
}

Ausnahme: Shared/Identity (verwaltet Teams)

Grund: Foundation/Core/Domain sind universell. Kontext kommt in Dev.

Law 7: Authentication in Shared, Authorization in Dev

Auth-System ist zweigeteilt

php

// ✅ Authentication in Shared
namespace App\Appi\Shared\Identity\UseCase;
class AuthenticateUserHandler { }

// ✅ Authorization in Dev
namespace App\Appi\Dev\Http\Controller;
class ItemController {
    public function create() {
        $this->denyAccessUnlessGranted('ITEM_CREATE');
    }
}

// ❌ FALSCH - auth() in Core
namespace App\Appi\Core\Category\UseCase;
class CreateCategoryHandler {
    public function handle() {
        $user = $this->security->getUser(); // VERBOTEN!
    }
}

Grund: Business Logic bleibt testbar und kontext-frei.

Law 8: Enums statt Lookup-Tables

Enums in Shared, keine ID-basierten Lookups

php

// ✅ RICHTIG - Enum nutzen
use App\Appi\Shared\Enums\PrincipalType;

#[ORM\Entity]
class Principal {
    #[ORM\Column(type: 'string', enumType: PrincipalType::class)]
    private PrincipalType $principalType;
}

// Migration mit CHECK Constraint
CREATE TABLE principals (
    principal_type VARCHAR(50),
    CONSTRAINT chk_type CHECK (principal_type IN ('person', 'organization'))
);

// ❌ FALSCH - Lookup-Table
CREATE TABLE principal_types (id SERIAL, name VARCHAR);

Verfügbare Enums: PrincipalType, EntityStatus, LocationType, OperationalStatus, CommunicationType

Grund: Enums sind typsicher, kein JOIN-Overhead, klare Validation.

Law 9: CQRS Pattern with Commands & Handlers

Use Cases folgen Command/Handler Pattern

php

// ✅ Command (DTO)
final readonly class CreateAdminCommand {
    public function __construct(
        public string $name,
        public string $email,
        public string $password
    ) {}
}

// ✅ Handler
final readonly class CreateAdminHandler {
    public function handle(CreateAdminCommand $command): Admin {
        // 1. Validation
        // 2. Business Rules
        // 3. Create Entity
        // 4. Persist
        // 5. Dispatch Event
    }
}

// ❌ FALSCH - Business Logic im Controller

Grund: Klare Trennung von Input, Business Logic, Output.

Law 10: Doctrine statt Active Record

Entities sind reine Datenstrukturen

php

// ✅ RICHTIG - Doctrine Entity
#[ORM\Entity]
class Admin {
    private ?int $id = null;
    private string $name;

    public function getName(): string { return $this->name; }
}

// ✅ Business Logic in Handlers
class CreateAdminHandler {
    public function handle() {
        $admin = new Admin();
        $this->repository->save($admin);
    }
}

// ❌ FALSCH - Active Record (Laravel)
class Admin extends Model {
    public static function create() { } // NO!
    public function save() { } // NO!
}

Grund: Doctrine Pattern. Entities = Daten, Repositories = Persistence.

Law 11: Repository Interfaces + Doctrine Implementation

Repositories immer als Interface definieren

php

// ✅ Contract
interface AdminRepositoryInterface {
    public function save(Admin $admin): void;
    public function findById(int $id): ?Admin;
}

// ✅ Implementation
class AdminRepository implements AdminRepositoryInterface {
    // Doctrine-spezifische Implementation
}

// ✅ Services nutzen Interface
class CreateAdminHandler {
    public function __construct(
        private AdminRepositoryInterface $repository
    ) {}
}

Grund: Testbarkeit, Austauschbarkeit, klare Contracts.

Law 12: Events mit AuditableInterface

Wichtige Domain Events implementieren AuditableInterface

php

final class AdminCreatedEvent implements AuditableInterface {
    public function getEventName(): string {
        return 'admin.created';
    }

    public function getAuditableType(): string {
        return Admin::class;
    }

    public function getAuditData(): array {
        return ['name' => $this->admin->getName()];
    }
}

Naming: {entity}.{action} (admin.created, user.authenticated)

Grund: Automatisches Audit-Logging für alle wichtigen Events.

📋 Quick Reference

Feature	Infrastructure	Shared	Foundation	Core	Domain	Dev
Imports	-	Infra	Shared	Found	Core	Domain
team_id	❌	CrmEntry	❌	❌	❌	✅
Enums	❌	✅	uses	uses	uses	uses
Auth	Own Guard	✅	❌	❌	❌	✅ (authz)
APIs	❌	❌	❌	❌	❌	✅
Controllers	❌	❌	❌	❌	❌	✅

Diese Laws sind die Grundlage für Code-Generierung. Bei Unsicherheit: Frage nach!

Appiyon Architectural Laws ​

🏗️ Die 6 Layer ​

🔴 Critical Laws (NIEMALS brechen) ​

Law 1: Layer Dependencies ​

Law 2: Event-Only Cross-Domain Communication ​

Law 3: Infrastructure Layer Isolation ​

Law 4: Shared Layer = Identity + Utilities ​

Law 5: Principal-Based Identity ​

Law 6: No team_id in Foundation/Core/Domain ​

Law 7: Authentication in Shared, Authorization in Dev ​

Law 8: Enums statt Lookup-Tables ​

Law 9: CQRS Pattern with Commands & Handlers ​

Law 10: Doctrine statt Active Record ​

Law 11: Repository Interfaces + Doctrine Implementation ​

Law 12: Events mit AuditableInterface ​

📋 Quick Reference ​