diff --git a/src/Core/Activity/Concerns/CLAUDE.md b/src/Core/Activity/Concerns/CLAUDE.md new file mode 100644 index 0000000..7ec5ea7 --- /dev/null +++ b/src/Core/Activity/Concerns/CLAUDE.md @@ -0,0 +1,17 @@ +# Activity/Concerns/ — Activity Logging Trait + +## Traits + +| Trait | Purpose | +|-------|---------| +| `LogsActivity` | Drop-in trait for models that should log changes. Wraps `spatie/laravel-activitylog` with sensible defaults: auto workspace_id tagging, dirty-only logging, empty log suppression. | + +## Configuration via Model Properties + +- `$activityLogAttributes` — array of attributes to log (default: all dirty) +- `$activityLogName` — custom log name +- `$activityLogEvents` — events to log (default: created, updated, deleted) +- `$activityLogWorkspace` — include workspace_id (default: true) +- `$activityLogOnlyDirty` — only log changed attributes (default: true) + +Static helpers: `activityLoggingEnabled()`, `withoutActivityLogging(callable)`. diff --git a/src/Core/Activity/Console/CLAUDE.md b/src/Core/Activity/Console/CLAUDE.md new file mode 100644 index 0000000..353595b --- /dev/null +++ b/src/Core/Activity/Console/CLAUDE.md @@ -0,0 +1,9 @@ +# Activity/Console/ — Activity Log Commands + +## Commands + +| Command | Signature | Purpose | +|---------|-----------|---------| +| `ActivityPruneCommand` | `activity:prune` | Prunes old activity logs. Options: `--days=N` (retention period), `--dry-run` (show count without deleting). Uses retention from config when days not specified. | + +Part of the Activity subsystem's maintenance tooling. Should be scheduled in the application's console kernel for regular cleanup. diff --git a/src/Core/Activity/Models/CLAUDE.md b/src/Core/Activity/Models/CLAUDE.md new file mode 100644 index 0000000..772b6fb --- /dev/null +++ b/src/Core/Activity/Models/CLAUDE.md @@ -0,0 +1,14 @@ +# Activity/Models/ — Activity Log Model + +## Models + +| Model | Extends | Purpose | +|-------|---------|---------| +| `Activity` | `Spatie\Activitylog\Models\Activity` | Extended activity model with workspace-aware scopes via the `ActivityScopes` trait. Adds query scopes for filtering by workspace, subject, causer, event type, date range, and search. | + +Configure as the activity model in `config/activitylog.php`: +```php +'activity_model' => \Core\Activity\Models\Activity::class, +``` + +Requires `spatie/laravel-activitylog`. diff --git a/src/Core/Activity/Scopes/CLAUDE.md b/src/Core/Activity/Scopes/CLAUDE.md new file mode 100644 index 0000000..624d5d2 --- /dev/null +++ b/src/Core/Activity/Scopes/CLAUDE.md @@ -0,0 +1,9 @@ +# Activity/Scopes/ — Activity Query Scopes + +## Traits + +| Trait | Purpose | +|-------|---------| +| `ActivityScopes` | Comprehensive query scopes for activity log filtering. Includes: `forWorkspace`, `forSubject`, `forSubjectType`, `byCauser`, `byCauserId`, `ofType`, `createdEvents`, `updatedEvents`, `deletedEvents`, `betweenDates`, `today`, `lastDays`, `lastHours`, `search`, `inLog`, `withChanges`, `withExistingSubject`, `withDeletedSubject`, `newest`, `oldest`. | + +Used by `Core\Activity\Models\Activity`. Workspace scoping checks both `properties->workspace_id` and subject model's `workspace_id`. Requires `spatie/laravel-activitylog`. diff --git a/src/Core/Activity/Services/CLAUDE.md b/src/Core/Activity/Services/CLAUDE.md new file mode 100644 index 0000000..3296275 --- /dev/null +++ b/src/Core/Activity/Services/CLAUDE.md @@ -0,0 +1,11 @@ +# Activity/Services/ — Activity Log Service + +## Services + +| Service | Purpose | +|---------|---------| +| `ActivityLogService` | Fluent interface for querying and managing activity logs. Methods: `logFor($model)`, `logBy($user)`, `forWorkspace($workspace)`, `recent()`, `search($term)`. Chainable query builder with workspace awareness. | + +Provides the business logic layer over Spatie's activity log. Used by the `ActivityFeed` Livewire component and available for injection throughout the application. + +Requires `spatie/laravel-activitylog`. diff --git a/src/Core/Activity/View/Blade/admin/CLAUDE.md b/src/Core/Activity/View/Blade/admin/CLAUDE.md new file mode 100644 index 0000000..2f5148c --- /dev/null +++ b/src/Core/Activity/View/Blade/admin/CLAUDE.md @@ -0,0 +1,9 @@ +# Activity/View/Blade/admin/ — Activity Feed Blade Template + +## Templates + +| File | Purpose | +|------|---------| +| `activity-feed.blade.php` | Admin panel activity log display — paginated list with filters (user, model type, event type, date range), activity detail modal with full diff view, optional polling for real-time updates. | + +Rendered by the `ActivityFeed` Livewire component via the `core.activity::admin.*` view namespace. diff --git a/src/Core/Activity/View/Modal/Admin/CLAUDE.md b/src/Core/Activity/View/Modal/Admin/CLAUDE.md new file mode 100644 index 0000000..8e305a7 --- /dev/null +++ b/src/Core/Activity/View/Modal/Admin/CLAUDE.md @@ -0,0 +1,11 @@ +# Activity/View/Modal/Admin/ — Activity Feed Livewire Component + +## Components + +| Component | Purpose | +|-----------|---------| +| `ActivityFeed` | Livewire component for displaying activity logs in the admin panel. Paginated list with URL-bound filters (causer, subject type, event type, date range, search). Supports workspace scoping and optional polling for real-time updates. | + +Usage: `` or `` + +Requires `spatie/laravel-activitylog`. diff --git a/src/Core/Bouncer/Database/Seeders/CLAUDE.md b/src/Core/Bouncer/Database/Seeders/CLAUDE.md new file mode 100644 index 0000000..ec7e928 --- /dev/null +++ b/src/Core/Bouncer/Database/Seeders/CLAUDE.md @@ -0,0 +1,7 @@ +# Bouncer/Database/Seeders/ — Bouncer Seeders + +## Seeders + +| File | Purpose | +|------|---------| +| `WebsiteRedirectSeeder.php` | Seeds 301 redirects for renamed website URLs. Uses the `RedirectService` to register old-to-new path mappings (e.g., `/services/biohost` -> `/services/bio`). Added during URL simplification (2026-01-16). | diff --git a/src/Core/Bouncer/Gate/Attributes/CLAUDE.md b/src/Core/Bouncer/Gate/Attributes/CLAUDE.md new file mode 100644 index 0000000..18e637c --- /dev/null +++ b/src/Core/Bouncer/Gate/Attributes/CLAUDE.md @@ -0,0 +1,14 @@ +# Bouncer/Gate/Attributes/ — Action Gate PHP Attributes + +## Attributes + +| Attribute | Target | Purpose | +|-----------|--------|---------| +| `#[Action(name, scope?)]` | Method, Class | Declares an explicit action name for permission checking, overriding auto-resolution from controller/method names. Optional `scope` for resource-specific permissions. | + +Without this attribute, action names are auto-resolved: `ProductController@store` becomes `product.store`. + +```php +#[Action('product.create')] +public function store(Request $request) { ... } +``` diff --git a/src/Core/Bouncer/Gate/CLAUDE.md b/src/Core/Bouncer/Gate/CLAUDE.md new file mode 100644 index 0000000..e2f4323 --- /dev/null +++ b/src/Core/Bouncer/Gate/CLAUDE.md @@ -0,0 +1,18 @@ +# Bouncer/Gate/ — Action Gate Authorisation + +Whitelist-based request authorisation system. Philosophy: "If it wasn't trained, it doesn't exist." + +## Files + +| File | Purpose | +|------|---------| +| `Boot.php` | ServiceProvider — registers middleware, configures action gate. | +| `ActionGateMiddleware.php` | Intercepts requests, checks if the target action is permitted. Production mode blocks unknown actions (403). Training mode prompts for approval. | +| `ActionGateService.php` | Core service — resolves action names from routes/controllers, checks `ActionPermission` records. Supports `#[Action]` attribute, auto-resolution from controller names, and training mode. | +| `RouteActionMacro.php` | Adds `->action('name')` and `->bypassGate()` macros to Laravel routes for fluent action naming. | + +## Integration Flow + +``` +Request -> ActionGateMiddleware -> ActionGateService::check() -> ActionPermission (allowed/denied) -> Controller +``` diff --git a/src/Core/Bouncer/Gate/Migrations/CLAUDE.md b/src/Core/Bouncer/Gate/Migrations/CLAUDE.md new file mode 100644 index 0000000..70d06c1 --- /dev/null +++ b/src/Core/Bouncer/Gate/Migrations/CLAUDE.md @@ -0,0 +1,7 @@ +# Bouncer/Gate/Migrations/ — Action Gate Schema + +## Migrations + +| File | Purpose | +|------|---------| +| `0001_01_01_000002_create_action_permission_tables.php` | Creates `core_action_permissions` (whitelisted actions) and `core_action_requests` (audit log) tables. | diff --git a/src/Core/Bouncer/Gate/Models/CLAUDE.md b/src/Core/Bouncer/Gate/Models/CLAUDE.md new file mode 100644 index 0000000..bb4db3e --- /dev/null +++ b/src/Core/Bouncer/Gate/Models/CLAUDE.md @@ -0,0 +1,8 @@ +# Bouncer/Gate/Models/ — Action Gate Models + +## Models + +| Model | Table | Purpose | +|-------|-------|---------| +| `ActionPermission` | `core_action_permissions` | Whitelisted action record. Stores action identifier, scope, guard, role, allowed flag, and training metadata (who trained it, when, from which route). Source: `trained`, `seeded`, or `manual`. | +| `ActionRequest` | `core_action_requests` | Audit log entry for all action permission checks. Records HTTP method, route, action, guard, user, IP, status (allowed/denied/pending), and whether training was triggered. | diff --git a/src/Core/Bouncer/Gate/Tests/Feature/CLAUDE.md b/src/Core/Bouncer/Gate/Tests/Feature/CLAUDE.md new file mode 100644 index 0000000..3531fbb --- /dev/null +++ b/src/Core/Bouncer/Gate/Tests/Feature/CLAUDE.md @@ -0,0 +1,7 @@ +# Bouncer/Gate/Tests/Feature/ — Action Gate Feature Tests + +## Test Files + +| File | Purpose | +|------|---------| +| `ActionGateTest.php` | Integration tests for the full action gate flow — middleware interception, permission enforcement, training mode responses, route macro behaviour. | diff --git a/src/Core/Bouncer/Gate/Tests/Unit/CLAUDE.md b/src/Core/Bouncer/Gate/Tests/Unit/CLAUDE.md new file mode 100644 index 0000000..469c9e8 --- /dev/null +++ b/src/Core/Bouncer/Gate/Tests/Unit/CLAUDE.md @@ -0,0 +1,7 @@ +# Bouncer/Gate/Tests/Unit/ — Action Gate Unit Tests + +## Test Files + +| File | Purpose | +|------|---------| +| `ActionGateServiceTest.php` | Unit tests for the `ActionGateService`. Tests action name resolution from routes and controllers, permission checking, training mode behaviour, and `#[Action]` attribute support. | diff --git a/src/Core/Bouncer/Migrations/CLAUDE.md b/src/Core/Bouncer/Migrations/CLAUDE.md new file mode 100644 index 0000000..f1639ab --- /dev/null +++ b/src/Core/Bouncer/Migrations/CLAUDE.md @@ -0,0 +1,9 @@ +# Bouncer/Migrations/ — Bouncer Schema Migrations + +## Migrations + +| File | Purpose | +|------|---------| +| `0001_01_01_000001_create_bouncer_tables.php` | Creates core bouncer tables for IP/domain blocklisting, redirect rules, and rate limiting configuration. | + +Uses early timestamps to run before application migrations. diff --git a/src/Core/Bouncer/Tests/Unit/CLAUDE.md b/src/Core/Bouncer/Tests/Unit/CLAUDE.md new file mode 100644 index 0000000..94b9de4 --- /dev/null +++ b/src/Core/Bouncer/Tests/Unit/CLAUDE.md @@ -0,0 +1,7 @@ +# Bouncer/Tests/Unit/ — Bouncer Unit Tests + +## Test Files + +| File | Purpose | +|------|---------| +| `BlocklistServiceTest.php` | Unit tests for the IP/domain blocklist service. Tests blocking, allowing, and checking IPs and domains against the blocklist. | diff --git a/src/Core/CLAUDE.md b/src/Core/CLAUDE.md new file mode 100644 index 0000000..940ff77 --- /dev/null +++ b/src/Core/CLAUDE.md @@ -0,0 +1,83 @@ +# 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`: + +```php +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 diff --git a/src/Core/Cdn/Console/CLAUDE.md b/src/Core/Cdn/Console/CLAUDE.md new file mode 100644 index 0000000..b26cbf9 --- /dev/null +++ b/src/Core/Cdn/Console/CLAUDE.md @@ -0,0 +1,10 @@ +# Cdn/Console/ — CDN Artisan Commands + +## Commands + +| Command | Signature | Purpose | +|---------|-----------|---------| +| `CdnPurge` | `cdn:purge` | Purge CDN cache — by URL, tag, workspace, or global. | +| `OffloadMigrateCommand` | `cdn:offload-migrate` | Migrate local files to remote storage, creating offload records. | +| `PushAssetsToCdn` | `cdn:push` | Push local assets to CDN storage zone. | +| `PushFluxToCdn` | `cdn:push-flux` | Push Flux UI framework assets to CDN. | diff --git a/src/Core/Cdn/Facades/CLAUDE.md b/src/Core/Cdn/Facades/CLAUDE.md new file mode 100644 index 0000000..b6b4886 --- /dev/null +++ b/src/Core/Cdn/Facades/CLAUDE.md @@ -0,0 +1,9 @@ +# Cdn/Facades/ — CDN Facade + +## Facades + +| Facade | Resolves To | Purpose | +|--------|-------------|---------| +| `Cdn` | `StorageUrlResolver` | Static proxy for CDN operations — `cdn()`, `origin()`, `private()`, `signedUrl()`, `asset()`, `pushToCdn()`, `deleteFromCdn()`, `purge()`, `storePublic()`, `storePrivate()`, `vBucketCdn()`, and more. | + +Usage: `Cdn::cdn('images/logo.png')` returns the CDN URL for the asset. diff --git a/src/Core/Cdn/Jobs/CLAUDE.md b/src/Core/Cdn/Jobs/CLAUDE.md new file mode 100644 index 0000000..edcb0a2 --- /dev/null +++ b/src/Core/Cdn/Jobs/CLAUDE.md @@ -0,0 +1,7 @@ +# Cdn/Jobs/ — CDN Background Jobs + +## Jobs + +| Job | Purpose | +|-----|---------| +| `PushAssetToCdn` | Queued job to push a local asset file to the CDN (BunnyCDN). Handles upload, verification, and StorageOffload record creation. | diff --git a/src/Core/Cdn/Middleware/CLAUDE.md b/src/Core/Cdn/Middleware/CLAUDE.md new file mode 100644 index 0000000..54a9335 --- /dev/null +++ b/src/Core/Cdn/Middleware/CLAUDE.md @@ -0,0 +1,8 @@ +# Cdn/Middleware/ — CDN HTTP Middleware + +## Middleware + +| Class | Purpose | +|-------|---------| +| `LocalCdnMiddleware` | Adds aggressive caching headers and compression for requests on the `cdn.*` subdomain. Provides CDN-like behaviour without external services. | +| `RewriteOffloadedUrls` | Processes JSON responses and replaces local storage paths with remote equivalents when files have been offloaded to external storage. | diff --git a/src/Core/Cdn/Models/CLAUDE.md b/src/Core/Cdn/Models/CLAUDE.md new file mode 100644 index 0000000..d7ed0ad --- /dev/null +++ b/src/Core/Cdn/Models/CLAUDE.md @@ -0,0 +1,7 @@ +# Cdn/Models/ — CDN Storage Models + +## Models + +| Model | Purpose | +|-------|---------| +| `StorageOffload` | Tracks files offloaded to remote storage. Records local path, remote path, disk, SHA-256 hash, file size, MIME type, category, metadata, and offload timestamp. Used by the URL rewriting middleware. | diff --git a/src/Core/Cdn/Services/CLAUDE.md b/src/Core/Cdn/Services/CLAUDE.md new file mode 100644 index 0000000..c0b54a1 --- /dev/null +++ b/src/Core/Cdn/Services/CLAUDE.md @@ -0,0 +1,13 @@ +# Cdn/Services/ — CDN Service Layer + +## Services + +| Service | Purpose | +|---------|---------| +| `BunnyCdnService` | BunnyCDN pull zone API — cache purging (URL, tag, workspace, global), statistics retrieval, pull zone management. Uses config from `ConfigService`. | +| `BunnyStorageService` | BunnyCDN storage zone API — file upload, download, delete, list. Supports public and private storage zones. | +| `StorageOffload` (service) | Manages file offloading to remote storage — upload, track, verify. Creates `StorageOffload` model records. | +| `StorageUrlResolver` | URL builder for all asset contexts — CDN, origin, private, signed, apex. Supports virtual buckets (vBucket) per domain. Backs the `Cdn` facade. | +| `CdnUrlBuilder` | Low-level URL construction for CDN paths with cache-busting and domain resolution. | +| `AssetPipeline` | Orchestrates asset processing — push to CDN, cache headers, versioning. | +| `FluxCdnService` | Pushes Flux UI assets to CDN for faster component loading. | diff --git a/src/Core/Cdn/Traits/CLAUDE.md b/src/Core/Cdn/Traits/CLAUDE.md new file mode 100644 index 0000000..063b873 --- /dev/null +++ b/src/Core/Cdn/Traits/CLAUDE.md @@ -0,0 +1,7 @@ +# Cdn/Traits/ — CDN Model Traits + +## Traits + +| Trait | Purpose | +|-------|---------| +| `HasCdnUrls` | For models with asset paths needing CDN URL resolution. Requires `$cdnPathAttribute` (attribute with storage path) and optional `$cdnBucket` (`public` or `private`). Provides `cdnUrl()` accessor. | diff --git a/src/Core/Config/Console/CLAUDE.md b/src/Core/Config/Console/CLAUDE.md new file mode 100644 index 0000000..c2178f0 --- /dev/null +++ b/src/Core/Config/Console/CLAUDE.md @@ -0,0 +1,13 @@ +# Config/Console/ — Config Artisan Commands + +Artisan commands for managing the hierarchical configuration system. + +## Commands + +| Command | Signature | Purpose | +|---------|-----------|---------| +| `ConfigListCommand` | `config:list` | List config keys with resolved values. Filters by workspace, category, or configured-only. | +| `ConfigPrimeCommand` | `config:prime` | Materialise resolved config into the fast-read table. Primes system and/or specific workspace. | +| `ConfigExportCommand` | `config:export` | Export config to JSON or YAML file. Supports workspace scope and sensitive value inclusion. | +| `ConfigImportCommand` | `config:import` | Import config from JSON or YAML file. Supports dry-run mode and automatic version snapshots. | +| `ConfigVersionCommand` | `config:version` | Manage config versions — list, create snapshots, show, rollback, and compare versions. | diff --git a/src/Core/Config/Contracts/CLAUDE.md b/src/Core/Config/Contracts/CLAUDE.md new file mode 100644 index 0000000..94bd0a3 --- /dev/null +++ b/src/Core/Config/Contracts/CLAUDE.md @@ -0,0 +1,9 @@ +# Config/Contracts/ — Config System Interfaces + +## Interfaces + +| Interface | Purpose | +|-----------|---------| +| `ConfigProvider` | Virtual configuration provider. Supplies config values at runtime without database storage. Matched against key patterns (e.g., `bio.*`). Registered via `ConfigResolver::registerProvider()`. | + +Providers implement `pattern()` (wildcard key matching) and `resolve()` (returns the value for a given key, workspace, and channel context). Returns `null` to fall through to database resolution. diff --git a/src/Core/Config/Database/Seeders/CLAUDE.md b/src/Core/Config/Database/Seeders/CLAUDE.md new file mode 100644 index 0000000..70d58fe --- /dev/null +++ b/src/Core/Config/Database/Seeders/CLAUDE.md @@ -0,0 +1,9 @@ +# Config/Database/Seeders/ — Config Key Seeders + +## Files + +| File | Purpose | +|------|---------| +| `ConfigKeySeeder.php` | Seeds known configuration keys into the `config_keys` table. Defines CDN (Bunny), storage (Hetzner S3), social, analytics, and bio settings with their types, categories, and defaults. Uses `firstOrCreate` for idempotency. | + +Part of the Config subsystem's M1 layer (key definitions). These keys are then assigned values via `ConfigValue` at system or workspace scope. diff --git a/src/Core/Config/Enums/CLAUDE.md b/src/Core/Config/Enums/CLAUDE.md new file mode 100644 index 0000000..1a5f3f8 --- /dev/null +++ b/src/Core/Config/Enums/CLAUDE.md @@ -0,0 +1,12 @@ +# Config/Enums/ — Config Type System + +Backed enums for the configuration system's type safety and scope hierarchy. + +## Enums + +| Enum | Values | Purpose | +|------|--------|---------| +| `ConfigType` | STRING, BOOL, INT, FLOAT, ARRAY, JSON | Determines how config values are cast and validated. Has `cast()` and `default()` methods. | +| `ScopeType` | SYSTEM, ORG, WORKSPACE | Defines the inheritance hierarchy. Resolution order: workspace (priority 20) > org (10) > system (0). | + +`ScopeType::resolutionOrder()` returns scopes from most specific to least specific for cascade resolution. diff --git a/src/Core/Config/Events/CLAUDE.md b/src/Core/Config/Events/CLAUDE.md new file mode 100644 index 0000000..31f4c1c --- /dev/null +++ b/src/Core/Config/Events/CLAUDE.md @@ -0,0 +1,13 @@ +# Config/Events/ — Config System Events + +Events dispatched by the configuration system for reactive integration. + +## Events + +| Event | Fired When | Key Properties | +|-------|-----------|----------------| +| `ConfigChanged` | A config value is set or updated via `ConfigService::set()` | `keyCode`, `value`, `previousValue`, `profile`, `channelId` | +| `ConfigInvalidated` | Config cache is manually cleared | `keyCode` (null = all), `workspaceId`, `channelId`. Has `isFull()` and `affectsKey()` helpers. | +| `ConfigLocked` | A config value is locked (FINAL) | `keyCode`, `profile`, `channelId` | + +Modules can listen to these events via the standard `$listens` pattern in their Boot class to react to config changes (e.g., refreshing CDN clients, flushing caches). diff --git a/src/Core/Config/Migrations/CLAUDE.md b/src/Core/Config/Migrations/CLAUDE.md new file mode 100644 index 0000000..9a986a3 --- /dev/null +++ b/src/Core/Config/Migrations/CLAUDE.md @@ -0,0 +1,14 @@ +# Config/Migrations/ — Config Schema Migrations + +Database migrations for the hierarchical configuration system. + +## Migrations + +| File | Purpose | +|------|---------| +| `0001_01_01_000001_create_config_tables.php` | Creates core config tables: `config_keys`, `config_profiles`, `config_values`, `config_channels`, `config_resolved`. | +| `0001_01_01_000002_add_soft_deletes_to_config_profiles.php` | Adds soft delete support to `config_profiles`. | +| `0001_01_01_000003_add_is_sensitive_to_config_keys.php` | Adds `is_sensitive` flag for automatic encryption of values. | +| `0001_01_01_000004_create_config_versions_table.php` | Creates `config_versions` table for point-in-time snapshots and rollback. | + +Uses early timestamps (`0001_01_01_*`) to run before application migrations. diff --git a/src/Core/Config/Models/CLAUDE.md b/src/Core/Config/Models/CLAUDE.md new file mode 100644 index 0000000..2be24c2 --- /dev/null +++ b/src/Core/Config/Models/CLAUDE.md @@ -0,0 +1,22 @@ +# Config/Models/ — Config Eloquent Models + +Eloquent models implementing the four-layer hierarchical configuration system. + +## Models + +| Model | Table | Purpose | +|-------|-------|---------| +| `ConfigKey` | `config_keys` | M1 layer — defines what keys exist. Dot-notation codes, typed (`ConfigType`), categorised. Supports sensitive flag for auto-encryption. Hierarchical parent/child grouping. | +| `ConfigProfile` | `config_profiles` | M2 layer — groups values at a scope level (system/org/workspace). Inherits from parent profiles. Soft-deletable. | +| `ConfigValue` | `config_values` | Junction table linking profiles to keys with actual values. `locked` flag implements FINAL (prevents child override). Auto-encrypts sensitive keys. Invalidates resolver hash on write. | +| `ConfigVersion` | `config_versions` | Point-in-time snapshots for version history and rollback. Immutable (no `updated_at`). Stores JSON snapshot of all values. | +| `Channel` | `config_channels` | Context dimension (web, api, mobile, instagram, etc.). Hierarchical inheritance chain with cycle detection. System or workspace-scoped. | +| `ConfigResolved` | `config_resolved` | Materialised READ table — all lookups hit this directly. No computation at read time. Populated by the `prime` operation. Composite key (workspace_id, channel_id, key_code). | + +## Resolution Flow + +``` +ConfigService::get() → ConfigResolved (fast lookup) + → miss: ConfigResolver computes from ConfigValue chain + → stores result back to ConfigResolved + in-memory hash +``` diff --git a/src/Core/Config/Routes/CLAUDE.md b/src/Core/Config/Routes/CLAUDE.md new file mode 100644 index 0000000..cddbdd9 --- /dev/null +++ b/src/Core/Config/Routes/CLAUDE.md @@ -0,0 +1,7 @@ +# Config/Routes/ — Config Admin Routes + +## Files + +| File | Purpose | +|------|---------| +| `admin.php` | Admin route definitions for the configuration panel. Registers routes under the `admin` middleware group for the `ConfigPanel` and `WorkspaceConfig` Livewire components. | diff --git a/src/Core/Config/Tests/Feature/CLAUDE.md b/src/Core/Config/Tests/Feature/CLAUDE.md new file mode 100644 index 0000000..08490c3 --- /dev/null +++ b/src/Core/Config/Tests/Feature/CLAUDE.md @@ -0,0 +1,11 @@ +# Config/Tests/Feature/ — Config Integration Tests + +Pest feature tests for the hierarchical configuration system. + +## Test Files + +| File | Purpose | +|------|---------| +| `ConfigServiceTest.php` | Full integration tests covering ConfigKey creation, ConfigProfile inheritance, ConfigResolver scope cascading, FINAL lock enforcement, ConfigService materialised reads/writes, ConfigResolved storage, and the single-hash lazy-load pattern. | + +Tests cover the complete config lifecycle: key definition, profile hierarchy (system/workspace), value resolution with inheritance, lock semantics, cache invalidation, and the prime/materialise flow. diff --git a/src/Core/Config/View/Blade/admin/CLAUDE.md b/src/Core/Config/View/Blade/admin/CLAUDE.md new file mode 100644 index 0000000..6a981a5 --- /dev/null +++ b/src/Core/Config/View/Blade/admin/CLAUDE.md @@ -0,0 +1,12 @@ +# Config/View/Blade/admin/ — Config Admin Blade Templates + +Blade templates for the admin configuration panel. + +## Templates + +| File | Purpose | +|------|---------| +| `config-panel.blade.php` | Full config management panel — browse keys by category, edit values, toggle locks, manage system vs workspace scopes. Used by `ConfigPanel` Livewire component. | +| `workspace-config.blade.php` | Workspace-specific config panel — hierarchical namespace navigation, tab grouping, value editing with system inheritance display. Used by `WorkspaceConfig` Livewire component. | + +Both templates use the `hub::admin.layouts.app` layout and are rendered via the `core.config::admin.*` view namespace. diff --git a/src/Core/Config/View/Modal/Admin/CLAUDE.md b/src/Core/Config/View/Modal/Admin/CLAUDE.md new file mode 100644 index 0000000..f68ae4a --- /dev/null +++ b/src/Core/Config/View/Modal/Admin/CLAUDE.md @@ -0,0 +1,12 @@ +# Config/View/Modal/Admin/ — Config Admin Livewire Components + +Livewire components for the admin configuration interface. + +## Components + +| Component | Purpose | +|-----------|---------| +| `ConfigPanel` | Hades-only config management. Browse/search keys by category, edit values inline, toggle FINAL locks, manage system and workspace scopes. Respects parent lock enforcement. | +| `WorkspaceConfig` | Workspace-scoped settings. Hierarchical namespace navigation (cdn/bunny/storage), tab grouping by second-level prefix, value editing with inherited value display, system lock indicators. | + +Both require the Tenant module for workspace support and fall back gracefully without it. `ConfigPanel` requires Hades (super-admin) access. Values are persisted via `ConfigService`. diff --git a/src/Core/Console/Commands/CLAUDE.md b/src/Core/Console/Commands/CLAUDE.md new file mode 100644 index 0000000..52da328 --- /dev/null +++ b/src/Core/Console/Commands/CLAUDE.md @@ -0,0 +1,15 @@ +# Console/Commands/ — Core Framework Commands + +Artisan commands for framework scaffolding and maintenance. + +## Commands + +| Command | Signature | Purpose | +|---------|-----------|---------| +| `InstallCommand` | `core:install` | Framework installation wizard — sets up sensible defaults for new projects. | +| `MakeModCommand` | `core:make-mod` | Generates a new module scaffold in the `Mod` namespace with Boot.php event-driven loading pattern. | +| `MakePlugCommand` | `core:make-plug` | Generates a new plugin scaffold in the `Plug` namespace. | +| `MakeWebsiteCommand` | `core:make-website` | Generates a new website module scaffold in the `Website` namespace. | +| `NewProjectCommand` | `core:new` | Creates a complete new project from the Core PHP template. | +| `PruneEmailShieldStatsCommand` | `emailshield:prune` | Prunes old EmailShield validation statistics. | +| `ScheduleSyncCommand` | `core:schedule-sync` | Synchronises scheduled tasks across the application. | diff --git a/src/Core/Database/Seeders/Attributes/CLAUDE.md b/src/Core/Database/Seeders/Attributes/CLAUDE.md new file mode 100644 index 0000000..0744a81 --- /dev/null +++ b/src/Core/Database/Seeders/Attributes/CLAUDE.md @@ -0,0 +1,27 @@ +# Database/Seeders/Attributes/ — Seeder Ordering Attributes + +PHP 8 attributes for controlling seeder execution order in the auto-discovery system. + +## Attributes + +| Attribute | Target | Purpose | +|-----------|--------|---------| +| `#[SeederAfter(...)]` | Class | This seeder must run after the specified seeders. Repeatable. | +| `#[SeederBefore(...)]` | Class | This seeder must run before the specified seeders. Repeatable. | +| `#[SeederPriority(n)]` | Class | Numeric priority (lower runs first, default 50). | + +## Priority Guidelines + +- 0-20: Foundation (features, configuration) +- 20-40: Core data (packages, workspaces) +- 40-60: Default (general seeders) +- 60-80: Content (pages, posts) +- 80-100: Demo/test data + +## Example + +```php +#[SeederAfter(FeatureSeeder::class)] +#[SeederPriority(30)] +class PackageSeeder extends Seeder { ... } +``` diff --git a/src/Core/Database/Seeders/Exceptions/CLAUDE.md b/src/Core/Database/Seeders/Exceptions/CLAUDE.md new file mode 100644 index 0000000..e347f80 --- /dev/null +++ b/src/Core/Database/Seeders/Exceptions/CLAUDE.md @@ -0,0 +1,9 @@ +# Database/Seeders/Exceptions/ — Seeder Exception Types + +## Files + +| File | Purpose | +|------|---------| +| `CircularDependencyException.php` | Thrown when seeder dependency graph contains a cycle. Includes the `$cycle` array showing the loop path. Has `fromPath()` factory for building from a traversal path. | + +Part of the seeder auto-discovery system. The `CoreDatabaseSeeder` uses topological sorting on `#[SeederAfter]`/`#[SeederBefore]` attributes and throws this when a cycle is detected. diff --git a/src/Core/Events/Concerns/CLAUDE.md b/src/Core/Events/Concerns/CLAUDE.md new file mode 100644 index 0000000..54f9296 --- /dev/null +++ b/src/Core/Events/Concerns/CLAUDE.md @@ -0,0 +1,9 @@ +# Events/Concerns/ — Event Version Compatibility + +## Traits + +| Trait | Purpose | +|-------|---------| +| `HasEventVersion` | For Boot classes to declare which event API versions they support. Methods: `getRequiredEventVersion(eventClass)`, `isCompatibleWithEventVersion(eventClass, version)`, `getEventVersionRequirements()`. | + +Enables graceful handling of event API changes. Modules declare minimum versions via `$eventVersions` static property. The framework checks compatibility during bootstrap and logs warnings for version mismatches. diff --git a/src/Core/Front/Admin/Blade/components/CLAUDE.md b/src/Core/Front/Admin/Blade/components/CLAUDE.md new file mode 100644 index 0000000..29705d7 --- /dev/null +++ b/src/Core/Front/Admin/Blade/components/CLAUDE.md @@ -0,0 +1,38 @@ +# Front/Admin/Blade/components + +Anonymous Blade components for the admin panel. Used via `` tag syntax. + +## Components + +| Component | Purpose | +|-----------|---------| +| action-link | Styled link for table row actions | +| activity-feed | Template for ActivityFeed class component | +| activity-log | Template for ActivityLog class component | +| alert | Template for Alert class component | +| card-grid | Template for CardGrid class component | +| clear-filters | Template for ClearFilters class component | +| data-table | Template for DataTable class component | +| editable-table | Template for EditableTable class component | +| empty-state | Empty state placeholder with icon and message | +| entitlement-gate | Conditionally renders content based on workspace entitlements | +| filter / filter-bar | Template for Filter/FilterBar class components | +| flash | Session flash message display | +| header | Page header with breadcrumbs and actions | +| link-grid | Template for LinkGrid class component | +| manager-table | Template for ManagerTable class component | +| metric-card / metrics | Individual metric card and grid template | +| module | Module wrapper with loading states | +| nav-group / nav-item / nav-link / nav-menu / nav-panel | Sidebar navigation primitives | +| page-header | Page title bar with optional subtitle and actions | +| panel | Content panel with optional header/footer | +| progress-list | Template for ProgressList class component | +| search | Template for Search class component | +| service-card / service-cards | Service overview cards | +| sidebar / sidemenu | Sidebar shell and menu template | +| stat-card / stats | Individual stat card and grid template | +| status-cards | Template for StatusCards class component | +| tabs | Tab navigation wrapper using `` | +| workspace-card | Workspace overview card | + +Most are templates for the class-backed components in `View/Components/`. A few are standalone anonymous components (empty-state, entitlement-gate, flash, nav-*, page-header, panel, workspace-card). diff --git a/src/Core/Front/Admin/Blade/components/tabs/CLAUDE.md b/src/Core/Front/Admin/Blade/components/tabs/CLAUDE.md new file mode 100644 index 0000000..99968dc --- /dev/null +++ b/src/Core/Front/Admin/Blade/components/tabs/CLAUDE.md @@ -0,0 +1,22 @@ +# Front/Admin/Blade/components/tabs + +Tab panel sub-component for admin tabs. + +## Files + +- **panel.blade.php** -- Individual tab panel that auto-detects selected state from `TabContext::$selected`. Wraps `` with automatic selection. + - Props: `name` (string, required) -- must match the tab key + - Reads `\Core\Front\Admin\TabContext::$selected` to determine visibility + +## Usage + +```blade + + + General settings content + + + Advanced settings content + + +``` diff --git a/src/Core/Front/Admin/Blade/layouts/CLAUDE.md b/src/Core/Front/Admin/Blade/layouts/CLAUDE.md new file mode 100644 index 0000000..22ff106 --- /dev/null +++ b/src/Core/Front/Admin/Blade/layouts/CLAUDE.md @@ -0,0 +1,10 @@ +# Front/Admin/Blade/layouts + +Layout templates for the admin panel. + +## Files + +- **app.blade.php** -- Full admin HTML shell with sidebar + content area layout. Includes dark mode (localStorage + cookie sync), FontAwesome Pro CSS, Vite assets (admin.css + app.js), Flux appearance/scripts, collapsible sidebar with `sidebarExpanded` Alpine state (persisted to localStorage), and light/dark mode toggle script. + - Props: `title` (string, default 'Admin') + - Slots: `$sidebar` (sidebar component), `$header` (top header), `$slot` (main content), `$head` (extra head content), `$scripts` (extra scripts) + - Responsive: sidebar hidden on mobile, 20px collapsed / 64px expanded on desktop. diff --git a/src/Core/Front/Admin/CLAUDE.md b/src/Core/Front/Admin/CLAUDE.md new file mode 100644 index 0000000..5678908 --- /dev/null +++ b/src/Core/Front/Admin/CLAUDE.md @@ -0,0 +1,24 @@ +# Front/Admin + +Admin panel frontage. Service provider that configures the `admin` middleware group, registers `` Blade tag syntax, and boots 18 class-backed view components. + +## Files + +- **Boot.php** -- ServiceProvider configuring the `admin` middleware stack (separate from web -- includes `auth`). Registers `admin::` Blade namespace, class component aliases (e.g., `admin-data-table`), `` tag compiler, and fires `AdminPanelBooting` lifecycle event. Binds `AdminMenuRegistry` as singleton. +- **AdminMenuRegistry.php** -- Central registry for admin sidebar navigation. Modules register `AdminMenuProvider` implementations during boot. Handles entitlement checks, permission filtering, caching (5min TTL), priority sorting, and menu structure building with groups: dashboard, agents, workspaces, services, settings, admin. +- **AdminTagCompiler.php** -- Blade precompiler for `` tags. Resolves class-backed components first (via `admin-xyz` aliases), falls back to anonymous `admin::xyz` namespace. +- **TabContext.php** -- Static context for `` to communicate selected state to child `` components. + +## Middleware Stack + +The `admin` group: EncryptCookies, AddQueuedCookiesToResponse, StartSession, ShareErrorsFromSession, ValidateCsrfToken, SubstituteBindings, SecurityHeaders, auth. + +## Tag Syntax + +```blade + + + + Content + +``` diff --git a/src/Core/Front/Admin/Concerns/CLAUDE.md b/src/Core/Front/Admin/Concerns/CLAUDE.md new file mode 100644 index 0000000..424dc3a --- /dev/null +++ b/src/Core/Front/Admin/Concerns/CLAUDE.md @@ -0,0 +1,7 @@ +# Front/Admin/Concerns + +Traits for admin panel functionality. + +## Files + +- **HasMenuPermissions.php** -- Default implementation of `AdminMenuProvider` permission methods. Provides `menuPermissions()` (returns empty array by default), `canViewMenu()` (checks all permissions from `menuPermissions()` against the user), and `userHasPermission()` (tries Laravel Gate `can()`, then `hasPermission()`, then Spatie's `hasPermissionTo()`, falls back to allow). Include this trait in classes implementing `AdminMenuProvider` to get sensible defaults; override methods for custom logic. diff --git a/src/Core/Front/Admin/Contracts/CLAUDE.md b/src/Core/Front/Admin/Contracts/CLAUDE.md new file mode 100644 index 0000000..f2ab40c --- /dev/null +++ b/src/Core/Front/Admin/Contracts/CLAUDE.md @@ -0,0 +1,17 @@ +# Front/Admin/Contracts + +Interfaces for the admin menu system. + +## Files + +- **AdminMenuProvider.php** -- Interface for modules contributing admin sidebar items. Defines priority constants (FIRST=0 through LAST=90), `adminMenuItems()` returning registration arrays with group/priority/entitlement/permissions/item closure, `menuPermissions()` for provider-level permission requirements, and `canViewMenu()` for custom access logic. Items are lazy-evaluated -- closures only called after permission checks pass. + +- **DynamicMenuProvider.php** -- Interface for providers supplying uncached, real-time menu items (e.g., notification counts, recent items). `dynamicMenuItems()` is called every request and merged after static cache retrieval. `dynamicCacheKey()` can invalidate static cache when dynamic state changes significantly. + +## Menu Groups + +`dashboard` | `workspaces` | `services` | `settings` | `admin` + +## Priority Constants + +PRIORITY_FIRST(0), PRIORITY_HIGH(10), PRIORITY_ABOVE_NORMAL(20), PRIORITY_NORMAL(50), PRIORITY_BELOW_NORMAL(70), PRIORITY_LOW(80), PRIORITY_LAST(90). diff --git a/src/Core/Front/Admin/Support/CLAUDE.md b/src/Core/Front/Admin/Support/CLAUDE.md new file mode 100644 index 0000000..9c11286 --- /dev/null +++ b/src/Core/Front/Admin/Support/CLAUDE.md @@ -0,0 +1,25 @@ +# Front/Admin/Support + +Builder utilities for constructing admin menu items. + +## Files + +- **MenuItemBuilder.php** -- Fluent builder for `AdminMenuProvider::adminMenuItems()` return arrays. Chainable API: `MenuItemBuilder::make('Label')->icon('cube')->href('/path')->inGroup('services')->entitlement('core.srv.x')->build()`. Supports route-based hrefs, active state callbacks (`activeOnRoute('hub.bio.*')`), children, badges, priority shortcuts (`->first()`, `->high()`, `->last()`), service keys, and custom attributes. + +- **MenuItemGroup.php** -- Static factory for structural menu elements within children arrays. Creates separators (`::separator()`), section headers (`::header('Products', 'cube')`), collapsible groups (`::collapsible('Orders', $children)`), and dividers (`::divider('More')`). Also provides type-check helpers: `isSeparator()`, `isHeader()`, `isCollapsible()`, `isDivider()`, `isStructural()`, `isLink()`. + +## Usage + +```php +MenuItemBuilder::make('Commerce') + ->icon('shopping-cart') + ->inServices() + ->entitlement('core.srv.commerce') + ->children([ + MenuItemGroup::header('Products', 'cube'), + MenuItemBuilder::child('All Products', '/products')->icon('list'), + MenuItemGroup::separator(), + MenuItemBuilder::child('Orders', '/orders')->icon('receipt'), + ]) + ->build(); +``` diff --git a/src/Core/Front/Admin/Validation/CLAUDE.md b/src/Core/Front/Admin/Validation/CLAUDE.md new file mode 100644 index 0000000..8eb27b6 --- /dev/null +++ b/src/Core/Front/Admin/Validation/CLAUDE.md @@ -0,0 +1,13 @@ +# Front/Admin/Validation + +Validation utilities for admin panel configuration. + +## Files + +- **IconValidator.php** -- Validates FontAwesome icon names used in admin menu items. Accepts shorthand (`home`), prefixed (`fa-home`), and full class (`fas fa-home`, `fa-solid fa-home`, `fab fa-github`) formats. Normalises all formats to base name. Contains built-in lists of ~200 solid icons and ~80 brand icons. Supports custom icons (`addCustomIcon()`), icon packs (`registerIconPack()`), and strict mode (config `core.admin_menu.strict_icon_validation`). Non-strict mode (default) allows unknown icons with optional warnings. Provides Levenshtein-based suggestions for misspelled icons (`getSuggestions()`). + +## Configuration + +- `core.admin_menu.strict_icon_validation` -- Reject unknown icons (default: false) +- `core.admin_menu.log_icon_warnings` -- Log warnings for unknown icons (default: true) +- `core.admin_menu.custom_icons` -- Array of additional valid icon names diff --git a/src/Core/Front/Admin/View/Components/CLAUDE.md b/src/Core/Front/Admin/View/Components/CLAUDE.md new file mode 100644 index 0000000..3228aa6 --- /dev/null +++ b/src/Core/Front/Admin/View/Components/CLAUDE.md @@ -0,0 +1,28 @@ +# Front/Admin/View/Components + +Class-backed Blade components for the admin panel. Registered via `` tag syntax in Boot.php. + +## Components + +| Component | Tag | Purpose | +|-----------|-----|---------| +| ActivityFeed | `` | Timeline of recent activity items with icons and timestamps | +| ActivityLog | `` | Detailed activity log with filtering | +| Alert | `` | Dismissible alert/notification banners | +| CardGrid | `` | Responsive grid of cards | +| ClearFilters | `` | Button to reset active table/list filters | +| DataTable | `` | Table with columns, rows, title, empty state, and action link | +| EditableTable | `` | Inline-editable table rows | +| Filter | `` | Single filter control (select, input, etc.) | +| FilterBar | `` | Horizontal bar of filter controls | +| LinkGrid | `` | Grid of navigational link cards | +| ManagerTable | `` | CRUD management table with actions | +| Metrics | `` | Grid of metric cards (configurable columns: 2-4) | +| ProgressList | `` | List of items with progress indicators | +| Search | `` | Search input with Livewire integration | +| ServiceCard | `` | Card displaying a service's status, stats, and actions | +| Sidemenu | `` | Sidebar navigation built from AdminMenuRegistry | +| Stats | `` | Grid of stat cards (configurable columns: 2-6) | +| StatusCards | `` | Cards showing system/service status | + +All components extend `Illuminate\View\Component` and render via Blade templates in `Admin/Blade/components/`. diff --git a/src/Core/Front/Cli/CLAUDE.md b/src/Core/Front/Cli/CLAUDE.md new file mode 100644 index 0000000..79ef688 --- /dev/null +++ b/src/Core/Front/Cli/CLAUDE.md @@ -0,0 +1,16 @@ +# Front/Cli + +CLI/Artisan frontage. Fires `ConsoleBooting` lifecycle event and processes module registrations. + +## Files + +- **Boot.php** -- ServiceProvider that only runs in console context. Registers the `ScheduleServiceProvider`, fires `ConsoleBooting` event, then processes module requests collected by the event: Artisan commands, translations, middleware aliases, Gate policies, and Blade component paths. This is how modules register CLI-specific resources without coupling to the console context directly. + +## Event-Driven Registration + +Modules listen for `ConsoleBooting` and call methods on the event to register: +- `commandRequests()` -- Artisan command classes +- `translationRequests()` -- `[namespace, path]` pairs +- `middlewareRequests()` -- `[alias, class]` pairs +- `policyRequests()` -- `[model, policy]` pairs +- `bladeComponentRequests()` -- `[path, namespace]` pairs diff --git a/src/Core/Front/Components/CLAUDE.md b/src/Core/Front/Components/CLAUDE.md new file mode 100644 index 0000000..faf5106 --- /dev/null +++ b/src/Core/Front/Components/CLAUDE.md @@ -0,0 +1,32 @@ +# Front/Components + +Core UI component system. Provides `` Blade tag syntax and data-driven PHP component builders for programmatic UI composition. + +## Files + +- **Boot.php** -- ServiceProvider registering multiple Blade namespaces: `core::` (core components + `` tags), `layouts::` (Livewire layout resolution), `front::` (front-end satellite components), `errors::` (error pages). Adds blade view paths for Livewire's `->layout()` resolution. +- **CoreTagCompiler.php** -- Blade precompiler for `` tag syntax. Compiles to `core::` anonymous components. +- **Component.php** -- Abstract base for data-driven UI components. Fluent interface with `attr()`, `class()`, `id()`, `buildAttributes()`. Implements `Htmlable`. Used by MCP tools and agents to compose UIs without Blade templates. +- **Button.php** -- Button builder. Variants: primary, secondary, danger, ghost. Sizes: sm, md, lg. Supports link buttons (`href()`), disabled state, submit type. +- **Card.php** -- Card builder with title, description, body content, and action buttons in footer. +- **Heading.php** -- Heading builder (h1-h6) with optional description subtitle. Size classes auto-mapped from level. +- **Layout.php** -- HLCRF Layout Compositor. Data-driven layout builder where H=Header, L=Left, C=Content, R=Right, F=Footer. Variant string defines which slots exist (e.g., `'HLCF'`, `'HCF'`, `'HC'`). Supports nesting and hierarchical path tracking. +- **NavList.php** -- Navigation list builder with heading, items (label + href + icon + active), and dividers. +- **Text.php** -- Text builder. Tags: span, p, div. Variants: default, muted, success, warning, error. + +## Tag Syntax + +```blade + +... +``` + +## Programmatic Usage + +```php +Layout::make('HLCF') + ->h('') + ->l(NavList::make()->item('Dashboard', '/hub')) + ->c(Card::make()->title('Settings')->body('Content')) + ->f('
Links
'); +``` diff --git a/src/Core/Front/Components/View/Blade/CLAUDE.md b/src/Core/Front/Components/View/Blade/CLAUDE.md new file mode 100644 index 0000000..99afa9a --- /dev/null +++ b/src/Core/Front/Components/View/Blade/CLAUDE.md @@ -0,0 +1,62 @@ +# Components/View/Blade + +Root directory for all core anonymous Blade components. Registered under the `core::` namespace and accessible via `` tag syntax. + +## Top-Level Components (48 files) + +Each `.blade.php` file is the parent component. Sub-components live in matching subdirectories. + +| Component | Description | +|-----------|-------------| +| accordion | Collapsible content sections | +| autocomplete | Typeahead search input | +| avatar | User/entity avatar display | +| badge | Status/count badge | +| button | Action button (primary, secondary, danger, ghost) | +| calendar | Calendar date display | +| callout | Notice/alert box | +| card | Content card container | +| chart | SVG chart container | +| checkbox | Checkbox input | +| command | Command palette (Cmd+K) | +| composer | Content composer/editor wrapper | +| context | Context menu | +| date-picker | Date selection input | +| description | Description list/text | +| dropdown | Dropdown menu trigger | +| editor | Rich text editor | +| error | Inline error message | +| field | Form field wrapper (label + input + error) | +| file-item | File list item display | +| file-upload | File upload input | +| heading | Section heading (h1-h6) | +| icon | FontAwesome icon renderer | +| input | Text input | +| kanban | Kanban board | +| label | Form label | +| layout | HLCRF layout container | +| main | Main content area | +| menu | Dropdown menu panel | +| modal | Modal dialog | +| navbar | Navigation bar | +| navlist | Navigation list (sidebar) | +| navmenu | Navigation menu | +| pillbox | Tag/chip multi-select input | +| popover | Popover tooltip/panel | +| radio | Radio button input | +| select | Dropdown select | +| separator | Visual divider | +| slider | Range slider input | +| subheading | Secondary heading text | +| switch | Toggle switch | +| tab | Tab trigger | +| table | Data table | +| tabs | Tab container with panels | +| text | Body text | +| textarea | Multi-line text input | +| time-picker | Time selection input | +| tooltip | Hover tooltip | + +## Subdirectories + +Each subdirectory contains sub-components (e.g., `table/row.blade.php` = ``). See individual `CLAUDE.md` files in each subdirectory. diff --git a/src/Core/Front/Components/View/Blade/accordion/CLAUDE.md b/src/Core/Front/Components/View/Blade/accordion/CLAUDE.md new file mode 100644 index 0000000..c2297e9 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/accordion/CLAUDE.md @@ -0,0 +1,20 @@ +# Blade/accordion + +Accordion (collapsible section) components. + +## Files + +- **content.blade.php** -- Collapsible content panel of an accordion item. Hidden/shown based on accordion state. +- **heading.blade.php** -- Clickable header that toggles the accordion item's content visibility. +- **item.blade.php** -- Single accordion item wrapping a heading + content pair. + +## Usage + +```blade + + + Section Title + Hidden content here + + +``` diff --git a/src/Core/Front/Components/View/Blade/autocomplete/CLAUDE.md b/src/Core/Front/Components/View/Blade/autocomplete/CLAUDE.md new file mode 100644 index 0000000..8e397c2 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/autocomplete/CLAUDE.md @@ -0,0 +1,7 @@ +# Blade/autocomplete + +Autocomplete sub-components. + +## Files + +- **item.blade.php** -- Individual autocomplete suggestion item. Rendered within an autocomplete dropdown list. diff --git a/src/Core/Front/Components/View/Blade/button/CLAUDE.md b/src/Core/Front/Components/View/Blade/button/CLAUDE.md new file mode 100644 index 0000000..289cf44 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/button/CLAUDE.md @@ -0,0 +1,7 @@ +# Blade/button + +Button sub-components. + +## Files + +- **group.blade.php** -- Button group container. Renders multiple buttons inline with shared styling (connected borders, uniform spacing). diff --git a/src/Core/Front/Components/View/Blade/callout/CLAUDE.md b/src/Core/Front/Components/View/Blade/callout/CLAUDE.md new file mode 100644 index 0000000..7bc636f --- /dev/null +++ b/src/Core/Front/Components/View/Blade/callout/CLAUDE.md @@ -0,0 +1,17 @@ +# Blade/callout + +Callout (notice/alert box) sub-components. + +## Files + +- **heading.blade.php** -- Callout title/heading text +- **text.blade.php** -- Callout body text/description + +## Usage + +```blade + + Note + Important information here. + +``` diff --git a/src/Core/Front/Components/View/Blade/chart/CLAUDE.md b/src/Core/Front/Components/View/Blade/chart/CLAUDE.md new file mode 100644 index 0000000..5c537d5 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/chart/CLAUDE.md @@ -0,0 +1,33 @@ +# Blade/chart + +SVG chart components for data visualisation. + +## Files + +- **area.blade.php** -- Area chart (filled line chart) +- **axis.blade.php** -- Chart axis container +- **cursor.blade.php** -- Interactive cursor/crosshair overlay +- **legend.blade.php** -- Chart legend +- **line.blade.php** -- Line chart series +- **point.blade.php** -- Data point marker +- **summary.blade.php** -- Chart summary/stats display +- **svg.blade.php** -- SVG container wrapper +- **tooltip.blade.php** -- Hover tooltip container +- **viewport.blade.php** -- Viewable chart area with coordinate system + +## Subdirectories + +- **tooltip/** -- `heading.blade.php` (tooltip title), `value.blade.php` (tooltip data value) +- **axis/** -- `grid.blade.php` (grid lines), `line.blade.php` (axis line), `mark.blade.php` (axis label), `tick.blade.php` (tick mark) + +## Usage + +```blade + + + + + + + +``` diff --git a/src/Core/Front/Components/View/Blade/chart/axis/CLAUDE.md b/src/Core/Front/Components/View/Blade/chart/axis/CLAUDE.md new file mode 100644 index 0000000..7c30c76 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/chart/axis/CLAUDE.md @@ -0,0 +1,12 @@ +# Blade/chart/axis + +Chart axis sub-components for rendering axis elements. + +## Files + +- **grid.blade.php** -- Background grid lines aligned to axis ticks +- **line.blade.php** -- The axis line itself (horizontal or vertical) +- **mark.blade.php** -- Axis label/mark text (e.g., "Jan", "Feb", "100", "200") +- **tick.blade.php** -- Small tick marks along the axis + +Used within `` to compose axis rendering. diff --git a/src/Core/Front/Components/View/Blade/chart/tooltip/CLAUDE.md b/src/Core/Front/Components/View/Blade/chart/tooltip/CLAUDE.md new file mode 100644 index 0000000..7e9dc49 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/chart/tooltip/CLAUDE.md @@ -0,0 +1,10 @@ +# Blade/chart/tooltip + +Chart tooltip sub-components. + +## Files + +- **heading.blade.php** -- Tooltip title/heading text (e.g., date or category label) +- **value.blade.php** -- Tooltip data value display (e.g., "1,234 visitors") + +Used within `` to structure hover information. diff --git a/src/Core/Front/Components/View/Blade/checkbox/CLAUDE.md b/src/Core/Front/Components/View/Blade/checkbox/CLAUDE.md new file mode 100644 index 0000000..b19ffe7 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/checkbox/CLAUDE.md @@ -0,0 +1,7 @@ +# Blade/checkbox + +Checkbox sub-components. + +## Files + +- **group.blade.php** -- Checkbox group container. Wraps multiple checkbox inputs with shared layout and optional label. diff --git a/src/Core/Front/Components/View/Blade/command/CLAUDE.md b/src/Core/Front/Components/View/Blade/command/CLAUDE.md new file mode 100644 index 0000000..7bdc365 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/command/CLAUDE.md @@ -0,0 +1,23 @@ +# Blade/command + +Command palette (Cmd+K) sub-components. + +## Files + +- **empty.blade.php** -- Empty state shown when no results match the search query +- **input.blade.php** -- Search input field within the command palette +- **item.blade.php** -- Individual command/action item in the results list +- **items.blade.php** -- Results list container wrapping command items + +## Usage + +```blade + + + + Go to Dashboard + Create New... + + No results found + +``` diff --git a/src/Core/Front/Components/View/Blade/components/satellite/CLAUDE.md b/src/Core/Front/Components/View/Blade/components/satellite/CLAUDE.md new file mode 100644 index 0000000..07fa734 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/components/satellite/CLAUDE.md @@ -0,0 +1,10 @@ +# Blade/components/satellite + +Satellite site layout components for workspace-branded pages (e.g., bio links, landing pages). + +## Files + +- **footer-custom.blade.php** -- Custom footer for satellite sites with workspace branding, social links, custom links, contact info, and copyright. Supports configurable footer settings (show_default_links, position, custom_content). +- **layout.blade.php** -- Full HTML shell for satellite/workspace sites. Includes dark mode, meta tags, workspace branding, configurable footer. Used for public workspace pages served on custom domains or subdomains. + +These are registered under the `front::` namespace via ``. diff --git a/src/Core/Front/Components/View/Blade/date-picker/CLAUDE.md b/src/Core/Front/Components/View/Blade/date-picker/CLAUDE.md new file mode 100644 index 0000000..d96083c --- /dev/null +++ b/src/Core/Front/Components/View/Blade/date-picker/CLAUDE.md @@ -0,0 +1,8 @@ +# Blade/date-picker + +Date picker sub-components. + +## Files + +- **button.blade.php** -- Trigger button that opens the date picker calendar popover. +- **input.blade.php** -- Text input field displaying the selected date value, with date picker integration. diff --git a/src/Core/Front/Components/View/Blade/editor/CLAUDE.md b/src/Core/Front/Components/View/Blade/editor/CLAUDE.md new file mode 100644 index 0000000..7d313b1 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/editor/CLAUDE.md @@ -0,0 +1,22 @@ +# Blade/editor + +Rich text editor sub-components. + +## Files + +- **button.blade.php** -- Toolbar action button (bold, italic, link, etc.) +- **content.blade.php** -- Editable content area (the actual rich text editing surface) +- **toolbar.blade.php** -- Editor toolbar container wrapping action buttons + +## Usage + +```blade + + + + + + + + +``` diff --git a/src/Core/Front/Components/View/Blade/errors/CLAUDE.md b/src/Core/Front/Components/View/Blade/errors/CLAUDE.md new file mode 100644 index 0000000..112f184 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/errors/CLAUDE.md @@ -0,0 +1,11 @@ +# Blade/errors + +HTTP error page templates. Registered under the `errors::` namespace. + +## Files + +- **404.blade.php** -- Not Found error page +- **500.blade.php** -- Internal Server Error page +- **503.blade.php** -- Service Unavailable / Maintenance Mode page + +These override Laravel's default error views when the `errors::` namespace is registered. diff --git a/src/Core/Front/Components/View/Blade/examples/CLAUDE.md b/src/Core/Front/Components/View/Blade/examples/CLAUDE.md new file mode 100644 index 0000000..b158508 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/examples/CLAUDE.md @@ -0,0 +1,13 @@ +# Blade/examples + +Example page templates demonstrating the component system. + +## Files + +- **blog-post.blade.php** -- Blog post page layout example +- **checkout.blade.php** -- Checkout/payment page layout example +- **guide.blade.php** -- Documentation/guide page layout example +- **help-centre.blade.php** -- Help centre page with sidebar navigation example +- **hlcrf-test.blade.php** -- Test page for the HLCRF layout compositor (Header-Left-Content-Right-Footer) + +These are reference implementations showing how to compose pages using the core component library and layout system. diff --git a/src/Core/Front/Components/View/Blade/file-item/CLAUDE.md b/src/Core/Front/Components/View/Blade/file-item/CLAUDE.md new file mode 100644 index 0000000..f6fd790 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/file-item/CLAUDE.md @@ -0,0 +1,7 @@ +# Blade/file-item + +File item sub-components for file list displays. + +## Files + +- **remove.blade.php** -- Remove/delete button for a file item. Typically renders an X icon button to remove a file from an upload list or file manager. diff --git a/src/Core/Front/Components/View/Blade/file-upload/CLAUDE.md b/src/Core/Front/Components/View/Blade/file-upload/CLAUDE.md new file mode 100644 index 0000000..1f9cf81 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/file-upload/CLAUDE.md @@ -0,0 +1,7 @@ +# Blade/file-upload + +File upload sub-components. + +## Files + +- **dropzone.blade.php** -- Drag-and-drop file upload zone. Provides a styled drop target area with upload icon, instructions, and file type/size hints. Integrates with Livewire file upload. diff --git a/src/Core/Front/Components/View/Blade/forms/CLAUDE.md b/src/Core/Front/Components/View/Blade/forms/CLAUDE.md new file mode 100644 index 0000000..9db8dbc --- /dev/null +++ b/src/Core/Front/Components/View/Blade/forms/CLAUDE.md @@ -0,0 +1,14 @@ +# Blade/forms + +Form element components. Provide styled, accessible form controls. + +## Files + +- **button.blade.php** -- Form submit/action button +- **checkbox.blade.php** -- Checkbox input with label +- **input.blade.php** -- Text input field +- **select.blade.php** -- Dropdown select field +- **textarea.blade.php** -- Multi-line text input +- **toggle.blade.php** -- Toggle switch (boolean input) + +All components follow Flux Pro styling conventions and integrate with Livewire `wire:model`. diff --git a/src/Core/Front/Components/View/Blade/icon/CLAUDE.md b/src/Core/Front/Components/View/Blade/icon/CLAUDE.md new file mode 100644 index 0000000..5150242 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/icon/CLAUDE.md @@ -0,0 +1,19 @@ +# Blade/icon + +Inline SVG icon components. These are Heroicon-style SVG icons used as fallbacks or within specific components. + +## Files + +- **check.blade.php** -- Checkmark icon +- **check-circle.blade.php** -- Checkmark in circle icon +- **clipboard.blade.php** -- Clipboard icon +- **clock.blade.php** -- Clock/time icon +- **code-bracket.blade.php** -- Code brackets icon +- **code-bracket-square.blade.php** -- Code brackets in square icon +- **document-text.blade.php** -- Document with text icon +- **key.blade.php** -- Key icon +- **lock-closed.blade.php** -- Locked padlock icon +- **x-circle.blade.php** -- X in circle icon (error/close) +- **x-mark.blade.php** -- X mark icon (close/dismiss) + +Note: The primary icon system uses Font Awesome Pro via ``. These SVG components are supplementary. diff --git a/src/Core/Front/Components/View/Blade/input/CLAUDE.md b/src/Core/Front/Components/View/Blade/input/CLAUDE.md new file mode 100644 index 0000000..f864e1f --- /dev/null +++ b/src/Core/Front/Components/View/Blade/input/CLAUDE.md @@ -0,0 +1,11 @@ +# Blade/input + +Input sub-components. + +## Files + +- **group.blade.php** -- Input group container for combining an input with prefix/suffix addons. + +## Subdirectories + +- **group/** -- Contains `prefix.blade.php` for input group prefix addon (icon, text, or custom content before the input). diff --git a/src/Core/Front/Components/View/Blade/input/group/CLAUDE.md b/src/Core/Front/Components/View/Blade/input/group/CLAUDE.md new file mode 100644 index 0000000..896e05b --- /dev/null +++ b/src/Core/Front/Components/View/Blade/input/group/CLAUDE.md @@ -0,0 +1,7 @@ +# Blade/input/group + +Input group addon components. + +## Files + +- **prefix.blade.php** -- Prefix addon for input groups. Renders content (icon, text, symbol) to the left of the input field within an input group container. diff --git a/src/Core/Front/Components/View/Blade/kanban/CLAUDE.md b/src/Core/Front/Components/View/Blade/kanban/CLAUDE.md new file mode 100644 index 0000000..e0bc084 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/kanban/CLAUDE.md @@ -0,0 +1,26 @@ +# Blade/kanban + +Kanban board components. + +## Files + +- **card.blade.php** -- Individual kanban card (draggable item within a column) +- **column.blade.php** -- Kanban column container + +## Subdirectories + +- **column/** -- `cards.blade.php` (card list container), `footer.blade.php` (column footer with add action), `header.blade.php` (column title and count) + +## Usage + +```blade + + + To Do + + Task 1 + + + + +``` diff --git a/src/Core/Front/Components/View/Blade/kanban/column/CLAUDE.md b/src/Core/Front/Components/View/Blade/kanban/column/CLAUDE.md new file mode 100644 index 0000000..79dd5b1 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/kanban/column/CLAUDE.md @@ -0,0 +1,9 @@ +# Blade/kanban/column + +Kanban column sub-components. + +## Files + +- **cards.blade.php** -- Card list container within a column. Provides the droppable area for kanban cards. +- **footer.blade.php** -- Column footer, typically containing an "Add card" action button. +- **header.blade.php** -- Column header displaying the column title, item count, and optional actions. diff --git a/src/Core/Front/Components/View/Blade/layout/CLAUDE.md b/src/Core/Front/Components/View/Blade/layout/CLAUDE.md new file mode 100644 index 0000000..43c0a28 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/layout/CLAUDE.md @@ -0,0 +1,13 @@ +# Blade/layout + +Structural layout slot components for page composition. + +## Files + +- **content.blade.php** -- Main content area wrapper +- **footer.blade.php** -- Page footer section +- **header.blade.php** -- Page header section +- **left.blade.php** -- Left sidebar/aside section +- **right.blade.php** -- Right sidebar/aside section + +These map to the HLCRF (Header-Left-Content-Right-Footer) layout system. Used as named slots within layout templates. diff --git a/src/Core/Front/Components/View/Blade/layouts/CLAUDE.md b/src/Core/Front/Components/View/Blade/layouts/CLAUDE.md new file mode 100644 index 0000000..8e52c69 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/layouts/CLAUDE.md @@ -0,0 +1,27 @@ +# Blade/layouts + +Page layout templates registered under the `layouts::` namespace. Used by Livewire components via `->layout('layouts::app')`. + +## Files + +- **app.blade.php** -- Marketing/sales layout with particle animation. For landing pages, pricing, about, services. +- **content.blade.php** -- Blog posts, guides, legal pages. Centred prose layout. +- **focused.blade.php** -- Checkout, forms, onboarding. Minimal, distraction-free layout. +- **minimal.blade.php** -- Bare minimum layout with no navigation. +- **sidebar-left.blade.php** -- Help centre, FAQ, documentation. Left nav + content. +- **sidebar-right.blade.php** -- Long guides with TOC. Content + right sidebar. +- **workspace.blade.php** -- Authenticated SaaS workspace layout. + +## Subdirectories + +- **partials/** -- Shared layout fragments (base HTML shell, fonts, header, footer) + +## Usage + +```php +// In Livewire component +public function layout(): string +{ + return 'layouts::app'; +} +``` diff --git a/src/Core/Front/Components/View/Blade/layouts/partials/CLAUDE.md b/src/Core/Front/Components/View/Blade/layouts/partials/CLAUDE.md new file mode 100644 index 0000000..7258e5e --- /dev/null +++ b/src/Core/Front/Components/View/Blade/layouts/partials/CLAUDE.md @@ -0,0 +1,12 @@ +# Blade/layouts/partials + +Shared layout fragments included by the layout templates. + +## Files + +- **base.blade.php** -- Base HTML document shell. Handles ``, ``, ``, OG meta tags, CSRF token, Vite assets, and optional particle animation canvas. All layout templates extend this. + - Props: `title`, `description`, `ogImage`, `ogType`, `particles` (bool) +- **fonts.blade.php** -- External font loading (Google Fonts link tags) +- **fonts-inline.blade.php** -- Inline font declarations (for critical rendering path) +- **footer.blade.php** -- Shared site footer with navigation links, social links, and copyright +- **header.blade.php** -- Shared site header/navigation bar with logo, menu items, and auth links diff --git a/src/Core/Front/Components/View/Blade/menu/CLAUDE.md b/src/Core/Front/Components/View/Blade/menu/CLAUDE.md new file mode 100644 index 0000000..2348921 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/menu/CLAUDE.md @@ -0,0 +1,25 @@ +# Blade/menu + +Dropdown menu sub-components. + +## Files + +- **checkbox.blade.php** -- Menu item with checkbox toggle +- **group.blade.php** -- Menu item group with optional label +- **item.blade.php** -- Standard menu item (link or action) +- **radio.blade.php** -- Menu item with radio button selection +- **separator.blade.php** -- Visual separator/divider between menu groups +- **submenu.blade.php** -- Nested submenu that opens on hover/click + +## Usage + +```blade + + + Edit + Duplicate + + + Delete + +``` diff --git a/src/Core/Front/Components/View/Blade/navbar/CLAUDE.md b/src/Core/Front/Components/View/Blade/navbar/CLAUDE.md new file mode 100644 index 0000000..ce6f951 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/navbar/CLAUDE.md @@ -0,0 +1,7 @@ +# Blade/navbar + +Navbar sub-components for the `` component. + +## Files + +- **item.blade.php** -- Individual navbar item. Renders as a navigation link within a navbar container. diff --git a/src/Core/Front/Components/View/Blade/navlist/CLAUDE.md b/src/Core/Front/Components/View/Blade/navlist/CLAUDE.md new file mode 100644 index 0000000..71a10b8 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/navlist/CLAUDE.md @@ -0,0 +1,19 @@ +# Blade/navlist + +Navigation list sub-components for sidebar/panel navigation. + +## Files + +- **group.blade.php** -- Navigation group with optional heading label. Groups related nav items together with visual separation. +- **item.blade.php** -- Individual navigation item with label, href, icon, and active state. + +## Usage + +```blade + + + Dashboard + Settings + + +``` diff --git a/src/Core/Front/Components/View/Blade/pillbox/CLAUDE.md b/src/Core/Front/Components/View/Blade/pillbox/CLAUDE.md new file mode 100644 index 0000000..43276a2 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/pillbox/CLAUDE.md @@ -0,0 +1,27 @@ +# Blade/pillbox + +Pillbox (tag/chip input) sub-components for multi-value selection. + +## Files + +- **create.blade.php** -- "Create new" action within the pillbox dropdown +- **empty.blade.php** -- Empty state when no options match the search +- **input.blade.php** -- Search/filter input within the pillbox +- **option.blade.php** -- Selectable option in the dropdown list +- **search.blade.php** -- Search container wrapping the input and results +- **trigger.blade.php** -- The pillbox trigger showing selected items as removable pills + +## Usage + +```blade + + + + + PHP + Go + No matches + Add new tag + + +``` diff --git a/src/Core/Front/Components/View/Blade/radio/CLAUDE.md b/src/Core/Front/Components/View/Blade/radio/CLAUDE.md new file mode 100644 index 0000000..9bf8f1b --- /dev/null +++ b/src/Core/Front/Components/View/Blade/radio/CLAUDE.md @@ -0,0 +1,7 @@ +# Blade/radio + +Radio button sub-components. + +## Files + +- **group.blade.php** -- Radio button group container. Wraps multiple radio inputs with shared name and layout. diff --git a/src/Core/Front/Components/View/Blade/select/CLAUDE.md b/src/Core/Front/Components/View/Blade/select/CLAUDE.md new file mode 100644 index 0000000..04d4b32 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/select/CLAUDE.md @@ -0,0 +1,7 @@ +# Blade/select + +Select dropdown sub-components. + +## Files + +- **option.blade.php** -- Individual option within a select dropdown. Renders as a selectable item in the custom select component's option list. diff --git a/src/Core/Front/Components/View/Blade/slider/CLAUDE.md b/src/Core/Front/Components/View/Blade/slider/CLAUDE.md new file mode 100644 index 0000000..1f2e92a --- /dev/null +++ b/src/Core/Front/Components/View/Blade/slider/CLAUDE.md @@ -0,0 +1,7 @@ +# Blade/slider + +Slider (range input) sub-components. + +## Files + +- **tick.blade.php** -- Tick mark along a slider track. Provides visual markers at specific values on a range slider. diff --git a/src/Core/Front/Components/View/Blade/tab/CLAUDE.md b/src/Core/Front/Components/View/Blade/tab/CLAUDE.md new file mode 100644 index 0000000..14f17db --- /dev/null +++ b/src/Core/Front/Components/View/Blade/tab/CLAUDE.md @@ -0,0 +1,19 @@ +# Blade/tab + +Tab sub-components for the `` system. + +## Files + +- **group.blade.php** -- Tab group container. Wraps tab triggers and manages selected state. +- **panel.blade.php** -- Tab content panel. Shows/hides based on which tab is selected. + +## Usage + +```blade + + General + Advanced + +General content +Advanced content +``` diff --git a/src/Core/Front/Components/View/Blade/table/CLAUDE.md b/src/Core/Front/Components/View/Blade/table/CLAUDE.md new file mode 100644 index 0000000..2f475ac --- /dev/null +++ b/src/Core/Front/Components/View/Blade/table/CLAUDE.md @@ -0,0 +1,28 @@ +# Blade/table + +Table sub-components for data tables. + +## Files + +- **cell.blade.php** -- Individual table cell (``) +- **column.blade.php** -- Column header (``) with optional sorting +- **columns.blade.php** -- Column header row container (``) +- **row.blade.php** -- Table row (``) +- **rows.blade.php** -- Table body container (``) + +## Usage + +```blade + + + Name + Status + + + + Item 1 + Active + + + +``` diff --git a/src/Core/Front/Components/View/Blade/web/CLAUDE.md b/src/Core/Front/Components/View/Blade/web/CLAUDE.md new file mode 100644 index 0000000..26715d9 --- /dev/null +++ b/src/Core/Front/Components/View/Blade/web/CLAUDE.md @@ -0,0 +1,11 @@ +# Blade/web + +Public-facing page templates for workspace websites. Registered under the `web::` namespace. + +## Files + +- **home.blade.php** -- Workspace homepage template +- **page.blade.php** -- Generic content page template +- **waitlist.blade.php** -- Pre-launch waitlist/signup page template + +These are rendered for workspace domains resolved by `FindDomainRecord` middleware. Used via `web::home`, `web::page`, `web::waitlist` view references. diff --git a/src/Core/Front/Services/CLAUDE.md b/src/Core/Front/Services/CLAUDE.md new file mode 100644 index 0000000..2b987d5 --- /dev/null +++ b/src/Core/Front/Services/CLAUDE.md @@ -0,0 +1,18 @@ +# Front/Services + +Shared services for the Front module. + +## Files + +- **DeviceDetectionService.php** -- User-Agent parser for device type, OS, browser, in-app browser, and bot detection. Detects 14 social platform in-app browsers (Instagram, Facebook, TikTok, Twitter, LinkedIn, Snapchat, Threads, Pinterest, Reddit, WeChat, LINE, Telegram, Discord, WhatsApp) plus generic WebView. Identifies strict content platforms (Meta, TikTok, Twitter, Snapchat, LinkedIn) and Meta-owned platforms. Platform-specific methods: `isInstagram()`, `isFacebook()`, `isTikTok()`, etc. Full parse returns `{device_type, os_name, browser_name, in_app_browser, is_in_app}`. + +## Usage + +```php +$service = new DeviceDetectionService(); +$info = $service->parse($request->userAgent()); + +if ($service->isStrictContentPlatform($ua)) { + // Hide restricted content for platform compliance +} +``` diff --git a/src/Core/Front/Stdio/CLAUDE.md b/src/Core/Front/Stdio/CLAUDE.md new file mode 100644 index 0000000..dbe3975 --- /dev/null +++ b/src/Core/Front/Stdio/CLAUDE.md @@ -0,0 +1,7 @@ +# Front/Stdio + +Stdio frontage for terminal/pipe-based I/O. + +## Files + +- **Boot.php** -- ServiceProvider for stdin/stdout transport. Handles non-HTTP contexts: Artisan commands, MCP stdio transport (agents connecting via pipes), and interactive CLI tools. Currently a placeholder with empty command registration -- core CLI commands will be registered here. No HTTP middleware -- this is a different transport entirely. diff --git a/src/Core/Front/Tests/Unit/CLAUDE.md b/src/Core/Front/Tests/Unit/CLAUDE.md new file mode 100644 index 0000000..acf6a7e --- /dev/null +++ b/src/Core/Front/Tests/Unit/CLAUDE.md @@ -0,0 +1,13 @@ +# Front/Tests/Unit + +Unit tests for the Front module. + +## Files + +- **DeviceDetectionServiceTest.php** -- Tests for `DeviceDetectionService`. Covers in-app browser detection (Instagram, Facebook, TikTok, Twitter, LinkedIn, Snapchat, Threads, Pinterest, Reddit, WeChat, WhatsApp), standard browser exclusion, platform-specific methods, strict content platform identification, Meta platform detection, display names, device type/OS/browser detection, bot detection, and full parse output. Uses PHPUnit DataProvider for UA string coverage. + +## Running + +```bash +composer test -- --filter=DeviceDetectionServiceTest +``` diff --git a/src/Core/Front/Web/Blade/components/CLAUDE.md b/src/Core/Front/Web/Blade/components/CLAUDE.md new file mode 100644 index 0000000..988f95c --- /dev/null +++ b/src/Core/Front/Web/Blade/components/CLAUDE.md @@ -0,0 +1,21 @@ +# Front/Web/Blade/components + +Anonymous Blade components for the public web frontage. Used via `` tag syntax. + +## Components + +- **nav-item.blade.php** -- Navigation list item with icon and active state highlighting. + - Props: `href` (required), `icon` (string|null), `active` (bool) + - Uses `` for icon rendering. + +- **page.blade.php** -- Simple page wrapper for public web pages with optional title and description. + - Props: `title` (string|null), `description` (string|null) + - Provides max-width container with responsive padding. + +## Usage + +```blade + +

