docs: rewrite CLAUDE.md for core-uptelligence package
Replace generic Core PHP Framework boilerplate with package-specific documentation covering the vendor tracking module's architecture, services, and commands. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
6c17c39c97
commit
256e0c38b7
1 changed files with 70 additions and 48 deletions
118
CLAUDE.md
118
CLAUDE.md
|
|
@ -1,66 +1,88 @@
|
|||
# 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',
|
||||
];
|
||||
}
|
||||
```
|
||||
`host-uk/core-uptelligence` - A Laravel module for upstream vendor tracking and dependency intelligence. Tracks software vendors (licensed, OSS, plugins), analyses version diffs with AI, generates upgrade todos, and dispatches digest notifications.
|
||||
|
||||
**Namespace:** `Core\Mod\Uptelligence\`
|
||||
|
||||
## 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 # Format with Pint
|
||||
composer run test # Run all tests with Pest
|
||||
./vendor/bin/pest --filter="test name" # Run single test
|
||||
./vendor/bin/pint --dirty # Format only changed files
|
||||
```
|
||||
|
||||
## Module 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
|
||||
**Artisan commands** (when installed in a host application):
|
||||
```bash
|
||||
php artisan upstream:check # Check vendors for updates
|
||||
php artisan upstream:analyze # Analyse version diffs
|
||||
php artisan upstream:issues # Generate issues from todos
|
||||
php artisan upstream:check-updates # Check external registries
|
||||
php artisan upstream:send-digests # Send digest emails
|
||||
```
|
||||
|
||||
## 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 |
|
||||
This is a **standalone Laravel package** (not an application). It registers as a service provider via `Boot.php`.
|
||||
|
||||
### Key Components
|
||||
|
||||
| Layer | Location | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Boot | `Boot.php` | Service provider, event listeners, rate limiters |
|
||||
| Models | `Models/` | Eloquent: Vendor, VersionRelease, UpstreamTodo, Asset, etc. |
|
||||
| Services | `Services/` | Business logic: AI analysis, diff generation, webhooks |
|
||||
| Commands | `Console/` | Artisan commands for CLI operations |
|
||||
| Admin UI | `View/Modal/Admin/` | Livewire modals for admin panel |
|
||||
| API | `Controllers/Api/` | Webhook receiver endpoints |
|
||||
|
||||
### Service Layer
|
||||
|
||||
Services are registered as singletons in `Boot.php`:
|
||||
|
||||
- `VendorStorageService` - File storage (local/S3)
|
||||
- `VendorUpdateCheckerService` - Registry polling (Packagist, npm)
|
||||
- `DiffAnalyzerService` - Version diff generation
|
||||
- `AIAnalyzerService` - Anthropic/OpenAI code analysis
|
||||
- `IssueGeneratorService` - GitHub/Gitea issue creation
|
||||
- `UptelligenceDigestService` - Email digests
|
||||
- `WebhookReceiverService` - Inbound webhook processing
|
||||
|
||||
### Event Registration
|
||||
|
||||
```php
|
||||
public static array $listens = [
|
||||
AdminPanelBooting::class => 'onAdminPanel',
|
||||
ApiRoutesRegistering::class => 'onApiRoutes',
|
||||
ConsoleBooting::class => 'onConsole',
|
||||
];
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
- UK English (colour, organisation, centre)
|
||||
- PSR-12 coding style (Laravel Pint)
|
||||
- Pest for testing
|
||||
- Livewire + Flux Pro for UI
|
||||
- **UK English** - colour, organisation, analyse (not American spellings)
|
||||
- **Strict types** - `declare(strict_types=1);` in every PHP file
|
||||
- **Full type hints** - Parameters and return types required
|
||||
- **PSR-12** - Laravel Pint for formatting
|
||||
- **Pest** - Not PHPUnit directly
|
||||
- **Livewire + Flux Pro** - Admin UI components
|
||||
|
||||
## Testing
|
||||
|
||||
Tests live in `tests/`. The package uses Orchestra Testbench for Laravel testing in isolation.
|
||||
|
||||
```bash
|
||||
composer run test # All tests
|
||||
./vendor/bin/pest tests/Unit/ # Unit tests only
|
||||
./vendor/bin/pest tests/Feature/ # Feature tests only
|
||||
./vendor/bin/pest --filter="VendorTest" # Specific test class
|
||||
```
|
||||
|
||||
## 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 for the `Core\` namespace)
|
||||
Loading…
Add table
Reference in a new issue