docs: tailor CLAUDE.md to core-commerce package
Replace generic Core PHP Framework template with documentation specific to this commerce package, including service layer architecture, payment gateways, domain events, and correct directory structure. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
8f27fe85c3
commit
8b0eac7bef
1 changed files with 93 additions and 47 deletions
140
CLAUDE.md
140
CLAUDE.md
|
|
@ -1,66 +1,112 @@
|
|||
# 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`.
|
||||
## What This Is
|
||||
|
||||
**Event-driven registration:**
|
||||
```php
|
||||
class Boot
|
||||
{
|
||||
public static array $listens = [
|
||||
WebRoutesRegistering::class => 'onWebRoutes',
|
||||
ApiRoutesRegistering::class => 'onApiRoutes',
|
||||
AdminPanelBooting::class => 'onAdminPanel',
|
||||
];
|
||||
}
|
||||
```
|
||||
`host-uk/core-commerce` - A Laravel package providing orders, subscriptions, invoices, and payment processing. Namespace: `Core\Mod\Commerce`.
|
||||
|
||||
## 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 # vendor/bin/pint
|
||||
composer run test # vendor/bin/pest
|
||||
vendor/bin/pint --dirty # Format changed files only
|
||||
vendor/bin/pest --filter=CheckoutFlowTest # Run single test file
|
||||
```
|
||||
|
||||
## 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 & Event System
|
||||
|
||||
This is a **Laravel package** (not a standalone app). `Boot.php` extends `ServiceProvider` and uses the Core Framework's event-driven lazy-loading:
|
||||
|
||||
```php
|
||||
public static array $listens = [
|
||||
AdminPanelBooting::class => 'onAdminPanel',
|
||||
ApiRoutesRegistering::class => 'onApiRoutes',
|
||||
WebRoutesRegistering::class => 'onWebRoutes',
|
||||
ConsoleBooting::class => 'onConsole',
|
||||
];
|
||||
```
|
||||
|
||||
## Packages
|
||||
### Service Layer
|
||||
|
||||
| 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 |
|
||||
Business logic lives in `Services/`. All services are registered as singletons in `Boot::register()`:
|
||||
|
||||
- **CommerceService** - Order orchestration
|
||||
- **SubscriptionService** - Subscription lifecycle
|
||||
- **InvoiceService** - Invoice generation
|
||||
- **TaxService** - Jurisdiction-based tax calculation
|
||||
- **CouponService** - Discount validation and application
|
||||
- **CurrencyService** - Multi-currency support with exchange rates
|
||||
- **DunningService** - Failed payment retry logic
|
||||
- **UsageBillingService** - Metered/usage-based billing
|
||||
- **ReferralService** - Affiliate tracking and commissions
|
||||
- **PaymentMethodService** - Stored payment methods
|
||||
|
||||
### Payment Gateways
|
||||
|
||||
Pluggable via `PaymentGatewayContract`:
|
||||
- `StripeGateway` - Primary (SaaS)
|
||||
- `BTCPayGateway` - Cryptocurrency
|
||||
|
||||
### Domain Events
|
||||
|
||||
Events in `Events/` trigger listeners for loose coupling:
|
||||
- `OrderPaid` - Payment succeeded
|
||||
- `SubscriptionCreated`, `SubscriptionRenewed`, `SubscriptionUpdated`, `SubscriptionCancelled`
|
||||
|
||||
### Livewire Components
|
||||
|
||||
Located in `View/Modal/` (not `Livewire/`):
|
||||
- `View/Modal/Web/` - User-facing (checkout, invoices, subscription management)
|
||||
- `View/Modal/Admin/` - Admin panel (managers for orders, coupons, products, etc.)
|
||||
|
||||
## Key Directories
|
||||
|
||||
```
|
||||
Boot.php # ServiceProvider, event registration
|
||||
config.php # Currencies, gateways, tax rules
|
||||
Models/ # Eloquent models (Order, Subscription, Invoice, etc.)
|
||||
Services/ # Business logic layer
|
||||
View/Modal/ # Livewire components
|
||||
Routes/ # web.php, api.php, admin.php, console.php
|
||||
Migrations/ # Database schema
|
||||
Events/ # Domain events
|
||||
Listeners/ # Event subscribers
|
||||
tests/Feature/ # Pest feature tests
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
- UK English (colour, organisation, centre)
|
||||
- PSR-12 coding style (Laravel Pint)
|
||||
- Pest for testing
|
||||
- Livewire + Flux Pro for UI
|
||||
- **UK English** - colour, organisation, centre
|
||||
- **PSR-12** via Laravel Pint
|
||||
- **Pest** for testing (not PHPUnit syntax)
|
||||
- **Strict types** - `declare(strict_types=1);` in all files
|
||||
- **Livewire + Flux Pro** for UI components
|
||||
- **Font Awesome Pro** for icons (not Heroicons)
|
||||
|
||||
## License
|
||||
## Namespaces
|
||||
|
||||
- `Core\` namespace and vendor packages: EUPL-1.2 (copyleft)
|
||||
- `app/Mod/*`, `app/Website/*`: Your choice (no copyleft)
|
||||
```php
|
||||
use Core\Mod\Commerce\Models\Order;
|
||||
use Core\Mod\Commerce\Services\SubscriptionService;
|
||||
use Core\Service\Commerce\SomeUtility; // Alternative service namespace
|
||||
```
|
||||
|
||||
See LICENSE for full details.
|
||||
## Testing
|
||||
|
||||
Tests are in `tests/` with Pest:
|
||||
|
||||
```php
|
||||
test('user can checkout', function () {
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
Run a specific test:
|
||||
```bash
|
||||
vendor/bin/pest --filter="checkout"
|
||||
vendor/bin/pest tests/Feature/CheckoutFlowTest.php
|
||||
```
|
||||
Loading…
Add table
Reference in a new issue