Content here

+ +``` diff --git a/src/Core/Front/Web/Blade/layouts/CLAUDE.md b/src/Core/Front/Web/Blade/layouts/CLAUDE.md new file mode 100644 index 0000000..147fac6 --- /dev/null +++ b/src/Core/Front/Web/Blade/layouts/CLAUDE.md @@ -0,0 +1,10 @@ +# Front/Web/Blade/layouts + +Layout templates for public web pages. + +## Files + +- **app.blade.php** -- Base HTML shell for public web pages. Includes dark mode support (cookie-based), CSRF meta tag, Vite assets (app.css + app.js), Flux appearance/scripts, and font loading via `layouts::partials.fonts`. + - Props: `title` (string, defaults to `core.app.name` config) + - Slots: `$head` (extra head content), `$scripts` (extra scripts before ``) + - Prevents white flash with inline critical CSS for dark mode. diff --git a/src/Core/Front/Web/CLAUDE.md b/src/Core/Front/Web/CLAUDE.md new file mode 100644 index 0000000..bfb9267 --- /dev/null +++ b/src/Core/Front/Web/CLAUDE.md @@ -0,0 +1,21 @@ +# Front/Web + +Public-facing web frontage. Service provider that configures the `web` middleware group and registers `` Blade tag syntax. + +## Files + +- **Boot.php** -- ServiceProvider that configures the `web` middleware stack (cookies, session, CSRF, security headers, domain resolution), registers the `web::` Blade namespace, fires `WebRoutesRegistering` lifecycle event, and aliases `livewire` as `admin` for Flux compatibility. +- **WebTagCompiler.php** -- Blade precompiler enabling `` tag syntax (like ``). Compiles to anonymous components in the `web::` namespace. + +## Middleware Stack + +The `web` group includes: EncryptCookies, AddQueuedCookiesToResponse, StartSession, ResilientSession, ShareErrorsFromSession, ValidateCsrfToken, SubstituteBindings, SecurityHeaders, FindDomainRecord. + +## Tag Syntax + +```blade +Content here +About +``` + +Resolves to anonymous components in `Web/Blade/components/` and `Components/View/Blade/web/`. diff --git a/src/Core/Front/Web/Middleware/CLAUDE.md b/src/Core/Front/Web/Middleware/CLAUDE.md new file mode 100644 index 0000000..8a0141f --- /dev/null +++ b/src/Core/Front/Web/Middleware/CLAUDE.md @@ -0,0 +1,9 @@ +# Front/Web/Middleware + +HTTP middleware for public web requests. + +## Files + +- **FindDomainRecord.php** -- Resolves the current workspace from the incoming domain. Sets `workspace_model` and `workspace` attributes on the request. Core domains (base domain, www, localhost) pass through. Checks custom domains first, then subdomain slugs. Requires `Core\Tenant` module. +- **RedirectIfAuthenticated.php** -- Redirects logged-in users away from guest-only pages (e.g., login). Redirects to `/` on the current domain instead of a global dashboard route. +- **ResilientSession.php** -- Catches session corruption (decryption errors, DB failures) and recovers gracefully by clearing cookies and retrying. Prevents 503 errors from APP_KEY changes or session table issues. Returns JSON for AJAX requests. diff --git a/src/Core/Headers/Livewire/CLAUDE.md b/src/Core/Headers/Livewire/CLAUDE.md new file mode 100644 index 0000000..899f20c --- /dev/null +++ b/src/Core/Headers/Livewire/CLAUDE.md @@ -0,0 +1,7 @@ +# Headers/Livewire/ — Header Configuration UI + +## Components + +| Component | Purpose | +|-----------|---------| +| `HeaderConfigurationManager` | Livewire component for managing security header configuration in the admin panel. Provides UI for configuring CSP directives, HSTS settings, Permissions Policy features, and other security headers. | diff --git a/src/Core/Headers/Testing/CLAUDE.md b/src/Core/Headers/Testing/CLAUDE.md new file mode 100644 index 0000000..ef8889c --- /dev/null +++ b/src/Core/Headers/Testing/CLAUDE.md @@ -0,0 +1,10 @@ +# Headers/Testing/ — Security Header Test Utilities + +## Files + +| File | Purpose | +|------|---------| +| `HeaderAssertions` | Trait with assertion methods for testing security headers in HTTP responses. Provides `assertHasSecurityHeaders()`, `assertCspContains()`, etc. | +| `SecurityHeaderTester` | Standalone static helper for validating security headers. Can be used without traits for flexible testing scenarios. | + +Used by feature tests (`SecurityHeadersTest`) to verify CSP, HSTS, X-Frame-Options, and other security headers. diff --git a/src/Core/Headers/Views/livewire/CLAUDE.md b/src/Core/Headers/Views/livewire/CLAUDE.md new file mode 100644 index 0000000..f96d298 --- /dev/null +++ b/src/Core/Headers/Views/livewire/CLAUDE.md @@ -0,0 +1,7 @@ +# Headers/Views/livewire/ — Header Configuration Blade Template + +## Templates + +| File | Purpose | +|------|---------| +| `header-configuration-manager.blade.php` | Blade template for the `HeaderConfigurationManager` Livewire component. Renders the security header configuration form with CSP, HSTS, and Permissions Policy controls. | diff --git a/src/Core/Helpers/Rules/CLAUDE.md b/src/Core/Helpers/Rules/CLAUDE.md new file mode 100644 index 0000000..7a897c6 --- /dev/null +++ b/src/Core/Helpers/Rules/CLAUDE.md @@ -0,0 +1,13 @@ +# Helpers/Rules/ — Custom Validation Rules + +## Rules + +| Rule | Purpose | +|------|---------| +| `HexRule` | Validates hexadecimal colour codes. Supports 3-digit (`#fff`) and 6-digit (`#ffffff`) formats. Hash symbol required. Constructor option `forceFull: true` rejects 3-digit codes. | + +Usage: +```php +'colour' => ['required', new HexRule()] +'colour' => ['required', new HexRule(forceFull: true)] +``` diff --git a/src/Core/Input/Tests/Unit/CLAUDE.md b/src/Core/Input/Tests/Unit/CLAUDE.md new file mode 100644 index 0000000..cfadd77 --- /dev/null +++ b/src/Core/Input/Tests/Unit/CLAUDE.md @@ -0,0 +1,9 @@ +# Input/Tests/Unit/ — Input Filtering Tests + +## Test Files + +| File | Purpose | +|------|---------| +| `InputFilteringTest.php` | Pest unit tests for the `Sanitiser` class. Covers clean input passthrough (ASCII, punctuation, UTF-8), XSS prevention, SQL injection stripping, null byte removal, and edge cases. | + +Tests the WAF layer that `Core\Init` uses to sanitise `$_GET` and `$_POST` before Laravel processes the request. diff --git a/src/Core/Lang/Console/Commands/CLAUDE.md b/src/Core/Lang/Console/Commands/CLAUDE.md new file mode 100644 index 0000000..936503e --- /dev/null +++ b/src/Core/Lang/Console/Commands/CLAUDE.md @@ -0,0 +1,10 @@ +# Lang/Console/Commands/ — Translation CLI Commands + +## Commands + +| Command | Purpose | +|---------|---------| +| `TranslationCoverageCommand` | Reports translation coverage across the codebase. Scans code for translation key usage and compares against translation files to identify missing and unused keys. | +| `TranslationMemoryCommand` | CLI interface for managing translation memory — view statistics, browse entries, import/export TMX files, fuzzy match queries. | + +Part of the Lang subsystem's developer tooling. diff --git a/src/Core/Lang/Coverage/CLAUDE.md b/src/Core/Lang/Coverage/CLAUDE.md new file mode 100644 index 0000000..a566f93 --- /dev/null +++ b/src/Core/Lang/Coverage/CLAUDE.md @@ -0,0 +1,10 @@ +# Lang/Coverage/ — Translation Coverage Analysis + +## Files + +| File | Purpose | +|------|---------| +| `TranslationCoverage` | Scans PHP, Blade, and JS/Vue files for translation key usage (`__()`, `trans()`, `@lang`, etc.) and compares against translation files. Reports missing keys (used but undefined) and unused keys (defined but unused). | +| `TranslationCoverageReport` | DTO containing analysis results — missing keys, unused keys, coverage statistics per locale, and usage locations. Implements `Arrayable`. | + +Used by the `lang:coverage` Artisan command for translation quality assurance. diff --git a/src/Core/Lang/TranslationMemory/CLAUDE.md b/src/Core/Lang/TranslationMemory/CLAUDE.md new file mode 100644 index 0000000..0e77121 --- /dev/null +++ b/src/Core/Lang/TranslationMemory/CLAUDE.md @@ -0,0 +1,14 @@ +# Lang/TranslationMemory/ — Translation Memory System + +Stores and retrieves previous translations for reuse and consistency. + +## Files + +| File | Purpose | +|------|---------| +| `TranslationMemory` | Unified service — store, retrieve, suggest translations. Supports exact and fuzzy matching with confidence scoring. | +| `TranslationMemoryEntry` | DTO for a single translation unit — source text, target text, metadata, quality score (0.0-1.0). | +| `FuzzyMatcher` | Finds similar translations via Levenshtein distance, token/word matching, and n-gram matching. Combines with quality score for confidence rating. | +| `JsonTranslationMemoryRepository` | File-based storage backend — JSON files organised by locale pairs. | +| `TmxExporter` | Exports to TMX (Translation Memory eXchange) standard XML format. | +| `TmxImporter` | Imports from TMX files for interoperability with other translation tools. | diff --git a/src/Core/Lang/TranslationMemory/Contracts/CLAUDE.md b/src/Core/Lang/TranslationMemory/Contracts/CLAUDE.md new file mode 100644 index 0000000..ef180cf --- /dev/null +++ b/src/Core/Lang/TranslationMemory/Contracts/CLAUDE.md @@ -0,0 +1,9 @@ +# Lang/TranslationMemory/Contracts/ — TM Repository Interface + +## Interfaces + +| Interface | Purpose | +|-----------|---------| +| `TranslationMemoryRepository` | Storage backend contract. Methods: `store(entry)`, `find(source, locale)`, `search(query, locale)`, `all(locale)`, `delete(id)`. Implementations may use JSON files, databases, or external services. | + +The default implementation is `JsonTranslationMemoryRepository`. diff --git a/src/Core/Lang/en_GB/CLAUDE.md b/src/Core/Lang/en_GB/CLAUDE.md new file mode 100644 index 0000000..da004f1 --- /dev/null +++ b/src/Core/Lang/en_GB/CLAUDE.md @@ -0,0 +1,9 @@ +# Lang/en_GB/ — British English Translations + +## Files + +| File | Purpose | +|------|---------| +| `core.php` | British English translation strings for the Core framework. Returns a keyed array of translatable strings used throughout the UI, emails, and error messages. | + +This is the primary locale — the framework uses UK English as its base language (colour, organisation, centre). diff --git a/src/Core/Mail/Rules/CLAUDE.md b/src/Core/Mail/Rules/CLAUDE.md new file mode 100644 index 0000000..0a7afee --- /dev/null +++ b/src/Core/Mail/Rules/CLAUDE.md @@ -0,0 +1,14 @@ +# Mail/Rules/ — Email Validation Rules + +## Rules + +| Rule | Purpose | +|------|---------| +| `ValidatedEmail` | Laravel validation rule using the `EmailShield` service. Validates email format and optionally blocks disposable email domains. Constructor takes `blockDisposable: true` (default). | + +Usage: +```php +'email' => ['required', new ValidatedEmail(blockDisposable: true)] +``` + +Part of the Mail subsystem's input validation layer. diff --git a/src/Core/Media/Abstracts/CLAUDE.md b/src/Core/Media/Abstracts/CLAUDE.md new file mode 100644 index 0000000..d033935 --- /dev/null +++ b/src/Core/Media/Abstracts/CLAUDE.md @@ -0,0 +1,10 @@ +# Media/Abstracts/ — Media Base Classes + +## Abstract Classes + +| Class | Purpose | +|-------|---------| +| `Image` | Base class for image handling operations. | +| `MediaConversion` | Abstract base for all media conversions (image resizing, thumbnail generation, video processing). Provides common functionality: queueing for large files (threshold configurable via `media.queue_threshold_mb`), progress reporting via `ConversionProgress` event, and storage abstraction. | + +Concrete implementations in `Core\Media\Conversions\`. diff --git a/src/Core/Media/Conversions/CLAUDE.md b/src/Core/Media/Conversions/CLAUDE.md new file mode 100644 index 0000000..630e15e --- /dev/null +++ b/src/Core/Media/Conversions/CLAUDE.md @@ -0,0 +1,12 @@ +# Media/Conversions/ — Media Conversion Implementations + +Concrete implementations of `MediaConversion` for specific processing tasks. + +## Conversions + +| Class | Purpose | +|-------|---------| +| `MediaImageResizerConversion` | Resizes images to specified dimensions while maintaining aspect ratio. Prevents upscaling. Skips GIF files to preserve animation. Uses `ImageResizer`. | +| `MediaVideoThumbConversion` | Extracts thumbnail frames from video files for preview display. | + +Both extend `Core\Media\Abstracts\MediaConversion` and can be queued via `ProcessMediaConversion` job. diff --git a/src/Core/Media/Events/CLAUDE.md b/src/Core/Media/Events/CLAUDE.md new file mode 100644 index 0000000..5642b47 --- /dev/null +++ b/src/Core/Media/Events/CLAUDE.md @@ -0,0 +1,7 @@ +# Media/Events/ — Media System Events + +## Events + +| Event | Fired When | Purpose | +|-------|-----------|---------| +| `ConversionProgress` | During media conversion processing | Reports progress stages for UI progress bars, logging, and monitoring. | diff --git a/src/Core/Media/Image/CLAUDE.md b/src/Core/Media/Image/CLAUDE.md new file mode 100644 index 0000000..15a79ef --- /dev/null +++ b/src/Core/Media/Image/CLAUDE.md @@ -0,0 +1,13 @@ +# Media/Image/ — Image Processing + +Image optimisation and processing utilities. + +## Files + +| File | Purpose | +|------|---------| +| `ImageOptimizer` | Main optimiser — resizes, compresses, and converts images. Includes memory safety checks (GD needs 5-6x image size). | +| `ImageOptimization` | Optimisation configuration and pipeline orchestration. | +| `ExifStripper` | Removes EXIF metadata from images for privacy (GPS coordinates, camera info). | +| `ModernFormatSupport` | Detects and enables WebP/AVIF support based on server capabilities. | +| `OptimizationResult` | DTO containing optimisation results — original size, optimised size, savings percentage, format used. | diff --git a/src/Core/Media/Jobs/CLAUDE.md b/src/Core/Media/Jobs/CLAUDE.md new file mode 100644 index 0000000..1b4ecc1 --- /dev/null +++ b/src/Core/Media/Jobs/CLAUDE.md @@ -0,0 +1,8 @@ +# Media/Jobs/ — Media Background Jobs + +## Jobs + +| Job | Purpose | +|-----|---------| +| `ProcessMediaConversion` | Queued job for running media conversions asynchronously. Dispatches `ConversionProgress` events during processing. Logs failures. | +| `GenerateThumbnail` | Queued job for generating thumbnails on demand. Called by `LazyThumbnail` when a thumbnail doesn't exist yet. | diff --git a/src/Core/Media/Routes/CLAUDE.md b/src/Core/Media/Routes/CLAUDE.md new file mode 100644 index 0000000..824dfce --- /dev/null +++ b/src/Core/Media/Routes/CLAUDE.md @@ -0,0 +1,7 @@ +# Media/Routes/ — Media Web Routes + +## Files + +| File | Purpose | +|------|---------| +| `web.php` | Web route definitions for media serving — thumbnail endpoints, image serving routes. Registered via the `WebRoutesRegistering` lifecycle event. | diff --git a/src/Core/Media/Support/CLAUDE.md b/src/Core/Media/Support/CLAUDE.md new file mode 100644 index 0000000..6b7aac4 --- /dev/null +++ b/src/Core/Media/Support/CLAUDE.md @@ -0,0 +1,11 @@ +# Media/Support/ — Media Processing Utilities + +## Files + +| File | Purpose | +|------|---------| +| `ImageResizer` | Image resizing with aspect ratio preservation and memory safety checks. Prevents upscaling and OOM crashes. | +| `ConversionProgressReporter` | Reports media conversion progress to listeners via `ConversionProgress` event. | +| `MediaConversionData` | DTO carrying conversion parameters — source path, output path, dimensions, format, quality. | +| `TemporaryDirectory` | Manages temporary directories for media processing with automatic cleanup. | +| `TemporaryFile` | Manages temporary files for media processing with automatic cleanup. | diff --git a/src/Core/Media/Thumbnail/CLAUDE.md b/src/Core/Media/Thumbnail/CLAUDE.md new file mode 100644 index 0000000..14a6760 --- /dev/null +++ b/src/Core/Media/Thumbnail/CLAUDE.md @@ -0,0 +1,11 @@ +# Media/Thumbnail/ — Lazy Thumbnail Generation + +## Files + +| File | Purpose | +|------|---------| +| `LazyThumbnail` | On-demand thumbnail generation service. Generates thumbnails when first requested rather than eagerly on upload. Caches generated thumbnails. Dispatches `GenerateThumbnail` job for async processing. | +| `ThumbnailController` | HTTP controller serving thumbnail requests. Generates on-the-fly if not cached. | +| `helpers.php` | Helper functions for thumbnail URL generation in Blade templates. | + +Thumbnails are generated lazily to avoid processing overhead on upload and to only create sizes that are actually requested. diff --git a/src/Core/Search/Analytics/CLAUDE.md b/src/Core/Search/Analytics/CLAUDE.md new file mode 100644 index 0000000..0435491 --- /dev/null +++ b/src/Core/Search/Analytics/CLAUDE.md @@ -0,0 +1,15 @@ +# Search/Analytics/ — Search Analytics + +## Files + +| File | Purpose | +|------|---------| +| `SearchAnalytics` | Tracks search queries, results, and user interactions. Features: query tracking with timestamps and result counts, click-through tracking, zero-result query tracking for content gap analysis, popular search trending. | + +Part of the Search subsystem. Data feeds into `SearchSuggestions` for autocomplete. + +## Migrations + +| File | Purpose | +|------|---------| +| `migrations/2024_01_01_000001_create_search_analytics_tables.php` | Creates tables for search query tracking, result counts, and click-through data. | diff --git a/src/Core/Search/Analytics/migrations/CLAUDE.md b/src/Core/Search/Analytics/migrations/CLAUDE.md new file mode 100644 index 0000000..757dd6a --- /dev/null +++ b/src/Core/Search/Analytics/migrations/CLAUDE.md @@ -0,0 +1,7 @@ +# Search/Analytics/migrations/ — Search Analytics Schema + +## Migrations + +| File | Purpose | +|------|---------| +| `2024_01_01_000001_create_search_analytics_tables.php` | Creates tables for search query tracking, result counts, and click-through data used by the `SearchAnalytics` service. | diff --git a/src/Core/Search/Suggestions/CLAUDE.md b/src/Core/Search/Suggestions/CLAUDE.md new file mode 100644 index 0000000..5b47673 --- /dev/null +++ b/src/Core/Search/Suggestions/CLAUDE.md @@ -0,0 +1,9 @@ +# Search/Suggestions/ — Search Autocomplete + +## Files + +| File | Purpose | +|------|---------| +| `SearchSuggestions` | Type-ahead suggestion service. Sources: popular queries from SearchAnalytics, recent searches (per user/session), prefix matching, content-based suggestions from searchable items. Cached for performance. | + +Part of the Search subsystem. Provides autocomplete data for search UIs. diff --git a/src/Core/Search/Support/CLAUDE.md b/src/Core/Search/Support/CLAUDE.md new file mode 100644 index 0000000..10797df --- /dev/null +++ b/src/Core/Search/Support/CLAUDE.md @@ -0,0 +1,9 @@ +# Search/Support/ — Search Utilities + +## Files + +| File | Purpose | +|------|---------| +| `SearchHighlighter` | Highlights search query terms within result text. Multi-word support, case-insensitive matching with original case preserved, HTML-safe output, context extraction (snippets around matches), configurable highlight styles. | + +Used by search result rendering to show users why a result matched their query. diff --git a/src/Core/Seo/Analytics/CLAUDE.md b/src/Core/Seo/Analytics/CLAUDE.md new file mode 100644 index 0000000..c8cb584 --- /dev/null +++ b/src/Core/Seo/Analytics/CLAUDE.md @@ -0,0 +1,7 @@ +# Seo/Analytics/ — SEO Score Tracking + +## Files + +| File | Purpose | +|------|---------| +| `SeoScoreTrend` | Tracks SEO scores over time to show improvement or regression trends. Reads from `SeoScoreHistory` model. Provides daily, weekly, and monthly aggregation. | diff --git a/src/Core/Seo/Console/Commands/CLAUDE.md b/src/Core/Seo/Console/Commands/CLAUDE.md new file mode 100644 index 0000000..a6d5d96 --- /dev/null +++ b/src/Core/Seo/Console/Commands/CLAUDE.md @@ -0,0 +1,10 @@ +# Seo/Console/Commands/ — SEO Artisan Commands + +## Commands + +| Command | Purpose | +|---------|---------| +| `AuditCanonicalUrls` | Audits canonical URLs across all SEO metadata for conflicts and misconfigurations. | +| `GenerateServiceOgImages` | Batch-generates OG images for service/product pages. | +| `RecordSeoScores` | Records current SEO scores to history for trend tracking. Designed for scheduled execution. | +| `TestStructuredData` | Validates structured data (JSON-LD) across pages against schema.org specs. | diff --git a/src/Core/Seo/Controllers/CLAUDE.md b/src/Core/Seo/Controllers/CLAUDE.md new file mode 100644 index 0000000..b2c7644 --- /dev/null +++ b/src/Core/Seo/Controllers/CLAUDE.md @@ -0,0 +1,8 @@ +# Seo/Controllers/ — SEO HTTP Controllers + +## Controllers + +| Controller | Purpose | +|------------|---------| +| `SitemapController` | Generates XML sitemaps — sitemap index pointing to child sitemaps (pages, posts, etc.). | +| `OgImageController` | Serves dynamically generated Open Graph images for social media previews. | diff --git a/src/Core/Seo/Jobs/CLAUDE.md b/src/Core/Seo/Jobs/CLAUDE.md new file mode 100644 index 0000000..87605a0 --- /dev/null +++ b/src/Core/Seo/Jobs/CLAUDE.md @@ -0,0 +1,7 @@ +# Seo/Jobs/ — SEO Background Jobs + +## Jobs + +| Job | Purpose | +|-----|---------| +| `GenerateOgImageJob` | Queued job to generate Open Graph images for pages. Uses `DynamicOgImageService` to render and store OG images. | diff --git a/src/Core/Seo/Models/CLAUDE.md b/src/Core/Seo/Models/CLAUDE.md new file mode 100644 index 0000000..ec73f62 --- /dev/null +++ b/src/Core/Seo/Models/CLAUDE.md @@ -0,0 +1,7 @@ +# Seo/Models/ — SEO Eloquent Models + +## Models + +| Model | Purpose | +|-------|---------| +| `SeoScoreHistory` | Historical SEO score records. Polymorphic (`seoable_type`/`seoable_id`) for any model with SEO metadata. Stores point-in-time snapshots of scores and issues. Supports daily and weekly aggregation for trend analysis. | diff --git a/src/Core/Seo/Services/CLAUDE.md b/src/Core/Seo/Services/CLAUDE.md new file mode 100644 index 0000000..46beb80 --- /dev/null +++ b/src/Core/Seo/Services/CLAUDE.md @@ -0,0 +1,8 @@ +# Seo/Services/ — SEO Service Layer + +## Services + +| Service | Purpose | +|---------|---------| +| `SchemaBuilderService` | Generates JSON-LD structured data for schema.org types: Article, BlogPosting, HowTo, FAQ, BreadcrumbList, Organization, WebSite. Uses `SchemaValidator` for validation. | +| `ServiceOgImageService` | Generates Open Graph images for service/product pages. | diff --git a/src/Core/Seo/Validation/CLAUDE.md b/src/Core/Seo/Validation/CLAUDE.md new file mode 100644 index 0000000..e04b539 --- /dev/null +++ b/src/Core/Seo/Validation/CLAUDE.md @@ -0,0 +1,10 @@ +# Seo/Validation/ — SEO Validation + +## Validators + +| Class | Purpose | +|-------|---------| +| `CanonicalUrlValidator` | Detects canonical URL conflicts across SEO metadata. Finds multiple pages pointing to the same canonical URL. | +| `OgImageValidator` | Validates OG images — checks dimensions, file size, format, and accessibility. | +| `SchemaValidator` | Validates JSON-LD structured data against schema.org requirements. | +| `StructuredDataTester` | Comprehensive structured data testing — validates all JSON-LD on a page against schema.org specs. | diff --git a/src/Core/Storage/Commands/CLAUDE.md b/src/Core/Storage/Commands/CLAUDE.md new file mode 100644 index 0000000..afdcc24 --- /dev/null +++ b/src/Core/Storage/Commands/CLAUDE.md @@ -0,0 +1,9 @@ +# Storage/Commands/ — Storage Artisan Commands + +## Commands + +| Command | Signature | Purpose | +|---------|-----------|---------| +| `WarmCacheCommand` | `cache:warm` | Pre-populates cache with frequently accessed data. Options: `--stale` (only warm missing items), `--status` (show warming status), `--key=foo` (warm specific key). Prevents cold cache problems after deployments. | + +Uses the `CacheWarmer` service which modules register their warmable items with. diff --git a/src/Core/Storage/Events/CLAUDE.md b/src/Core/Storage/Events/CLAUDE.md new file mode 100644 index 0000000..fab0cef --- /dev/null +++ b/src/Core/Storage/Events/CLAUDE.md @@ -0,0 +1,9 @@ +# Storage/Events/ — Storage System Events + +## Events + +| Event | Fired When | Properties | +|-------|-----------|------------| +| `RedisFallbackActivated` | Redis becomes unavailable and fallback driver is activated | `context`, `errorMessage`, `fallbackDriver` (default: `database`) | + +Listeners can use this for alerting, monitoring, or graceful degradation when Redis fails. diff --git a/src/Core/Tests/Feature/CLAUDE.md b/src/Core/Tests/Feature/CLAUDE.md new file mode 100644 index 0000000..cc1ddb8 --- /dev/null +++ b/src/Core/Tests/Feature/CLAUDE.md @@ -0,0 +1,27 @@ +# Tests/Feature/ — Core Feature Tests + +Pest feature (integration) tests for the Core PHP framework. + +## Test Files + +| File | Tests | +|------|-------| +| `AdminComponentsTest.php` | Admin panel Livewire component rendering | +| `AdminRouteSmokeTest.php` | Admin route accessibility | +| `BladeViewCompilationTest.php` | Blade template compilation | +| `CdnIntegrationTest.php` | CDN URL building and asset delivery | +| `CoreComponentsTest.php` | Core UI component rendering | +| `DatabaseMigrationTest.php` | Migration execution | +| `EmailShieldTest.php` | Email validation and disposable blocking | +| `ErrorPagesTest.php` | Custom error page rendering | +| `ImageOptimizerTest.php` | Image optimisation pipeline | +| `MailConfigurationTest.php` | Mail driver configuration | +| `ModuleScannerIntegrationTest.php` | Full module discovery flow | +| `OffloadMigrateCommandTest.php` | Storage offload migration command | +| `PerformanceBaselineTest.php` | Response time baselines | +| `ResilientSessionTest.php` | Session fallback handling | +| `RewriteOffloadedUrlsTest.php` | URL rewriting for offloaded assets | +| `SecurityFixesTest.php` | Security vulnerability patches | +| `SecurityHeadersTest.php` | HTTP security header enforcement | +| `StorageOffloadTest.php` | File offloading to remote storage | +| `ValidationRulesTest.php` | Custom validation rule behaviour | diff --git a/src/Core/Tests/Feature/Config/CLAUDE.md b/src/Core/Tests/Feature/Config/CLAUDE.md new file mode 100644 index 0000000..bef1fe9 --- /dev/null +++ b/src/Core/Tests/Feature/Config/CLAUDE.md @@ -0,0 +1,8 @@ +# Tests/Feature/Config/ — Config Feature Tests + +## Test Files + +| File | Purpose | +|------|---------| +| `ChannelTest.php` | Tests for the `Channel` model — creation, inheritance chain, cycle detection, workspace scoping, `byCode()` lookup. | +| `ConfigValueTest.php` | Tests for `ConfigValue` model — value storage, encryption of sensitive keys, FINAL lock semantics, typed value retrieval. | diff --git a/src/Core/Tests/Unit/CLAUDE.md b/src/Core/Tests/Unit/CLAUDE.md new file mode 100644 index 0000000..e7da58d --- /dev/null +++ b/src/Core/Tests/Unit/CLAUDE.md @@ -0,0 +1,18 @@ +# Tests/Unit/ — Core Unit Tests + +Pest unit tests for core framework components. + +## Test Files + +| File | Tests | +|------|-------| +| `ApiVersionTest.php` | API versioning logic | +| `ComponentBuildersTest.php` | UI component builder patterns | +| `HadesEncryptTest.php` | Hades encryption utilities | +| `LazyModuleListenerTest.php` | Lazy module instantiation and event handling | +| `LthnHashTest.php` | Custom hashing implementation | +| `ModuleScannerTest.php` | Module discovery from Boot.php files | +| `PrivacyHelperTest.php` | Privacy/GDPR helper functions | +| `UtmHelperTest.php` | UTM parameter handling | + +These test the root-level Core framework components (Boot, ModuleScanner, LazyModuleListener) and shared utilities. diff --git a/src/Core/Tests/Unit/Crypt/CLAUDE.md b/src/Core/Tests/Unit/Crypt/CLAUDE.md new file mode 100644 index 0000000..19e86cb --- /dev/null +++ b/src/Core/Tests/Unit/Crypt/CLAUDE.md @@ -0,0 +1,7 @@ +# Tests/Unit/Crypt/ — Encryption Unit Tests + +## Test Files + +| File | Purpose | +|------|---------| +| `EncryptArrayObjectTest.php` | Tests for encrypting and decrypting array/object data structures. Validates the Crypt subsystem's handling of complex data types. | diff --git a/src/Core/Tests/Unit/Services/CLAUDE.md b/src/Core/Tests/Unit/Services/CLAUDE.md new file mode 100644 index 0000000..24cc1d3 --- /dev/null +++ b/src/Core/Tests/Unit/Services/CLAUDE.md @@ -0,0 +1,7 @@ +# Tests/Unit/Services/ — Service Unit Tests + +## Test Files + +| File | Purpose | +|------|---------| +| `BunnyCdnServiceTest.php` | Unit tests for the BunnyCDN pull zone API service. Tests cache purging, statistics retrieval, and pull zone management. | diff --git a/src/Mod/CLAUDE.md b/src/Mod/CLAUDE.md new file mode 100644 index 0000000..3c0e2c6 --- /dev/null +++ b/src/Mod/CLAUDE.md @@ -0,0 +1,45 @@ +# Mod -- Module Aggregator + +`Core\Mod\Boot` is a minimal ServiceProvider that acts as the namespace root for feature modules bundled with the core-php package. + +## How It Works + +Each module lives in a subdirectory (e.g., `Mod/Trees/`) with its own `Boot.php`. Modules self-register through the lifecycle event system -- they declare a static `$listens` array and are discovered by `ModuleScanner` during `LifecycleEventProvider::register()`. + +`Mod\Boot` itself does nothing in `register()` or `boot()`. It exists purely as the ServiceProvider entry point listed in `Core\Boot::$providers`. + +## Module Structure Convention + +``` +Mod/ + {ModuleName}/ + Boot.php # $listens declaration + event handlers + Console/ # Artisan commands + Controllers/ # HTTP controllers (Api/, Web/) + Database/Seeders/ # Database seeders + Jobs/ # Queue jobs + Lang/ # Translation files + Listeners/ # Event listeners + Middleware/ # HTTP middleware + Models/ # Eloquent models + Notifications/ # Notification classes + Routes/ # Route files (api.php, web.php) + Tests/ # Feature and Unit tests + View/ # Blade templates and Livewire components + Blade/ # Blade view files + Modal/ # Livewire components (organized by frontage) +``` + +## Namespace + +`Core\Mod\{ModuleName}` -- autoloaded via PSR-4 from `src/Mod/`. + +## Adding a Module + +1. Create `Mod/{Name}/Boot.php` with `public static array $listens` +2. Implement event handler methods referenced in `$listens` +3. The scanner discovers it automatically -- no registration needed + +## Current Modules + +- `Trees/` -- Trees for Agents initiative (see `Trees/CLAUDE.md`) diff --git a/src/Mod/Trees/CLAUDE.md b/src/Mod/Trees/CLAUDE.md new file mode 100644 index 0000000..208a267 --- /dev/null +++ b/src/Mod/Trees/CLAUDE.md @@ -0,0 +1,87 @@ +# Trees for Agents + +A module implementing the "Trees for Agents" programme: when an AI agent refers a user to the platform, a tree is planted with Trees for the Future (TFTF). The module tracks plantings, manages a pre-paid reserve, provides a public leaderboard, and handles batch donations. + +## Namespace + +`Core\Mod\Trees` -- autoloaded from `src/Mod/Trees/`. + +## Lifecycle Events + +```php +public static array $listens = [ + ApiRoutesRegistering::class => 'onApiRoutes', + WebRoutesRegistering::class => 'onWebRoutes', + ConsoleBooting::class => 'onConsole', +]; +``` + +## Models + +| Model | Purpose | +|-------|---------| +| `TreePlanting` | Individual tree planting record. Workspace-scoped (`BelongsToWorkspace`). Tracks provider, model, source, status, TFTF reference. Statuses: `pending` -> `confirmed` -> `planted` (or `queued` if reserve depleted). | +| `TreeReserve` | Singleton row managing the pre-paid tree reserve. Tracks current level, total decremented/replenished. Warning at 50, critical at 10, depleted at 0. Sends `LowTreeReserveNotification` to admins. | +| `TreeDonation` | Batch donation record. Created when confirmed trees are batched into a monthly TFTF donation. Cost: $0.25/tree. | +| `TreePlantingStats` | Aggregated daily stats by provider/model. Atomic upsert for concurrent safety. Powers leaderboard and provider breakdowns. | + +## Planting Flow + +``` +Agent referral visit (/ref/{provider}/{model}) + -> User signs up + -> PlantTreeForAgentReferral listener fires on Registered event + -> Checks daily limit (1 free tree/day) and guaranteed bonus + -> Creates TreePlanting (pending or queued) + -> If pending: markConfirmed() decrements reserve + updates stats + -> If queued: waits for trees:process-queue command +``` + +## Valid Providers + +`anthropic`, `openai`, `google`, `meta`, `mistral`, `local`, `unknown` + +## Console Commands + +| Command | Schedule | Purpose | +|---------|----------|---------| +| `trees:process-queue` | Daily | Processes oldest queued tree planting. Supports `--dry-run`. | +| `trees:donate` | Monthly (28th) | Batches confirmed trees into TFTF donation. Creates `TreeDonation`, marks plantings as `planted`, optionally replenishes reserve. Supports `--dry-run` and `--replenish=N`. | +| `trees:reserve:add {count}` | Manual | Replenishes reserve after a TFTF donation. Supports `--force`. | + +## API Endpoints (public, no auth) + +All under `api` middleware with `throttle:60,1`: + +| Route | Controller Method | Returns | +|-------|------------------|---------| +| `GET /trees/stats` | `index()` | Global totals, monthly/yearly, queue size | +| `GET /trees/stats/{provider}` | `provider()` | Provider totals + model breakdown | +| `GET /trees/stats/{provider}/{model}` | `model()` | Model-specific stats | +| `GET /trees/leaderboard` | `leaderboard()` | Top 20 providers by trees planted | + +## Web Routes + +| Route | Component | Purpose | +|-------|-----------|---------| +| `GET /trees` | `trees.index` Livewire | Public leaderboard page | +| `GET /ref/{provider}/{model?}` | `ReferralController@track` | Agent referral tracking (sets cookie/session) | + +## Middleware + +`IncludeAgentContext` -- Adds `for_agents` context to 401 JSON responses when the request comes from an AI agent. Includes referral URL, impact stats, and programme links. Depends on `Core\Agentic\Services\AgentDetection`. + +## Key Classes + +| Class | Purpose | +|-------|---------| +| `PlantTreeForAgentReferral` | Listener on `Registered` event. Checks referral data, daily limits, bonus system. | +| `PlantTreeWithTFTF` | Queue job for confirming plantings. 3 retries, 60s backoff. | +| `LowTreeReserveNotification` | Mail notification at warning/critical/depleted levels. | +| `View\Modal\Web\Index` | Livewire component for the public leaderboard page. | + +## Dependencies + +- `Core\Tenant` -- `BelongsToWorkspace` trait, `ReferralController`, `AgentReferralBonus` +- `Core\Agentic` -- `AgentDetection`, `AgentIdentity` (for middleware) +- `Core\Front` -- `Controller` base class diff --git a/src/Plug/CLAUDE.md b/src/Plug/CLAUDE.md new file mode 100644 index 0000000..e465bca --- /dev/null +++ b/src/Plug/CLAUDE.md @@ -0,0 +1,107 @@ +# Plug -- Plugin System for External Service Integrations + +`Core\Plug` is an operation-based plugin architecture for connecting to external services (social networks, Web3, content platforms, chat, business tools). Each provider is split into discrete operation classes rather than monolithic adapters. + +## Namespace + +`Core\Plug` -- autoloaded from `src/Plug/`. + +## Architecture + +Providers are organised by category and operation: + +``` +Plug/ + Social/ + Twitter/ + Auth.php # implements Authenticable + Post.php # implements Postable + Delete.php # implements Deletable + Media.php # implements MediaUploadable + Bluesky/ + Auth.php + Post.php + Web3/ + Content/ + Chat/ + Business/ +``` + +Usage: +```php +use Core\Plug\Social\Twitter\Auth; +use Core\Plug\Social\Twitter\Post; + +$auth = new Auth($clientId, $clientSecret, $redirectUrl); +$post = (new Post())->withToken($token); +``` + +## Key Classes + +### Boot (ServiceProvider) + +Registers `Registry` as a singleton with alias `plug.registry`. Pure library module -- no routes, views, or migrations. + +### Registry + +Auto-discovers providers from directory structure. Scans categories: `Social`, `Web3`, `Content`, `Chat`, `Business`. + +**Public API:** + +| Method | Purpose | +|--------|---------| +| `discover()` | Scans category directories for provider folders. Idempotent. | +| `register(id, category, name, namespace)` | Programmatic registration (for external packages). | +| `identifiers()` | All registered provider identifiers (lowercase). | +| `has(identifier)` | Check if provider exists. | +| `get(identifier)` | Get provider metadata (category, name, namespace, path). | +| `supports(identifier, operation)` | Check if provider has an operation class. | +| `operation(identifier, operation)` | Get the FQCN for a provider's operation class. | +| `all()` | All providers as Collection. | +| `byCategory(category)` | Provider identifiers filtered by category. | +| `withCapability(operation)` | Providers that support a specific operation. | +| `displayName(identifier)` | Human-readable name (from Auth::name() or directory name). | + +### Response + +Standardised response for all Plug operations. Immutable value object. + +**Properties:** `status` (Status enum), `context` (array), `rateLimitApproaching` (bool), `retryAfter` (int). + +**Methods:** `isOk()`, `hasError()`, `isUnauthorized()`, `isRateLimited()`, `id()`, `get(key)`, `getMessage()`, `retryAfter()`, `toArray()`. Supports magic `__get` for context values. + +## Contracts (interfaces) + +| Contract | Methods | Purpose | +|----------|---------|---------| +| `Authenticable` | `identifier()`, `name()`, `getAuthUrl()`, `requestAccessToken(params)`, `getAccount()` | OAuth2/API key/credential auth flows | +| `Postable` | `publish(text, media, params)` | Content publishing | +| `Readable` | `get(id)`, `list(params)` | Read posts/content | +| `Commentable` | `comment(text, postId, params)` | Reply to content | +| `Deletable` | `delete(id)` | Delete content | +| `MediaUploadable` | `upload(item)` | Upload media files | +| `Listable` | `listEntities()` | List pages/boards/publications (target selection) | +| `Refreshable` | `refresh()` | Refresh expired access tokens | + +## Concerns (traits) + +| Trait | Purpose | +|-------|---------| +| `BuildsResponse` | Response factory helpers: `ok()`, `error()`, `unauthorized()`, `rateLimit()`, `noContent()`, `fromHttp()`. The `fromHttp()` method auto-maps HTTP status codes (401, 429) to correct Response types. | +| `ManagesTokens` | Token lifecycle: `withToken()`, `getToken()`, `accessToken()`, `hasRefreshToken()`, `refreshToken()`, `tokenExpiresSoon(minutes)`, `tokenExpired()`. Fluent interface via `withToken()`. | +| `UsesHttp` | HTTP client helpers: `http()` (configured PendingRequest with 30s timeout, JSON accept, User-Agent), `buildUrl()`. Override `defaultHeaders()` for provider-specific headers. | + +## Enum + +`Status` -- string-backed: `OK`, `ERROR`, `UNAUTHORIZED`, `RATE_LIMITED`, `NO_CONTENT`. + +## Integration Pattern + +1. Create provider directory under the appropriate category +2. Implement operation classes using contracts + concerns +3. Registry auto-discovers on first access (or register programmatically) +4. All operations return `Response` objects for consistent error handling + +## Categories + +`Social`, `Web3`, `Content`, `Chat`, `Business` diff --git a/src/Website/CLAUDE.md b/src/Website/CLAUDE.md new file mode 100644 index 0000000..1e3c79f --- /dev/null +++ b/src/Website/CLAUDE.md @@ -0,0 +1,87 @@ +# Website -- Domain-Scoped Module System + +`Core\Website` provides lazy-loading of website modules based on the incoming HTTP domain. Only the matching provider is registered for a given request, isolating errors so one broken website does not take down others. + +## Namespace + +`Core\Website` -- autoloaded from `src/Website/`. + +## How It Works + +### Web Requests + +1. `Website\Boot::register()` reads `$_SERVER['HTTP_HOST']` +2. Dispatches a `DomainResolving` event with the hostname +3. Website modules listening for `DomainResolving` check if the host matches their `$domains` patterns +4. The first matching provider is registered via `$app->register()` +5. Only that one provider boots -- all others are skipped + +### CLI Context (artisan, tests, queues) + +All website providers are loaded via `registerAllProviders()`, which scans `app/Mod/*/Boot.php` for website module Boot classes. This ensures artisan commands, seeders, and queue workers can access all website modules. + +## Files + +### Boot.php (ServiceProvider) + +- Registers `DomainResolver` as singleton +- Web: fires `DomainResolving` event, registers matched provider +- CLI: loads all providers from `app/Mod/` +- Provider load order: must come before `Front\Boot` so listeners are wired before frontage events fire + +### DomainResolver + +Utility for working with domain patterns. Website Boot classes declare domains as regex patterns: + +```php +class Boot extends ServiceProvider +{ + public static array $domains = [ + '/^example\.(com|test)$/', + ]; +} +``` + +**Methods:** + +| Method | Purpose | +|--------|---------| +| `extractDomains(providerClass)` | Read `$domains` static property via reflection | +| `domainsFor(providerClass)` | Convert regex patterns to concrete domain strings. In local env, filters to `.test`/`.localhost` only. | + +Pattern expansion handles: +- Fixed domains: `example.com` +- TLD alternatives: `example\.(com|test)` -> `example.com`, `example.test` +- Optional www prefix: `(www\.)?example\.com` + +## Writing a Website Module + +Website modules live in `app/Mod/{Name}/` (not `src/Mod/`). They use the same `$listens` pattern as regular modules: + +```php +namespace Mod\MyWebsite; + +class Boot extends ServiceProvider +{ + public static array $domains = [ + '/^mysite\.(com|test)$/', + ]; + + public static array $listens = [ + WebRoutesRegistering::class => 'onWebRoutes', + ]; + + public function onWebRoutes(WebRoutesRegistering $event): void + { + $event->routes(fn () => require __DIR__.'/Routes/web.php'); + $event->views('mysite', __DIR__.'/Views'); + } +} +``` + +## Key Design Decisions + +- **Isolation**: One broken website module cannot crash others since only the matched provider loads +- **Lazy loading**: Website modules are not instantiated unless their domain matches +- **Dual paths**: Framework-bundled modules in `src/Mod/`, application modules in `app/Mod/` +- **Environment-aware**: Local dev only serves `.test`/`.localhost` domains from `domainsFor()`