docs: update CLAUDE.md to reflect package structure
Previous version described the application template, but this repository is the core-content package. Updated to document actual namespace, structure, models, API routes, rate limiters, and configuration. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
35946a895b
commit
5c92e92a29
1 changed files with 77 additions and 46 deletions
123
CLAUDE.md
123
CLAUDE.md
|
|
@ -1,66 +1,97 @@
|
|||
# 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`.
|
||||
## Package Overview
|
||||
|
||||
**Event-driven registration:**
|
||||
```php
|
||||
class Boot
|
||||
{
|
||||
public static array $listens = [
|
||||
WebRoutesRegistering::class => 'onWebRoutes',
|
||||
ApiRoutesRegistering::class => 'onApiRoutes',
|
||||
AdminPanelBooting::class => 'onAdminPanel',
|
||||
];
|
||||
}
|
||||
```
|
||||
This is `host-uk/core-content`, a Laravel package providing headless CMS functionality for the Core PHP Framework. It handles content management, AI generation, revisions, webhooks, and search.
|
||||
|
||||
**Namespace:** `Core\Mod\Content\`
|
||||
|
||||
## 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
|
||||
composer run lint # Laravel Pint (PSR-12)
|
||||
composer run test # Pest tests
|
||||
./vendor/bin/pint --dirty # Format changed files only
|
||||
./vendor/bin/pest --filter=ContentSearch # Run specific tests
|
||||
```
|
||||
|
||||
## Module Structure
|
||||
## Architecture
|
||||
|
||||
```
|
||||
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
|
||||
### Boot.php (Service Provider)
|
||||
|
||||
The entry point extending `ServiceProvider` with event-driven registration:
|
||||
|
||||
```php
|
||||
public static array $listens = [
|
||||
WebRoutesRegistering::class => 'onWebRoutes',
|
||||
ApiRoutesRegistering::class => 'onApiRoutes',
|
||||
ConsoleBooting::class => 'onConsole',
|
||||
McpToolsRegistering::class => 'onMcpTools',
|
||||
];
|
||||
```
|
||||
|
||||
## Packages
|
||||
### Package Structure
|
||||
|
||||
| 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-mcp` | Model Context Protocol for AI agents |
|
||||
```
|
||||
Boot.php # Service provider + event listeners
|
||||
config.php # Package configuration
|
||||
Models/ # Eloquent: ContentItem, ContentBrief, ContentRevision, etc.
|
||||
Services/ # Business logic: ContentSearchService, ContentRender, etc.
|
||||
Controllers/Api/ # REST API controllers
|
||||
Mcp/Handlers/ # MCP tools for AI agent integration
|
||||
Jobs/ # Queue jobs: GenerateContentJob, ProcessContentWebhook
|
||||
View/Modal/ # Livewire components (Web/ and Admin/)
|
||||
View/Blade/ # Blade templates
|
||||
Migrations/ # Database migrations
|
||||
routes/ # web.php, api.php, console.php
|
||||
```
|
||||
|
||||
### Key Models
|
||||
|
||||
| Model | Purpose |
|
||||
|-------|---------|
|
||||
| `ContentItem` | Published content with revisions |
|
||||
| `ContentBrief` | Content generation requests/queue |
|
||||
| `ContentRevision` | Version history for content items |
|
||||
| `ContentMedia` | Attached media files |
|
||||
| `ContentTaxonomy` | Categories and tags |
|
||||
| `ContentWebhookEndpoint` | External webhook configurations |
|
||||
|
||||
### API Routes (routes/api.php)
|
||||
|
||||
- `/api/content/briefs` - Content brief CRUD
|
||||
- `/api/content/generate/*` - AI generation (rate limited)
|
||||
- `/api/content/media` - Media management
|
||||
- `/api/content/search` - Full-text search
|
||||
- `/api/content/webhooks/{endpoint}` - External webhooks (no auth, signature verified)
|
||||
|
||||
## Conventions
|
||||
|
||||
- UK English (colour, organisation, centre)
|
||||
- PSR-12 coding style (Laravel Pint)
|
||||
- Pest for testing
|
||||
- Livewire + Flux Pro for UI
|
||||
- `declare(strict_types=1);` in all PHP files
|
||||
- Type hints on all parameters and return types
|
||||
- Pest for testing (not PHPUnit syntax)
|
||||
- Livewire + Flux Pro for UI components
|
||||
- Font Awesome Pro for icons (not Heroicons)
|
||||
|
||||
## Rate Limiters
|
||||
|
||||
Defined in `Boot::configureRateLimiting()`:
|
||||
- `content-generate` - AI generation (10/min authenticated)
|
||||
- `content-briefs` - Brief creation (30/min)
|
||||
- `content-webhooks` - Incoming webhooks (60/min per endpoint)
|
||||
- `content-search` - Search queries (configurable, default 60/min)
|
||||
|
||||
## Configuration (config.php)
|
||||
|
||||
Key settings exposed via environment:
|
||||
- `CONTENT_GENERATION_TIMEOUT` - AI generation timeout
|
||||
- `CONTENT_MAX_REVISIONS` - Revision limit per item
|
||||
- `CONTENT_SEARCH_BACKEND` - Search driver (database, scout_database, meilisearch)
|
||||
- `CONTENT_CACHE_TTL` - Content cache duration
|
||||
|
||||
## 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 (European Union Public Licence)
|
||||
Loading…
Add table
Reference in a new issue