php/src/Core/CLAUDE.md

Core Orchestration

Root-level files in src/Core/ that wire the entire framework together. These are the bootstrap, module discovery, lazy loading, and pro-feature detection systems.

Files

File	Purpose
Init.php	True entry point. Core\Init::handle() replaces Laravel's bootstrap/app.php. Runs WAF input filtering via Input::capture(), then delegates to Boot::app(). Prefers App\Boot if it exists.
Boot.php	Configures Laravel Application with providers, middleware, and exceptions. Provider load order is critical: LifecycleEventProvider -> Website\Boot -> Front\Boot -> Mod\Boot.
LifecycleEventProvider.php	The orchestrator. Registers ModuleScanner and ModuleRegistry as singletons, scans configured paths, wires lazy listeners. Static fire*() methods are called by frontage modules to dispatch lifecycle events and process collected requests (views, livewire, routes, middleware).
ModuleScanner.php	Discovers Boot.php files in subdirectories of given paths. Reads static $listens arrays via reflection without instantiating modules. Maps paths to namespaces (/Core -> Core\, /Mod -> Mod\, /Website -> Website\, /Plug -> Plug\).
ModuleRegistry.php	Coordinates scanner output into Laravel's event system. Sorts listeners by priority (highest first), creates LazyModuleListener instances, supports late-registration via addPaths().
LazyModuleListener.php	The lazy-loading wrapper. Instantiates module on first event fire (cached thereafter). ServiceProviders use resolveProvider(), plain classes use make(). Records audit logs and profiling data.
Pro.php	Detects Flux Pro and FontAwesome Pro installations. Auto-enables pro features, falls back gracefully to free equivalents. Throws helpful dev-mode exceptions.
config.php	Framework configuration: branding, domains, CDN, organisation, social links, contact, FontAwesome, pro fallback behaviour, icon defaults, debug settings, seeder auto-discovery.

Bootstrap Sequence

public/index.php
  -> Core\Init::handle()
       -> Input::capture()           # WAF layer sanitises $_GET/$_POST
       -> Boot::app()                # Build Laravel Application
            -> LifecycleEventProvider # register(): scan + wire lazy listeners
            -> Website\Boot          # register(): domain resolution
            -> Front\Boot            # boot(): fires lifecycle events
            -> Mod\Boot              # aggregates feature modules

Module Declaration Pattern

Modules declare interest in events via static $listens:

class Boot
{
    public static array $listens = [
        WebRoutesRegistering::class => 'onWebRoutes',
        AdminPanelBooting::class => ['onAdmin', 10],  // priority 10
    ];
}

Modules are never instantiated until their event fires.

Lifecycle Events (fire* methods)

Method	Event	Middleware	Processes
fireWebRoutes()	WebRoutesRegistering	web	views, livewire, routes
fireAdminBooting()	AdminPanelBooting	admin	views, translations, livewire, routes
fireClientRoutes()	ClientRoutesRegistering	client	views, livewire, routes
fireApiRoutes()	ApiRoutesRegistering	api	routes
fireMcpRoutes()	McpRoutesRegistering	mcp	routes
fireMcpTools()	McpToolsRegistering	--	returns handler class names
fireConsoleBooting()	ConsoleBooting	--	artisan commands
fireQueueWorkerBooting()	QueueWorkerBooting	--	queue-specific init

All route-registering fire methods call refreshRoutes() afterward to deduplicate names and refresh lookups.

Default Scan Paths

• app_path('Core') -- application-level core modules
• app_path('Mod') -- feature modules
• app_path('Website') -- domain-scoped website modules
• src/Core -- framework's own modules
• src/Mod -- framework's own feature modules

Configurable via config('core.module_paths').

Priority System

• Default: 0
• Higher values run first: ['onAdmin', 100] runs before ['onAdmin', 0]
• Negative values run last: ['onCleanup', -10]

Key Integration Points

• Init::boot() returns App\Boot if it exists, allowing apps to customise providers
• Boot::basePath() auto-detects monorepo vs vendor structure
• LifecycleEventProvider processes middleware aliases, view namespaces, and Livewire components collected during event dispatch
• Route deduplication prevents route:cache failures when the same route file serves multiple domains