docs: rewrite CLAUDE.md for core-api package specifics
Replace generic monorepo instructions with package-specific guidance: - Document actual src/ structure with Core\Api and Core\Website\Api namespaces - Add package-relevant commands (pest, pint) - Document key middleware components and OpenAPI attributes - Remove irrelevant app/Mod/ module structure references Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
d77ebdf69e
commit
1da124a92a
1 changed files with 70 additions and 45 deletions
115
CLAUDE.md
115
CLAUDE.md
|
|
@ -1,66 +1,91 @@
|
|||
# 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-api`, a Laravel package providing REST API infrastructure: OpenAPI documentation, rate limiting, webhook signing, and secure API key management. Part of the Core PHP Framework monorepo ecosystem.
|
||||
|
||||
## 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
|
||||
./vendor/bin/pest # Run all tests
|
||||
./vendor/bin/pest --filter=ApiKey # Run tests matching "ApiKey"
|
||||
./vendor/bin/pint --dirty # Format changed files
|
||||
./vendor/bin/pint src/ # Format specific directory
|
||||
```
|
||||
|
||||
## Module Structure
|
||||
## Package 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/
|
||||
├── Api/ # Core\Api namespace
|
||||
│ ├── Boot.php # Service provider, event listeners
|
||||
│ ├── config.php # Package configuration
|
||||
│ ├── Middleware/ # API auth, rate limiting, scopes
|
||||
│ ├── Models/ # ApiKey, WebhookEndpoint, etc.
|
||||
│ ├── Services/ # Business logic (webhooks, keys)
|
||||
│ ├── Documentation/ # OpenAPI spec generation
|
||||
│ │ ├── Attributes/ # #[ApiTag], #[ApiResponse], etc.
|
||||
│ │ ├── Extensions/ # API docs extensions
|
||||
│ │ └── OpenApiBuilder.php # Spec generator
|
||||
│ ├── RateLimit/ # Per-endpoint rate limiting
|
||||
│ ├── Resources/ # API JSON resources
|
||||
│ └── Tests/Feature/ # Package tests
|
||||
│
|
||||
└── Website/Api/ # Core\Website\Api namespace
|
||||
├── Boot.php # Web routes service provider
|
||||
├── Controllers/ # DocsController
|
||||
├── Routes/web.php # /api/docs, /api/guides routes
|
||||
├── Services/ # OpenApiGenerator
|
||||
└── View/Blade/ # API docs UI templates
|
||||
```
|
||||
|
||||
## Packages
|
||||
## Architecture
|
||||
|
||||
| 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 |
|
||||
**Two-namespace design:**
|
||||
- `Core\Api\` — Backend API logic (middleware, models, services)
|
||||
- `Core\Website\Api\` — Frontend documentation UI (controllers, views)
|
||||
|
||||
**Event-driven boot** via `$listens` array in Boot classes:
|
||||
```php
|
||||
public static array $listens = [
|
||||
AdminPanelBooting::class => 'onAdminPanel',
|
||||
ApiRoutesRegistering::class => 'onApiRoutes',
|
||||
ConsoleBooting::class => 'onConsole',
|
||||
];
|
||||
```
|
||||
|
||||
**Key components:**
|
||||
- `AuthenticateApiKey` — Validates API keys (bcrypt + legacy SHA-256)
|
||||
- `EnforceApiScope` — Scope-based permissions (`read`, `write`, wildcards)
|
||||
- `RateLimitApi` — Tier-based rate limiting with burst allowance
|
||||
- `WebhookService` — HMAC-SHA256 signed webhook delivery
|
||||
|
||||
## OpenAPI Documentation Attributes
|
||||
|
||||
```php
|
||||
use Core\Api\Documentation\Attributes\{ApiTag, ApiResponse, ApiParameter, ApiSecurity, ApiHidden};
|
||||
|
||||
#[ApiTag('Products')]
|
||||
#[ApiResponse(200, ProductResource::class)]
|
||||
#[ApiSecurity('apiKey')]
|
||||
class ProductController
|
||||
{
|
||||
#[ApiParameter('filter', 'query', 'string', 'Filter products')]
|
||||
public function index() { }
|
||||
}
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
- UK English (colour, organisation, centre)
|
||||
- PSR-12 coding style (Laravel Pint)
|
||||
- Pest for testing
|
||||
- Livewire + Flux Pro for UI
|
||||
- PSR-12 with `declare(strict_types=1);`
|
||||
- Type hints on all parameters and return types
|
||||
- Pest for testing (not PHPUnit directly)
|
||||
- Font Awesome Pro icons (not Heroicons)
|
||||
- Flux Pro components (not vanilla Alpine)
|
||||
|
||||
## 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 applies to Core\ namespace)
|
||||
Loading…
Add table
Reference in a new issue