From 63f274f83a7363bac5367c43984e9b3887916c08 Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Wed, 28 Jan 2026 14:03:40 +0000
Subject: [PATCH] docs: update CLAUDE.md for core-admin package specifics

Replace generic framework template with package-specific guidance:
- Document the three Boot.php architecture pattern
- Add Form Components and Search System sections
- Update commands to match actual package scripts
- Simplify directory structure to focus on src/

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 109 +++++++++++++++++++++++++++++++++---------------------
 1 file changed, 66 insertions(+), 43 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 138e17b..0680e41 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,66 +1,89 @@
-# Core PHP Framework Project
+# CLAUDE.md
 
-## Architecture
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-Modular monolith using Core PHP Framework. Modules live in `app/Mod/{Name}/Boot.php`.
+## Overview
 
-**Event-driven registration:**
-```php
-class Boot
-{
-    public static array $listens = [
-        WebRoutesRegistering::class => 'onWebRoutes',
-        ApiRoutesRegistering::class => 'onApiRoutes',
-        AdminPanelBooting::class => 'onAdminPanel',
-    ];
-}
-```
+This is the **Core Admin Package** (`host-uk/core-admin`) - an admin panel and service layer for the Core PHP Framework. It provides the Hub dashboard, form components with authorization, global search, and Livewire modals.
 
 ## Commands
 
 ```bash
-composer run dev              # Dev server (if configured)
 php artisan serve             # Laravel dev server
-npm run dev                   # Vite
-./vendor/bin/pint --dirty     # Format changed files
-php artisan test              # All tests
-php artisan make:mod Blog     # Create module
+npm run dev                   # Vite dev server
+./vendor/bin/pint --dirty     # Format changed files only
+./vendor/bin/pest             # Run all tests
+./vendor/bin/pest --filter=SearchTest  # Run specific test
 ```
 
-## Module Structure
+## Architecture
+
+This package contains three Boot.php files that wire up different concerns:
+
+| File | Namespace | Purpose |
+|------|-----------|---------|
+| `src/Boot.php` | `Core\Admin\` | Main package provider - form components, search registry |
+| `src/Website/Hub/Boot.php` | `Website\Hub\` | Admin dashboard frontend - routes, Livewire components, menu |
+| `src/Mod/Hub/Boot.php` | `Core\Admin\Mod\Hub\` | Admin backend - models, migrations, 20+ Livewire modals |
+| `Service/Boot.php` | `Core\Service\Admin\` | Service definition for platform_services table |
+
+**Event-driven registration pattern:**
+```php
+class Boot extends ServiceProvider
+{
+    public static array $listens = [
+        AdminPanelBooting::class => 'onAdminPanel',
+        DomainResolving::class => 'onDomainResolving',
+    ];
+}
+```
+
+### Key Systems
+
+**Form Components** (`src/Forms/`) - Blade components with authorization via `HasAuthorizationProps` trait:
+- `<x-core-forms.input />`, `<x-core-forms.select />`, `<x-core-forms.toggle />`, etc.
+- Props: `canGate`, `canResource`, `canHide` for permission-based disable/hide
+
+**Search System** (`src/Search/`) - Extensible provider-based search:
+- Implement `SearchProvider` interface with `search()`, `searchType()`, `getUrl()`
+- Register providers via `SearchProviderRegistry`
+
+**Admin Menu** - Implement `AdminMenuProvider` interface to add menu items
+
+### Directory Structure
 
 ```
-app/Mod/Blog/
-├── Boot.php              # Event listeners
-├── Models/               # Eloquent models
-├── Routes/
-│   ├── web.php          # Web routes
-│   └── api.php          # API routes
-├── Views/               # Blade templates
-├── Livewire/            # Livewire components
-├── Migrations/          # Database migrations
-└── Tests/               # Module tests
+src/
+├── Boot.php                    # Package service provider
+├── Forms/                      # Form components with authorization
+├── Search/                     # Global search system
+├── Website/Hub/                # Admin dashboard frontend
+│   ├── Routes/admin.php        # Admin web routes
+│   └── View/                   # Blade templates + Livewire components
+└── Mod/Hub/                    # Admin backend module
+    ├── Models/                 # Service, HoneypotHit
+    ├── Migrations/             # platform_services, honeypot_hits
+    └── Boot.php                # Module registration + 20 Livewire modals
 ```
 
+## Conventions
+
+- **UK English** - colour, organisation, centre (never American spellings)
+- **Strict types** - `declare(strict_types=1);` in every PHP file
+- **Type hints** - All parameters and return types
+- **Flux Pro** - Use Flux components, not vanilla Alpine
+- **Font Awesome Pro** - Use FA icons, not Heroicons
+- **Pest** - Write tests using Pest syntax
+
 ## Packages
 
 | Package | Purpose |
 |---------|---------|
 | `host-uk/core` | Core framework, events, module discovery |
-| `host-uk/core-admin` | Admin panel, Livewire modals |
-| `host-uk/core-api` | REST API, scopes, rate limiting, webhooks |
+| `host-uk/core-admin` | This package - admin panel, modals |
+| `host-uk/core-api` | REST API, scopes, rate limiting |
 | `host-uk/core-mcp` | Model Context Protocol for AI agents |
 
-## Conventions
-
-- UK English (colour, organisation, centre)
-- PSR-12 coding style (Laravel Pint)
-- Pest for testing
-- Livewire + Flux Pro for UI
-
 ## License
 
-- `Core\` namespace and vendor packages: EUPL-1.2 (copyleft)
-- `app/Mod/*`, `app/Website/*`: Your choice (no copyleft)
-
-See LICENSE for full details.
+EUPL-1.2 (copyleft) - See LICENSE for details.
\ No newline at end of file