1da124a92a
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>
91 lines
No EOL
3.3 KiB
Markdown
91 lines
No EOL
3.3 KiB
Markdown
# 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-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
|
|
./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
|
|
```
|
|
|
|
## Package Structure
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
## Architecture
|
|
|
|
**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 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
|
|
|
|
EUPL-1.2 (copyleft applies to Core\ namespace) |