| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 2 | 14 | 14 | 7% |
| Commands | 3 | 10 | 8 | 14% |
| Section tags | 8 | 1 | 3 | 67% |
What each file covers
Sections
2 shared · 14 only in A · 14 only in B- − CLAUDE.md
- − Project Overview
- − Common Commands
- − Development
- − E2E Tests (Playwright)
- − Translations
- − Architecture
- − Modular Package System
- − Key Design Patterns
- − Package Anatomy
- − Frontend Assets
- − Naming Conventions
- − Adding a New Package
- − CI Pipeline
- + AGENTS.md — Cross-Agent Instructions for Bagisto 2.4.x
- + Do Not Edit
- + Repository Map
- + Package Internal Structure
- + Key Architecture Patterns
- + Commands
- + Pest (PHP)
- + Playwright (E2E) — Admin (run from packages/Webkul/Admin)
- + Playwright (E2E) — Shop (run from packages/Webkul/Shop)
- + Frontend (run from within each package: Admin, Shop, or Installer)
- + Database
- + CI Workflows (.github/workflows/)
- + Safety Rails
- + Validation Checklist (Before Marking Complete)
- Testing
- Code Style
Commands
3 shared · 10 only in A · 8 only in B- − composer install
- − php artisan bagisto:install
- − php artisan serve
- − php artisan optimize:clear
- − npm 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>
- + php artisan test --compact
- + php artisan test --compact --filter=testName
- + php artisan test --compact packages/Webkul/Admin/tests
- + php artisan migrate
- + php artisan db:seed
- + composer.lock
- + composer update
- + composer dump-autoload
- php artisan bagisto:translations:check
- npm run build
- composer.json
Section tags
8 shared · 1 only in A · 3 only in B- − deployment
- + dependencies
- + database
- + monorepo
- setup
- build
- test
- code-style
- architecture
- testing-strategy
- do-not
- agent-behaviour
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 · AGENTS.md
@@ +1 @@
1# AGENTS.md — Cross-Agent Instructions for Bagisto 2.4.x
2
3## Do Not Edit
4
5- `vendor/`, `node_modules/`, `composer.lock`, `package-lock.json`
6- `public/themes/*/build/` — Vite build output
7- `storage/` — runtime caches, logs, compiled views
8- `*.hot` files — Vite HMR markers
9- `packages/Webkul/*/src/Resources/assets/` — only edit if working on frontend; always run `npm run build` from the respective package directory after
10
11## Repository Map
12
13```
14├── app/ # Thin Laravel app shell (middleware, providers)
15├── bootstrap/
16│ ├── app.php # Middleware, exceptions, routing
17│ └── providers.php # All service provider registrations
18├── config/
19│ ├── concord.php # Concord module (model proxy) registrations
20│ ├── themes.php # Shop + Admin theme config (Vite paths)
21│ ├── elasticsearch.php # Elasticsearch connection
22│ └── ... # Standard Laravel configs
23├── database/
24│ ├── migrations/ # App-level migrations
25│ └── seeders/
26├── packages/Webkul/ # ★ All Bagisto packages live here (40 packages)
27│ ├── Admin/ # Admin panel (controllers, views, DataGrids, reporting, e2e-pw tests)
28│ ├── Shop/ # Customer storefront (controllers, views, e2e-pw tests)
29│ ├── Core/ # Helpers, models, jobs, listeners, exchange rates
30│ ├── Product/ # Product models, types, indexers, repositories
31│ ├── Sales/ # Orders, invoices, shipments, refunds
32│ ├── Checkout/ # Cart, checkout flow
33│ ├── Customer/ # Customer models, auth
34│ ├── Category/ # Category tree (nested set)
35│ ├── Attribute/ # EAV attribute system
36│ ├── Payment/ # Base payment classes (CashOnDelivery, MoneyTransfer)
37│ ├── Paypal/ # PayPal integration
38│ ├── Stripe/ # Stripe integration
39│ ├── Razorpay/ # Razorpay integration
40│ ├── PayU/ # PayU integration
41│ ├── Shipping/ # Base shipping carriers
42│ ├── Inventory/ # Stock management
43│ ├── CartRule/ # Cart promotion rules
44│ ├── CatalogRule/ # Catalog price rules
45│ ├── Tax/ # Tax calculation
46│ ├── DataGrid/ # Admin data table component
47│ ├── DataTransfer/ # Import/export
48│ ├── CMS/ # CMS pages
49│ ├── Marketing/ # SEO, URL rewrites, search terms, campaigns
50│ ├── Theme/ # Theme management
51│ ├── MagicAI/ # AI features (Laravel AI SDK)
52│ ├── Notification/ # Notifications
53│ ├── BookingProduct/ # Booking product type
54│ ├── Rule/ # Shared rule engine base
55│ ├── User/ # Admin user management
56│ ├── Installer/ # Installation wizard
57│ ├── SocialLogin/ # OAuth social login
58│ ├── SocialShare/ # Social sharing
59│ ├── Sitemap/ # XML sitemap generation
60│ ├── GDPR/ # GDPR compliance
61│ ├── RMA/ # Return merchandise authorization
62│ ├── FPC/ # Full page cache
63│ ├── ImageCache/ # Image caching/resizing
64│ ├── DebugBar/ # Debug toolbar
65│ ├── BreezeFront/ # Breeze frontend theme
66│ └── NewTheme/ # New theme scaffold
67├── routes/
68│ ├── web.php # Minimal — packages define their own routes
69│ └── console.php
70├── tests/
71│ └── Pest.php # Pest configuration binding test cases to packages
72├── phpunit.xml # Test suites per package
73├── pint.json # Pint config (preset: laravel)
74├── vite.config.js # Root Vite config
75└── docker-compose.yml # Sail: MySQL 8, Redis, Elasticsearch 7.17, Kibana, Mailpit
76```
77
78## Package Internal Structure
79
80Every package in `packages/Webkul/{Name}/src/` follows:
81
82```
83├── Config/ # admin-menu.php, system.php, acl.php, carriers.php, etc.
84├── Contracts/ # Interfaces for each model
85├── Database/
86│ ├── Migrations/
87│ ├── Factories/
88│ └── Seeders/
89├── DataGrids/ # DataGrid classes (extends Webkul\DataGrid\DataGrid)
90├── Http/
91│ ├── Controllers/
92│ ├── Middleware/
93│ └── Requests/ # Form Request validation classes
94├── Jobs/
95├── Listeners/
96├── Models/ # Eloquent models + Proxy classes
97├── Observers/
98├── Providers/
99│ ├── {Name}ServiceProvider.php
100│ └── ModuleServiceProvider.php # Concord model registration
101├── Repositories/ # Prettus L5 repositories
102├── Resources/
103│ ├── assets/ # JS, CSS, images (Vite-compiled)
104│ ├── lang/{locale}/ # 21 locales
105│ └── views/
106├── Routes/
107│ ├── admin-routes.php
108│ └── shop-routes.php
109└── Type/ # (Product package) Product type classes
110```
111
112## Key Architecture Patterns
113
114- **Concord Module System**: Models registered in each package's `ModuleServiceProvider`, wired via `config/concord.php`. Every data entity has a Contract (interface), Model, and Proxy (three-component system).
115- **Repository Pattern**: All DB access through repositories extending `Webkul\Core\Eloquent\Repository` (Prettus L5). Repository `model()` returns the Contract class, not the Model.
116- **Path Repositories**: `composer.json` uses `"type": "path"` for `packages/*/*`, packages are symlinked — no `composer update` needed for package code changes. Run `composer dump-autoload` after adding new packages.
117- **Service Providers**: Each package has a main ServiceProvider (routes, views, translations, migrations, config) registered in `bootstrap/providers.php`.
118- **Dual Route Files**: Admin routes (`['web', 'admin']` middleware, `config('app.admin_url')` prefix) and Shop routes (`['web', 'locale', 'theme', 'currency']` middleware).
119- **21 Locales**: ar, bn, ca, de, en, es, fa, fr, he, hi_IN, id, it, ja, nl, pl, pt_BR, ru, sin, tr, uk, zh_CN. Translation changes must be applied to ALL locale files. Verify with `php artisan bagisto:translations:check`.
120
121## Commands
122
123### Testing
124```bash
125# Pest (PHP)
126php artisan test --compact # Run all tests
127php artisan test --compact --filter=testName # Run specific test
128php artisan test --compact packages/Webkul/Admin/tests # Run package tests
129
130# Playwright (E2E) — Admin (run from packages/Webkul/Admin)
131cd packages/Webkul/Admin && npm install && npx playwright install --with-deps chromium
132cd packages/Webkul/Admin && npx playwright test --config=tests/e2e-pw/playwright.config.ts
133
134# Playwright (E2E) — Shop (run from packages/Webkul/Shop)
135cd packages/Webkul/Shop && npm install && npx playwright install --with-deps chromium
136cd packages/Webkul/Shop && npx playwright test --config=tests/e2e-pw/playwright.config.ts
137```
138
139### Code Style
140```bash
141vendor/bin/pint --dirty # Fix changed files only
142vendor/bin/pint # Fix all files
143vendor/bin/pint --test # Check only (CI uses this)
144```
145
146### Frontend (run from within each package: Admin, Shop, or Installer)
147```bash
148cd packages/Webkul/Admin && npm install && npm run build # Admin production build
149cd packages/Webkul/Shop && npm install && npm run build # Shop production build
150cd packages/Webkul/Admin && npm run dev # Admin dev server with HMR
151cd packages/Webkul/Shop && npm run dev # Shop dev server with HMR
152```
153
154### Database
155```bash
156php artisan migrate # Run migrations
157php artisan db:seed # Seed database
158```
159
160## CI Workflows (.github/workflows/)
161
162| Workflow | Trigger | What it does |
163|----------|---------|--------------|
164| `pest_tests.yml` | push, PR | Installs Bagisto, runs `vendor/bin/pest` |
165| `pint_tests.yml` | push, PR | Runs `pint --test` (style check) |
166| `admin_playwright_tests.yml` | push, PR | Admin E2E tests |
167| `shop_playwright_tests.yml` | push, PR | Shop E2E tests |
168| `translation_tests.yml` | push, PR | Translation key consistency |
169
170## Safety Rails
171
172- **Never modify `bootstrap/providers.php` or `config/concord.php`** without understanding the full provider chain — removing a provider breaks the entire module.
173- **Translations are 21 files per key.** Missing a locale will fail CI. When adding/removing translation keys, hit all 21 files.
174- **Pint must pass.** Run `vendor/bin/pint --dirty` before finalizing any PHP change.
175- **Tests must pass.** Run affected package tests after changes. Do not delete tests without approval.
176- **Do not add/remove composer dependencies without approval.**
177- **Do not create documentation files unless explicitly requested.**
178
179## Validation Checklist (Before Marking Complete)
180
1811. `vendor/bin/pint --dirty` — no style violations
1822. `php artisan test --compact` — affected tests pass
1833. `php artisan bagisto:translations:check` — translation keys exist in all 21 locale files (if changed)
1844. No `env()` calls outside `config/` files
1855. New models have Contract + Model + Proxy + Repository
1866. New packages registered in `bootstrap/providers.php` and `config/concord.php`
187
@@ −1 +1 @@
1−# CLAUDE.md
1+# AGENTS.md — Cross-Agent Instructions for Bagisto 2.4.x
22
3−This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
3+## Do Not Edit
44
5−## Project Overview
5+- `vendor/`, `node_modules/`, `composer.lock`, `package-lock.json`
6+- `public/themes/*/build/` — Vite build output
7+- `storage/` — runtime caches, logs, compiled views
8+- `*.hot` files — Vite HMR markers
9+- `packages/Webkul/*/src/Resources/assets/` — only edit if working on frontend; always run `npm run build` from the respective package directory after
610
7−Bagisto 2.4.x - open-source Laravel 12 e-commerce platform. PHP 8.3+, Vue.js 3, Tailwind CSS 3, Vite 5.
11+## Repository Map
812
9−## Common Commands
10−
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)
1713 ```
14+├── app/ # Thin Laravel app shell (middleware, providers)
15+├── bootstrap/
16+│ ├── app.php # Middleware, exceptions, routing
17+│ └── providers.php # All service provider registrations
18+├── config/
19+│ ├── concord.php # Concord module (model proxy) registrations
20+│ ├── themes.php # Shop + Admin theme config (Vite paths)
21+│ ├── elasticsearch.php # Elasticsearch connection
22+│ └── ... # Standard Laravel configs
23+├── database/
24+│ ├── migrations/ # App-level migrations
25+│ └── seeders/
26+├── packages/Webkul/ # ★ All Bagisto packages live here (40 packages)
27+│ ├── Admin/ # Admin panel (controllers, views, DataGrids, reporting, e2e-pw tests)
28+│ ├── Shop/ # Customer storefront (controllers, views, e2e-pw tests)
29+│ ├── Core/ # Helpers, models, jobs, listeners, exchange rates
30+│ ├── Product/ # Product models, types, indexers, repositories
31+│ ├── Sales/ # Orders, invoices, shipments, refunds
32+│ ├── Checkout/ # Cart, checkout flow
33+│ ├── Customer/ # Customer models, auth
34+│ ├── Category/ # Category tree (nested set)
35+│ ├── Attribute/ # EAV attribute system
36+│ ├── Payment/ # Base payment classes (CashOnDelivery, MoneyTransfer)
37+│ ├── Paypal/ # PayPal integration
38+│ ├── Stripe/ # Stripe integration
39+│ ├── Razorpay/ # Razorpay integration
40+│ ├── PayU/ # PayU integration
41+│ ├── Shipping/ # Base shipping carriers
42+│ ├── Inventory/ # Stock management
43+│ ├── CartRule/ # Cart promotion rules
44+│ ├── CatalogRule/ # Catalog price rules
45+│ ├── Tax/ # Tax calculation
46+│ ├── DataGrid/ # Admin data table component
47+│ ├── DataTransfer/ # Import/export
48+│ ├── CMS/ # CMS pages
49+│ ├── Marketing/ # SEO, URL rewrites, search terms, campaigns
50+│ ├── Theme/ # Theme management
51+│ ├── MagicAI/ # AI features (Laravel AI SDK)
52+│ ├── Notification/ # Notifications
53+│ ├── BookingProduct/ # Booking product type
54+│ ├── Rule/ # Shared rule engine base
55+│ ├── User/ # Admin user management
56+│ ├── Installer/ # Installation wizard
57+│ ├── SocialLogin/ # OAuth social login
58+│ ├── SocialShare/ # Social sharing
59+│ ├── Sitemap/ # XML sitemap generation
60+│ ├── GDPR/ # GDPR compliance
61+│ ├── RMA/ # Return merchandise authorization
62+│ ├── FPC/ # Full page cache
63+│ ├── ImageCache/ # Image caching/resizing
64+│ ├── DebugBar/ # Debug toolbar
65+│ ├── BreezeFront/ # Breeze frontend theme
66+│ └── NewTheme/ # New theme scaffold
67+├── routes/
68+│ ├── web.php # Minimal — packages define their own routes
69+│ └── console.php
70+├── tests/
71+│ └── Pest.php # Pest configuration binding test cases to packages
72+├── phpunit.xml # Test suites per package
73+├── pint.json # Pint config (preset: laravel)
74+├── vite.config.js # Root Vite config
75+└── docker-compose.yml # Sail: MySQL 8, Redis, Elasticsearch 7.17, Kibana, Mailpit
76+```
1877
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
78+## Package Internal Structure
79+
80+Every package in `packages/Webkul/{Name}/src/` follows:
81+
2582 ```
83+├── Config/ # admin-menu.php, system.php, acl.php, carriers.php, etc.
84+├── Contracts/ # Interfaces for each model
85+├── Database/
86+│ ├── Migrations/
87+│ ├── Factories/
88+│ └── Seeders/
89+├── DataGrids/ # DataGrid classes (extends Webkul\DataGrid\DataGrid)
90+├── Http/
91+│ ├── Controllers/
92+│ ├── Middleware/
93+│ └── Requests/ # Form Request validation classes
94+├── Jobs/
95+├── Listeners/
96+├── Models/ # Eloquent models + Proxy classes
97+├── Observers/
98+├── Providers/
99+│ ├── {Name}ServiceProvider.php
100+│ └── ModuleServiceProvider.php # Concord model registration
101+├── Repositories/ # Prettus L5 repositories
102+├── Resources/
103+│ ├── assets/ # JS, CSS, images (Vite-compiled)
104+│ ├── lang/{locale}/ # 21 locales
105+│ └── views/
106+├── Routes/
107+│ ├── admin-routes.php
108+│ └── shop-routes.php
109+└── Type/ # (Product package) Product type classes
110+```
26111
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.
112+## Key Architecture Patterns
28113
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/`.
114+- **Concord Module System**: Models registered in each package's `ModuleServiceProvider`, wired via `config/concord.php`. Every data entity has a Contract (interface), Model, and Proxy (three-component system).
115+- **Repository Pattern**: All DB access through repositories extending `Webkul\Core\Eloquent\Repository` (Prettus L5). Repository `model()` returns the Contract class, not the Model.
116+- **Path Repositories**: `composer.json` uses `"type": "path"` for `packages/*/*`, packages are symlinked — no `composer update` needed for package code changes. Run `composer dump-autoload` after adding new packages.
117+- **Service Providers**: Each package has a main ServiceProvider (routes, views, translations, migrations, config) registered in `bootstrap/providers.php`.
118+- **Dual Route Files**: Admin routes (`['web', 'admin']` middleware, `config('app.admin_url')` prefix) and Shop routes (`['web', 'locale', 'theme', 'currency']` middleware).
119+- **21 Locales**: ar, bn, ca, de, en, es, fa, fr, he, hi_IN, id, it, ja, nl, pl, pt_BR, ru, sin, tr, uk, zh_CN. Translation changes must be applied to ALL locale files. Verify with `php artisan bagisto:translations:check`.
30120
31−### E2E Tests (Playwright)
32−E2E tests are run from within each package directory. Each package has its own Playwright config and tests:
121+## Commands
33122
34−**Admin**:
123+### Testing
35124 ```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−```
125+# Pest (PHP)
126+php artisan test --compact # Run all tests
127+php artisan test --compact --filter=testName # Run specific test
128+php artisan test --compact packages/Webkul/Admin/tests # Run package tests
41129
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
130+# Playwright (E2E) — Admin (run from packages/Webkul/Admin)
131+cd packages/Webkul/Admin && npm install && npx playwright install --with-deps chromium
132+cd packages/Webkul/Admin && npx playwright test --config=tests/e2e-pw/playwright.config.ts
133+
134+# Playwright (E2E) — Shop (run from packages/Webkul/Shop)
135+cd packages/Webkul/Shop && npm install && npx playwright install --with-deps chromium
136+cd packages/Webkul/Shop && npx playwright test --config=tests/e2e-pw/playwright.config.ts
48137 ```
49138
50−Tests require a running Laravel server (`php artisan serve`) and seeded database. Set `BASE_URL` env var if not using default.
51−
52139 ### Code Style
53140 ```bash
54−vendor/bin/pint # Fix PHP code style (Laravel Pint)
55−vendor/bin/pint --test # Check style without fixing
141+vendor/bin/pint --dirty # Fix changed files only
142+vendor/bin/pint # Fix all files
143+vendor/bin/pint --test # Check only (CI uses this)
56144 ```
57145
58−### Translations
59−When adding new translation keys, always provide translations for **all locales** in the package's `Resources/lang/` directory. Verify with:
146+### Frontend (run from within each package: Admin, Shop, or Installer)
60147 ```bash
61−php artisan bagisto:translations:check
148+cd packages/Webkul/Admin && npm install && npm run build # Admin production build
149+cd packages/Webkul/Shop && npm install && npm run build # Shop production build
150+cd packages/Webkul/Admin && npm run dev # Admin dev server with HMR
151+cd packages/Webkul/Shop && npm run dev # Shop dev server with HMR
62152 ```
63153
64−## Architecture
65−
66−### Modular Package System
67−
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.
69−
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)
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−
154+### Database
155+```bash
156+php artisan migrate # Run migrations
157+php artisan db:seed # Seed database
84158 ```
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−```
100159
101−### Frontend Assets
160+## CI Workflows (.github/workflows/)
102161
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/`
162+| Workflow | Trigger | What it does |
163+|----------|---------|--------------|
164+| `pest_tests.yml` | push, PR | Installs Bagisto, runs `vendor/bin/pest` |
165+| `pint_tests.yml` | push, PR | Runs `pint --test` (style check) |
166+| `admin_playwright_tests.yml` | push, PR | Admin E2E tests |
167+| `shop_playwright_tests.yml` | push, PR | Shop E2E tests |
168+| `translation_tests.yml` | push, PR | Translation key consistency |
107169
108−Vue 3 components are used within Blade templates via `@pushOnce('scripts')` / Blade component slots.
170+## Safety Rails
109171
110−### Naming Conventions
172+- **Never modify `bootstrap/providers.php` or `config/concord.php`** without understanding the full provider chain — removing a provider breaks the entire module.
173+- **Translations are 21 files per key.** Missing a locale will fail CI. When adding/removing translation keys, hit all 21 files.
174+- **Pint must pass.** Run `vendor/bin/pint --dirty` before finalizing any PHP change.
175+- **Tests must pass.** Run affected package tests after changes. Do not delete tests without approval.
176+- **Do not add/remove composer dependencies without approval.**
177+- **Do not create documentation files unless explicitly requested.**
111178
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/`
179+## Validation Checklist (Before Marking Complete)
117180
118−### Adding a New Package
119−
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`
125−
126−Or 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
181+1. `vendor/bin/pint --dirty` — no style violations
182+2. `php artisan test --compact` — affected tests pass
183+3. `php artisan bagisto:translations:check` — translation keys exist in all 21 locale files (if changed)
184+4. No `env()` calls outside `config/` files
185+5. New models have Contract + Model + Proxy + Repository
186+6. New packages registered in `bootstrap/providers.php` and `config/concord.php`
134187
