| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 2 | 14 | 14 | 7% |
| Commands | 3 | 8 | 10 | 14% |
| Section tags | 8 | 3 | 1 | 67% |
What each file covers
Sections
2 shared · 14 only in A · 14 only in B- − 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)
- + 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
- Testing
- Code Style
Commands
3 shared · 8 only in A · 10 only in B- − 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
- + 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>
- npm run build
- composer.json
- php artisan bagisto:translations:check
Section tags
8 shared · 3 only in A · 1 only in B- − dependencies
- − database
- − monorepo
- + deployment
- setup
- build
- test
- code-style
- architecture
- testing-strategy
- do-not
- agent-behaviour
Line diff
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
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
@@ −1 +1 @@
1−# AGENTS.md — Cross-Agent Instructions for Bagisto 2.4.x
1+# CLAUDE.md
22
3−## Do Not Edit
3+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
44
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
5+## Project Overview
106
11−## Repository Map
7+Bagisto 2.4.x - open-source Laravel 12 e-commerce platform. PHP 8.3+, Vue.js 3, Tailwind CSS 3, Vite 5.
128
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)
1317 ```
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−```
7718
78−## Package Internal Structure
79−
80−Every package in `packages/Webkul/{Name}/src/` follows:
81−
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
8225 ```
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−```
11126
112−## Key Architecture Patterns
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.
11328
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`.
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/`.
12030
121−## Commands
31+### E2E Tests (Playwright)
32+E2E tests are run from within each package directory. Each package has its own Playwright config and tests:
12233
123−### Testing
34+**Admin**:
12435 ```bash
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
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+```
12941
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
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
13748 ```
13849
50+Tests require a running Laravel server (`php artisan serve`) and seeded database. Set `BASE_URL` env var if not using default.
51+
13952 ### Code Style
14053 ```bash
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)
54+vendor/bin/pint # Fix PHP code style (Laravel Pint)
55+vendor/bin/pint --test # Check style without fixing
14456 ```
14557
146−### Frontend (run from within each package: Admin, Shop, or Installer)
58+### Translations
59+When adding new translation keys, always provide translations for **all locales** in the package's `Resources/lang/` directory. Verify with:
14760 ```bash
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
61+php artisan bagisto:translations:check
15262 ```
15363
154−### Database
155−```bash
156−php artisan migrate # Run migrations
157−php artisan db:seed # Seed database
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+
15884 ```
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+```
159100
160−## CI Workflows (.github/workflows/)
101+### Frontend Assets
161102
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 |
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/`
169107
170−## Safety Rails
108+Vue 3 components are used within Blade templates via `@pushOnce('scripts')` / Blade component slots.
171109
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.**
110+### Naming Conventions
178111
179−## Validation Checklist (Before Marking Complete)
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/`
180117
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`
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
187134
