CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7Bagisto 2.4.x - open-source Laravel 12 e-commerce platform. PHP 8.3+, Vue.js 3, Tailwind CSS 3, Vite 5.
8 
9## Common Commands
10 
11### Development
12```bash
13composer install                # Install PHP dependencies
14php artisan bagisto:install     # Full installation (migrations, seeders, assets)
15php artisan serve               # Start PHP dev server
16php artisan optimize:clear      # Clear all caches (run after config/code changes)
17```
18 
19### Testing
20```bash
21vendor/bin/pest                                         # Run all tests
22vendor/bin/pest --testsuite="Admin Feature Test"        # Run a specific test suite
23vendor/bin/pest packages/Webkul/Admin/tests/Feature     # Run tests in a directory
24vendor/bin/pest --filter="test name"                    # Run a single test by name
25```
26 
27Test suites defined in `phpunit.xml`: Admin Feature, Core Unit, Customer Unit, DataGrid Unit, Installer Feature, PayU Unit/Feature, Razorpay Unit/Feature, Shop Feature, Stripe Unit/Feature.
28 
29Tests use **Pest 3** with package-specific TestCase classes bound in `tests/Pest.php`. Each package's tests live in `packages/Webkul/<Package>/tests/`.
30 
31### E2E Tests (Playwright)
32E2E tests are run from within each package directory. Each package has its own Playwright config and tests:
33 
34**Admin**:
35```bash
36cd packages/Webkul/Admin
37npm install
38npx playwright install --with-deps chromium
39npx playwright test --config=tests/e2e-pw/playwright.config.ts
40```
41 
42**Shop**:
43```bash
44cd packages/Webkul/Shop
45npm install
46npx playwright install --with-deps chromium
47npx playwright test --config=tests/e2e-pw/playwright.config.ts
48```
49 
50Tests require a running Laravel server (`php artisan serve`) and seeded database. Set `BASE_URL` env var if not using default.
51 
52### Code Style
53```bash
54vendor/bin/pint             # Fix PHP code style (Laravel Pint)
55vendor/bin/pint --test      # Check style without fixing
56```
57 
58### Translations
59When adding new translation keys, always provide translations for **all locales** in the package's `Resources/lang/` directory. Verify with:
60```bash
61php artisan bagisto:translations:check
62```
63 
64## Architecture
65 
66### Modular Package System
67 
68All core functionality lives in **`packages/Webkul/`** (~42 packages). Each package is a self-contained Laravel package with its own models, controllers, routes, views, migrations, and service providers.
69 
70**Dual registration**: Each package registers in two places:
711. **`bootstrap/providers.php`** - Main ServiceProvider (routes, views, events, config)
722. **`config/concord.php`** - ModuleServiceProvider (Konekt Concord model/enum registration)
73 
74### Key Design Patterns
75 
76**Repository Pattern**: All database access goes through repositories (`Prettus L5 Repository`). Interfaces in `Contracts/`, implementations in `Repositories/`. Never use models directly for queries in controllers.
77 
78**Proxy Pattern**: Models have Proxy classes (e.g., `ProductProxy`, `CategoryProxy`) enabling model substitution without modifying core code. Always reference proxies when type-hinting across packages.
79 
80**Event-Driven Extensibility**: The framework fires events at key lifecycle points. Extend behavior via listeners rather than modifying core packages.
81 
82### Package Anatomy
83 
84```
85packages/Webkul/<Package>/src/
86├── Config/           # system.php (admin settings), admin-menu.php, acl.php
87├── Database/         # Migrations/, Seeders/, Factories/
88├── Http/Controllers/ # Separate Admin/ and Shop/ controller directories
89├── Models/           # Eloquent models + Proxy classes
90├── Repositories/     # Data access layer
91├── Contracts/        # Interfaces for models and repositories
92├── Resources/
93│   ├── views/        # Blade templates (admin/, shop/)
94│   ├── lang/         # Localization (translatable strings)
95│   └── assets/       # CSS/JS source files
96├── Routes/           # admin-routes.php, shop-routes.php, api.php
97├── Providers/        # ServiceProvider + ModuleServiceProvider
98└── Listeners/        # Event listeners
99```
100 
101### Frontend Assets
102 
103Admin, Shop, and Installer each have independent Vite builds. Run `npm install` and `npm run dev`/`npm run build` from within the respective package directory:
104- **Admin**: `packages/Webkul/Admin/` builds to `public/themes/admin/default/build/`
105- **Shop**: `packages/Webkul/Shop/` builds to `public/themes/shop/default/build/`
106- **Installer**: `packages/Webkul/Installer/`
107 
108Vue 3 components are used within Blade templates via `@pushOnce('scripts')` / Blade component slots.
109 
110### Naming Conventions
111 
112- **Namespace**: `Webkul\<PackageName>` (e.g., `Webkul\Product`)
113- **Routes**: Separate `admin-routes.php` and `shop-routes.php` per package
114- **Models**: Singular (`Product`, `Category`)
115- **Repositories**: `<Model>Repository` (e.g., `ProductRepository`)
116- **Controllers**: `<Model>Controller` in `Http/Controllers/Admin/` or `Shop/`
117 
118### Adding a New Package
119 
1201. Create `packages/Webkul/<Name>/src/` with the standard structure
1212. Add PSR-4 namespace to root `composer.json` autoload
1223. Register ServiceProvider in `bootstrap/providers.php`
1234. Register ModuleServiceProvider in `config/concord.php`
1245. Run `composer dump-autoload && php artisan optimize:clear`
125 
126Or use: `php artisan package:make Webkul/<Name>` (requires `bagisto/bagisto-package-generator`)
127 
128## CI Pipeline
129 
130- **pest_tests.yml**: Pest tests on PHP 8.3 + MySQL 8.0
131- **pint_tests.yml**: Code style checks with Laravel Pint
132- **admin_playwright_tests.yml / shop_playwright_tests.yml**: E2E tests (6 parallel shards)
133- **translation_tests.yml**: Translation file validation
134