docs: add CLAUDE.md project instructions
Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Snider
parent
67b5eb2af9
commit
f4fc6976de
1 changed files with 34 additions and 41 deletions
75
CLAUDE.md
75
CLAUDE.md
|
|
@ -4,67 +4,59 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||
|
||||
## Overview
|
||||
|
||||
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.
|
||||
This is the **Core Admin Package** (`lthn/php-admin`) - an admin panel and service layer for the Core PHP Framework. It provides the Hub dashboard, form components with authorisation, global search, Livewire modals, and honeypot security monitoring.
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
php artisan serve # Laravel dev server
|
||||
npm run dev # Vite dev server
|
||||
npm run dev # Vite dev server (Tailwind v4)
|
||||
npm run build # Production asset build
|
||||
./vendor/bin/pint --dirty # Format changed files only
|
||||
./vendor/bin/pest # Run all tests
|
||||
./vendor/bin/pest --filter=SearchTest # Run specific test
|
||||
```
|
||||
|
||||
CI matrix: PHP 8.2, 8.3, 8.4.
|
||||
|
||||
## Architecture
|
||||
|
||||
This package contains three Boot.php files that wire up different concerns:
|
||||
Four Boot.php files wire up different concerns via event-driven registration:
|
||||
|
||||
| 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 |
|
||||
| `src/Boot.php` | `Core\Admin\` | Main package provider - form components (`core-forms` prefix), search registry singleton |
|
||||
| `src/Website/Hub/Boot.php` | `Website\Hub\` | Admin frontend - routes, Livewire components, menu. Activates via domain pattern matching (`/^(hub\.)?core\.(test\|localhost)$/`) |
|
||||
| `src/Mod/Hub/Boot.php` | `Core\Admin\Mod\Hub\` | Admin backend - models, migrations, 30+ Livewire modals. Lazy-loads on `AdminPanelBooting` event |
|
||||
| `Service/Boot.php` | `Core\Service\Admin\` | Service definition for `platform_services` table |
|
||||
|
||||
**Key pattern — event-driven lazy loading:**
|
||||
Boot classes declare a static `$listens` array mapping events to handler methods. Modules only register their components when the relevant event fires (e.g., `AdminPanelBooting`), not at application boot. This is important to understand when adding new features — registration happens in event handlers, not in `register()`/`boot()`.
|
||||
|
||||
**Event-driven registration pattern:**
|
||||
```php
|
||||
class Boot extends ServiceProvider
|
||||
{
|
||||
public static array $listens = [
|
||||
AdminPanelBooting::class => 'onAdminPanel',
|
||||
DomainResolving::class => 'onDomainResolving',
|
||||
];
|
||||
}
|
||||
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.
|
||||
**Form Components** (`src/Forms/`) - Class-backed Blade components with `core-forms` prefix and authorisation via `HasAuthorizationProps` trait:
|
||||
- Props: `canGate`, `canResource`, `canHide` for permission-based disable/hide
|
||||
- Authorisation only checks when BOTH `canGate` AND `canResource` are set; explicit `disabled` prop takes precedence
|
||||
- 7 components: Input, Textarea, Select, Checkbox, Button, Toggle, FormGroup
|
||||
|
||||
**Search System** (`src/Search/`) - Extensible provider-based search:
|
||||
- Implement `SearchProvider` interface with `search()`, `searchType()`, `getUrl()`
|
||||
- Register providers via `SearchProviderRegistry`
|
||||
**Search System** (`src/Search/`) - Provider-based search with fuzzy matching and relevance scoring:
|
||||
- Implement `SearchProvider` interface: `search()`, `searchType()`, `searchLabel()`, `searchIcon()`, `getUrl()`, `searchPriority()`, `isAvailable()`
|
||||
- `SearchProviderRegistry` aggregates providers, sorts by priority (lower = higher), calculates relevance scores (100=exact, 90=starts-with, 80=whole-word, 70=substring, 60=word-start, 40=fuzzy)
|
||||
- Built-in `AdminPageSearchProvider` covers 13 admin pages at priority 10
|
||||
|
||||
**Admin Menu** - Implement `AdminMenuProvider` interface to add menu items
|
||||
**Admin Menu** - Implement `AdminMenuProvider` interface. Items have `group` (dashboard, workspaces, settings, admin), `priority`, `icon`, and optional `'admin' => true` flag. Menu registration uses closures for deferred route resolution.
|
||||
|
||||
### Directory Structure
|
||||
**Honeypot Security** (`src/Mod/Hub/Models/HoneypotHit`) - Tracks attacks with severity levels ("warning" for robots.txt violations, "critical" for admin probing). Includes bot detection for 23+ patterns and IP/geo tracking.
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
**Livewire Modals** - Full-page Livewire components using `->layout('hub::admin.layouts.app')`. Routes are GET-based (Livewire handles forms internally). Routes prefixed with `/hub`, named `hub.*`.
|
||||
|
||||
## Conventions
|
||||
|
||||
|
|
@ -73,17 +65,18 @@ src/
|
|||
- **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
|
||||
- **Pest** - Write tests using Pest `describe`/`it` syntax with `expect()` assertions
|
||||
- **Immutable DTOs** - Use readonly properties; mutation methods return new instances (see `SearchResult::withTypeAndIcon()`)
|
||||
|
||||
## Packages
|
||||
|
||||
| Package | Purpose |
|
||||
|---------|---------|
|
||||
| `host-uk/core` | Core framework, events, module discovery |
|
||||
| `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 |
|
||||
| `lthn/php` | Core framework, events, module discovery |
|
||||
| `lthn/php-admin` | This package - admin panel, modals |
|
||||
| `lthn/php-api` | REST API, scopes, rate limiting |
|
||||
| `lthn/php-mcp` | Model Context Protocol for AI agents |
|
||||
|
||||
## License
|
||||
|
||||
EUPL-1.2 (copyleft) - See LICENSE for details.
|
||||
EUPL-1.2 (copyleft) - See LICENSE for details.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue