| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 7 | 9 | 21 | 19% |
| Commands | 6 | 7 | 3 | 38% |
| Section tags | 6 | 3 | 3 | 50% |
What each file covers
Sections
7 shared · 9 only in A · 21 only in B- − CLAUDE.md
- − Common Commands
- − Development
- − Modular Package System
- − Key Design Patterns
- − Package Anatomy
- − Frontend Assets
- − Adding a New Package
- − CI Pipeline
- + Bagisto Development Guide
- + Modular Package Structure
- + Available Packages
- + Standard Package Structure
- + Development Patterns
- + Repository Pattern
- + Event-Driven Architecture
- + Proxy Pattern
- + Key Conventions
- + Package Registration
- + Creating New Packages
- + Working with Features
- + Shipping Methods
- + Payment Methods
- + Product Types
- + Themes
- + Pest (PHP)
- + Admin
- + Shop
- + Documentation References
- + Important Notes
- Project Overview
- Testing
- E2E Tests (Playwright)
- Code Style
- Translations
- Architecture
- Naming Conventions
Commands
6 shared · 7 only in A · 3 only in B- − composer install
- − php artisan bagisto:install
- − npx playwright install --with-deps chromium
- − npx playwright test --config=tests/e2e-pw/playwright.config.ts
- − npm run dev
- − composer dump-autoload && php artisan optimize:clear
- − php artisan package:make Webkul/<Name>
- + composer require bagisto/bagisto-package-generator
- + php artisan package:make Webkul/<PackageName>
- + composer dump-autoload
- php artisan serve
- php artisan optimize:clear
- npm install
- php artisan bagisto:translations:check
- npm run build
- composer.json
Section tags
6 shared · 3 only in A · 3 only in B- − deployment
- − do-not
- − agent-behaviour
- + types
- + dependencies
- + docs
- setup
- build
- test
- code-style
- architecture
- testing-strategy
Line diff
bagisto/bagisto · CLAUDE.md
@@ −1 @@
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
bagisto/bagisto · .github/copilot-instructions.md
@@ +1 @@
1# Bagisto Development Guide
2
3## Project Overview
4
5This is a **Bagisto** e-commerce platform - an open-source Laravel-based e-commerce framework. Bagisto is built with:
6- **PHP** (Server-side)
7- **Laravel** (PHP Framework)
8- **Vue.js** (Frontend components)
9- **Tailwind CSS** (Styling)
10
11## Architecture
12
13### Modular Package Structure
14
15Bagisto follows a modular, package-based architecture. All core features are organized into Laravel packages located in `packages/Webkul/`.
16
17### Available Packages
18
19- `Admin` - Administrative interface and management
20- `Attribute` - Product attributes and attribute sets
21- `BookingProduct` - Booking/rental functionality
22- `CartRule` - Cart-based promotions
23- `CatalogRule` - Catalog-based promotions
24- `Category` - Category management
25- `Checkout` - Cart and checkout process
26- `CMS` - CMS pages
27- `Core` - Core utilities and helpers
28- `Customer` - Customer management
29- `DataGrid` - Tabular data display component
30- `DataTransfer` - Import/export data
31- `DebugBar` - Debug toolbar
32- `FPC` - Full page caching
33- `GDPR` - GDPR compliance
34- `ImageCache` - Image caching/resizing
35- `Installer` - Installation wizard
36- `Inventory` - Stock management
37- `MagicAI` - AI features (Laravel AI SDK)
38- `Marketing` - SEO, URL rewrites, search terms, campaigns
39- `Notification` - Notifications
40- `Payment` - Base payment classes (CashOnDelivery, MoneyTransfer)
41- `Paypal` - PayPal integration
42- `PayU` - PayU integration
43- `Product` - Product management
44- `Razorpay` - Razorpay integration
45- `RMA` - Return merchandise authorization
46- `Rule` - Shared rule engine base
47- `Sales` - Order management
48- `Shipping` - Shipping methods
49- `Shop` - Customer storefront
50- `Sitemap` - XML sitemap generation
51- `SocialLogin` - OAuth social login
52- `SocialShare` - Social sharing
53- `Stripe` - Stripe integration
54- `Tax` - Tax calculations
55- `Theme` - Theme management
56- `User` - Admin user management
57
58### Standard Package Structure
59
60Each package follows this structure:
61
62```
63Package/src/
64├── Config/ # Configuration files (admin-menu.php, system.php)
65├── Database/
66│ ├── Migrations/ # Database migrations
67│ ├── Seeders/ # Database seeders
68│ └── Factories/ # Model factories
69├── Http/
70│ ├── Controllers/ # Admin and Shop controllers
71│ ├── Middleware/ # Route middleware
72│ └── Requests/ # Form requests/validation
73├── Models/ # Eloquent models with Proxy pattern
74├── Repositories/ # Repository pattern (Prettus L5 Repository)
75├── Resources/
76│ ├── views/ # Blade views (admin/, shop/)
77│ ├── lang/ # Localization files
78│ └── assets/ # CSS, JS assets
79├── Routes/ # admin-routes.php, shop-routes.php
80├── Providers/ # Service providers
81└── Contracts/ # Interface definitions
82```
83
84## Development Patterns
85
86### Repository Pattern
87
88Bagisto uses **Prettus L5 Repository** for data access abstraction:
89- Repository Contracts define interfaces
90- Repository Implementations contain data access logic
91- Works with Eloquent models
92
93### Event-Driven Architecture
94
95The framework triggers events throughout the application lifecycle for extensibility.
96
97### Proxy Pattern
98
99Models use proxy classes (e.g., `ProductProxy`) for extensibility.
100
101## Key Conventions
102
103### Naming Conventions
104
105- **Namespace**: `Webkul\<PackageName>`
106- **Routes**: Separate `admin-routes.php` and `shop-routes.php`
107- **Views**: Organized in `admin/` and `shop/` folders
108- **Models**: Singular name (e.g., `Product`, `Category`)
109- **Repositories**: `<ModelName>Repository` pattern
110- **Controllers**: `<ModelName>Controller` in Admin/Shop folders
111
112### Package Registration
113
1141. Add namespace to `composer.json` psr-4 autoload
1152. Run `composer dump-autoload`
1163. Register ServiceProvider in `bootstrap/providers.php`
1174. Register ModuleServiceProvider in `config/concord.php`
1185. Run `php artisan optimize:clear`
119
120### Creating New Packages
121
122Use Bagisto Package Generator:
123```bash
124composer require bagisto/bagisto-package-generator
125php artisan package:make Webkul/<PackageName>
126```
127
128Or manually create:
1291. Create `packages/Webkul/<PackageName>/src/`
1302. Create Service Provider in `src/Providers/`
1313. Update composer.json and register provider
132
133## Working with Features
134
135### Shipping Methods
136- Extend `Webkul\Shipping\Carriers\AbstractCarrier`
137- Configure in `Config/system.php`
138- Register in service provider
139
140### Payment Methods
141- Extend `Webkul\Payment\Payment\AbstractPayment`
142- Configure in `Config/system.php`
143
144### Product Types
145- Extend appropriate type class in `Product\Type/`
146- Configure in `Config/product_types.php`
147
148### Themes
149- Create in `packages/Webkul/<Theme>/`
150- Use Vite for asset bundling — run `npm install` and `npm run build` from within the respective package directory (Admin, Shop, or Installer), not from the project root
151- Follow Blade templating conventions
152
153## Code Style
154
155- Use **Pint** for PHP code style (`./vendor/bin/pint`)
156- Follow Laravel conventions
157- Use type hints where possible
158- Write meaningful variable/method names
159
160## Testing
161
162### Pest (PHP)
163```bash
164vendor/bin/pest # Run all tests
165vendor/bin/pest --testsuite="Admin Feature Test" # Run a specific test suite
166vendor/bin/pest packages/Webkul/Admin/tests/Feature # Run tests in a directory
167vendor/bin/pest --filter="test name" # Run a single test by name
168```
169Tests use **Pest 3** with package-specific TestCase classes. Each package's tests live in `packages/Webkul/<Package>/tests/`.
170
171### E2E Tests (Playwright)
172Run from within each package directory:
173```bash
174# Admin
175cd packages/Webkul/Admin && npm install && npx playwright install --with-deps chromium
176cd packages/Webkul/Admin && npx playwright test --config=tests/e2e-pw/playwright.config.ts
177
178# Shop
179cd packages/Webkul/Shop && npm install && npx playwright install --with-deps chromium
180cd packages/Webkul/Shop && npx playwright test --config=tests/e2e-pw/playwright.config.ts
181```
182Tests require a running Laravel server (`php artisan serve`) and seeded database.
183
184### Translations
185When adding new translation keys, provide translations for **all 21 locales** in the package's `Resources/lang/` directory. Verify with:
186```bash
187php artisan bagisto:translations:check
188```
189
190## Documentation References
191
192- [Architecture Overview](https://devdocs.bagisto.com/architecture/overview.html)
193- [Backend Architecture](https://devdocs.bagisto.com/architecture/backend.html)
194- [Frontend Architecture](https://devdocs.bagisto.com/architecture/frontend.html)
195- [Package Development](https://devdocs.bagisto.com/package-development/getting-started.html)
196- [Shipping Method Development](https://devdocs.bagisto.com/shipping-method-development/getting-started.html)
197- [Payment Method Development](https://devdocs.bagisto.com/payment-method-development/getting-started.html)
198- [Product Type Development](https://devdocs.bagisto.com/product-type-development/getting-started.html)
199- [Theme Development](https://devdocs.bagisto.com/theme-development/getting-started.html)
200
201## Important Notes
202
203- Never modify core packages directly - use events/listeners or create custom packages
204- Clear caches after making changes: `php artisan optimize:clear`
205- Use repository pattern for all database operations
206- Follow the modular structure when adding new features
207
@@ −1 +1 @@
1−# CLAUDE.md
1+# Bagisto Development Guide
22
3−This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4−
53 ## Project Overview
64
7−Bagisto 2.4.x - open-source Laravel 12 e-commerce platform. PHP 8.3+, Vue.js 3, Tailwind CSS 3, Vite 5.
5+This is a **Bagisto** e-commerce platform - an open-source Laravel-based e-commerce framework. Bagisto is built with:
6+- **PHP** (Server-side)
7+- **Laravel** (PHP Framework)
8+- **Vue.js** (Frontend components)
9+- **Tailwind CSS** (Styling)
810
9−## Common Commands
11+## Architecture
1012
11−### Development
12−```bash
13−composer install # Install PHP dependencies
14−php artisan bagisto:install # Full installation (migrations, seeders, assets)
15−php artisan serve # Start PHP dev server
16−php artisan optimize:clear # Clear all caches (run after config/code changes)
17−```
13+### Modular Package Structure
1814
19−### Testing
20−```bash
21−vendor/bin/pest # Run all tests
22−vendor/bin/pest --testsuite="Admin Feature Test" # Run a specific test suite
23−vendor/bin/pest packages/Webkul/Admin/tests/Feature # Run tests in a directory
24−vendor/bin/pest --filter="test name" # Run a single test by name
25−```
15+Bagisto follows a modular, package-based architecture. All core features are organized into Laravel packages located in `packages/Webkul/`.
2616
27−Test 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.
17+### Available Packages
2818
29−Tests use **Pest 3** with package-specific TestCase classes bound in `tests/Pest.php`. Each package's tests live in `packages/Webkul/<Package>/tests/`.
19+- `Admin` - Administrative interface and management
20+- `Attribute` - Product attributes and attribute sets
21+- `BookingProduct` - Booking/rental functionality
22+- `CartRule` - Cart-based promotions
23+- `CatalogRule` - Catalog-based promotions
24+- `Category` - Category management
25+- `Checkout` - Cart and checkout process
26+- `CMS` - CMS pages
27+- `Core` - Core utilities and helpers
28+- `Customer` - Customer management
29+- `DataGrid` - Tabular data display component
30+- `DataTransfer` - Import/export data
31+- `DebugBar` - Debug toolbar
32+- `FPC` - Full page caching
33+- `GDPR` - GDPR compliance
34+- `ImageCache` - Image caching/resizing
35+- `Installer` - Installation wizard
36+- `Inventory` - Stock management
37+- `MagicAI` - AI features (Laravel AI SDK)
38+- `Marketing` - SEO, URL rewrites, search terms, campaigns
39+- `Notification` - Notifications
40+- `Payment` - Base payment classes (CashOnDelivery, MoneyTransfer)
41+- `Paypal` - PayPal integration
42+- `PayU` - PayU integration
43+- `Product` - Product management
44+- `Razorpay` - Razorpay integration
45+- `RMA` - Return merchandise authorization
46+- `Rule` - Shared rule engine base
47+- `Sales` - Order management
48+- `Shipping` - Shipping methods
49+- `Shop` - Customer storefront
50+- `Sitemap` - XML sitemap generation
51+- `SocialLogin` - OAuth social login
52+- `SocialShare` - Social sharing
53+- `Stripe` - Stripe integration
54+- `Tax` - Tax calculations
55+- `Theme` - Theme management
56+- `User` - Admin user management
3057
31−### E2E Tests (Playwright)
32−E2E tests are run from within each package directory. Each package has its own Playwright config and tests:
58+### Standard Package Structure
3359
34−**Admin**:
35−```bash
36−cd packages/Webkul/Admin
37−npm install
38−npx playwright install --with-deps chromium
39−npx playwright test --config=tests/e2e-pw/playwright.config.ts
40−```
60+Each package follows this structure:
4161
42−**Shop**:
43−```bash
44−cd packages/Webkul/Shop
45−npm install
46−npx playwright install --with-deps chromium
47−npx playwright test --config=tests/e2e-pw/playwright.config.ts
4862 ```
63+Package/src/
64+├── Config/ # Configuration files (admin-menu.php, system.php)
65+├── Database/
66+│ ├── Migrations/ # Database migrations
67+│ ├── Seeders/ # Database seeders
68+│ └── Factories/ # Model factories
69+├── Http/
70+│ ├── Controllers/ # Admin and Shop controllers
71+│ ├── Middleware/ # Route middleware
72+│ └── Requests/ # Form requests/validation
73+├── Models/ # Eloquent models with Proxy pattern
74+├── Repositories/ # Repository pattern (Prettus L5 Repository)
75+├── Resources/
76+│ ├── views/ # Blade views (admin/, shop/)
77+│ ├── lang/ # Localization files
78+│ └── assets/ # CSS, JS assets
79+├── Routes/ # admin-routes.php, shop-routes.php
80+├── Providers/ # Service providers
81+└── Contracts/ # Interface definitions
82+```
4983
50−Tests require a running Laravel server (`php artisan serve`) and seeded database. Set `BASE_URL` env var if not using default.
84+## Development Patterns
5185
52−### Code Style
53−```bash
54−vendor/bin/pint # Fix PHP code style (Laravel Pint)
55−vendor/bin/pint --test # Check style without fixing
56−```
86+### Repository Pattern
5787
58−### Translations
59−When adding new translation keys, always provide translations for **all locales** in the package's `Resources/lang/` directory. Verify with:
60−```bash
61−php artisan bagisto:translations:check
62−```
88+Bagisto uses **Prettus L5 Repository** for data access abstraction:
89+- Repository Contracts define interfaces
90+- Repository Implementations contain data access logic
91+- Works with Eloquent models
6392
64−## Architecture
93+### Event-Driven Architecture
6594
66−### Modular Package System
95+The framework triggers events throughout the application lifecycle for extensibility.
6796
68−All 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.
97+### Proxy Pattern
6998
70−**Dual registration**: Each package registers in two places:
71−1. **`bootstrap/providers.php`** - Main ServiceProvider (routes, views, events, config)
72−2. **`config/concord.php`** - ModuleServiceProvider (Konekt Concord model/enum registration)
99+Models use proxy classes (e.g., `ProductProxy`) for extensibility.
73100
74−### Key Design Patterns
101+## Key Conventions
75102
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.
103+### Naming Conventions
77104
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.
105+- **Namespace**: `Webkul\<PackageName>`
106+- **Routes**: Separate `admin-routes.php` and `shop-routes.php`
107+- **Views**: Organized in `admin/` and `shop/` folders
108+- **Models**: Singular name (e.g., `Product`, `Category`)
109+- **Repositories**: `<ModelName>Repository` pattern
110+- **Controllers**: `<ModelName>Controller` in Admin/Shop folders
79111
80−**Event-Driven Extensibility**: The framework fires events at key lifecycle points. Extend behavior via listeners rather than modifying core packages.
112+### Package Registration
81113
82−### Package Anatomy
114+1. Add namespace to `composer.json` psr-4 autoload
115+2. Run `composer dump-autoload`
116+3. Register ServiceProvider in `bootstrap/providers.php`
117+4. Register ModuleServiceProvider in `config/concord.php`
118+5. Run `php artisan optimize:clear`
83119
120+### Creating New Packages
121+
122+Use Bagisto Package Generator:
123+```bash
124+composer require bagisto/bagisto-package-generator
125+php artisan package:make Webkul/<PackageName>
84126 ```
85−packages/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−```
100127
101−### Frontend Assets
128+Or manually create:
129+1. Create `packages/Webkul/<PackageName>/src/`
130+2. Create Service Provider in `src/Providers/`
131+3. Update composer.json and register provider
102132
103−Admin, 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/`
133+## Working with Features
107134
108−Vue 3 components are used within Blade templates via `@pushOnce('scripts')` / Blade component slots.
135+### Shipping Methods
136+- Extend `Webkul\Shipping\Carriers\AbstractCarrier`
137+- Configure in `Config/system.php`
138+- Register in service provider
109139
110−### Naming Conventions
140+### Payment Methods
141+- Extend `Webkul\Payment\Payment\AbstractPayment`
142+- Configure in `Config/system.php`
111143
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/`
144+### Product Types
145+- Extend appropriate type class in `Product\Type/`
146+- Configure in `Config/product_types.php`
117147
118−### Adding a New Package
148+### Themes
149+- Create in `packages/Webkul/<Theme>/`
150+- Use Vite for asset bundling — run `npm install` and `npm run build` from within the respective package directory (Admin, Shop, or Installer), not from the project root
151+- Follow Blade templating conventions
119152
120−1. Create `packages/Webkul/<Name>/src/` with the standard structure
121−2. Add PSR-4 namespace to root `composer.json` autoload
122−3. Register ServiceProvider in `bootstrap/providers.php`
123−4. Register ModuleServiceProvider in `config/concord.php`
124−5. Run `composer dump-autoload && php artisan optimize:clear`
153+## Code Style
125154
126−Or use: `php artisan package:make Webkul/<Name>` (requires `bagisto/bagisto-package-generator`)
155+- Use **Pint** for PHP code style (`./vendor/bin/pint`)
156+- Follow Laravel conventions
157+- Use type hints where possible
158+- Write meaningful variable/method names
127159
128−## CI Pipeline
160+## Testing
129161
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
162+### Pest (PHP)
163+```bash
164+vendor/bin/pest # Run all tests
165+vendor/bin/pest --testsuite="Admin Feature Test" # Run a specific test suite
166+vendor/bin/pest packages/Webkul/Admin/tests/Feature # Run tests in a directory
167+vendor/bin/pest --filter="test name" # Run a single test by name
168+```
169+Tests use **Pest 3** with package-specific TestCase classes. Each package's tests live in `packages/Webkul/<Package>/tests/`.
170+
171+### E2E Tests (Playwright)
172+Run from within each package directory:
173+```bash
174+# Admin
175+cd packages/Webkul/Admin && npm install && npx playwright install --with-deps chromium
176+cd packages/Webkul/Admin && npx playwright test --config=tests/e2e-pw/playwright.config.ts
177+
178+# Shop
179+cd packages/Webkul/Shop && npm install && npx playwright install --with-deps chromium
180+cd packages/Webkul/Shop && npx playwright test --config=tests/e2e-pw/playwright.config.ts
181+```
182+Tests require a running Laravel server (`php artisan serve`) and seeded database.
183+
184+### Translations
185+When adding new translation keys, provide translations for **all 21 locales** in the package's `Resources/lang/` directory. Verify with:
186+```bash
187+php artisan bagisto:translations:check
188+```
189+
190+## Documentation References
191+
192+- [Architecture Overview](https://devdocs.bagisto.com/architecture/overview.html)
193+- [Backend Architecture](https://devdocs.bagisto.com/architecture/backend.html)
194+- [Frontend Architecture](https://devdocs.bagisto.com/architecture/frontend.html)
195+- [Package Development](https://devdocs.bagisto.com/package-development/getting-started.html)
196+- [Shipping Method Development](https://devdocs.bagisto.com/shipping-method-development/getting-started.html)
197+- [Payment Method Development](https://devdocs.bagisto.com/payment-method-development/getting-started.html)
198+- [Product Type Development](https://devdocs.bagisto.com/product-type-development/getting-started.html)
199+- [Theme Development](https://devdocs.bagisto.com/theme-development/getting-started.html)
200+
201+## Important Notes
202+
203+- Never modify core packages directly - use events/listeners or create custom packages
204+- Clear caches after making changes: `php artisan optimize:clear`
205+- Use repository pattern for all database operations
206+- Follow the modular structure when adding new features
134207
