Snider 5c92e92a29 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>

2026-01-28 14:08:45 +00:00

3.2 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Package Overview

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

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

Architecture

Boot.php (Service Provider)

The entry point extending ServiceProvider with event-driven registration:

public static array $listens = [
    WebRoutesRegistering::class => 'onWebRoutes',
    ApiRoutesRegistering::class => 'onApiRoutes',
    ConsoleBooting::class => 'onConsole',
    McpToolsRegistering::class => 'onMcpTools',
];

Package Structure

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)
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

EUPL-1.2 (European Union Public Licence)

3.2 KiB Raw Blame History