| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 3 | 13 | 25 | 7% |
| Commands | 4 | 7 | 5 | 25% |
| Section tags | 7 | 4 | 2 | 54% |
What each file covers
Sections
3 shared · 13 only in A · 25 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
- − 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)
- + Bagisto Development Guide
- + Project Overview
- + Architecture
- + Modular Package Structure
- + Available Packages
- + Standard Package Structure
- + Development Patterns
- + Repository Pattern
- + Event-Driven Architecture
- + Proxy Pattern
- + Key Conventions
- + Naming Conventions
- + Package Registration
- + Creating New Packages
- + Working with Features
- + Shipping Methods
- + Payment Methods
- + Product Types
- + Themes
- + E2E Tests (Playwright)
- + Admin
- + Shop
- + Translations
- + Documentation References
- + Important Notes
- Testing
- Pest (PHP)
- Code Style
Commands
4 shared · 7 only in A · 5 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 require bagisto/bagisto-package-generator
- + php artisan package:make Webkul/<PackageName>
- + php artisan optimize:clear
- + npm install
- + php artisan serve
- npm run build
- composer.json
- composer dump-autoload
- php artisan bagisto:translations:check
Section tags
7 shared · 4 only in A · 2 only in B- − database
- − monorepo
- − do-not
- − agent-behaviour
- + types
- + docs
- setup
- build
- test
- code-style
- architecture
- testing-strategy
- dependencies
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 · .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−# AGENTS.md — Cross-Agent Instructions for Bagisto 2.4.x
1+# Bagisto Development Guide
22
3−## Do Not Edit
3+## Project Overview
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+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)
1010
11−## Repository Map
11+## Architecture
1212
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−```
13+### Modular Package Structure
7714
78−## Package Internal Structure
15+Bagisto follows a modular, package-based architecture. All core features are organized into Laravel packages located in `packages/Webkul/`.
7916
80−Every package in `packages/Webkul/{Name}/src/` follows:
17+### Available Packages
8118
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+
60+Each package follows this structure:
61+
8262 ```
83−├── Config/ # admin-menu.php, system.php, acl.php, carriers.php, etc.
84−├── Contracts/ # Interfaces for each model
63+Package/src/
64+├── Config/ # Configuration files (admin-menu.php, system.php)
8565 ├── Database/
86−│ ├── Migrations/
87−│ ├── Factories/
88−│ └── Seeders/
89−├── DataGrids/ # DataGrid classes (extends Webkul\DataGrid\DataGrid)
66+│ ├── Migrations/ # Database migrations
67+│ ├── Seeders/ # Database seeders
68+│ └── Factories/ # Model factories
9069 ├── 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
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)
10275 ├── 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
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
11082 ```
11183
112−## Key Architecture Patterns
84+## Development Patterns
11385
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`.
86+### Repository Pattern
12087
121−## Commands
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
12292
123−### Testing
124−```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
93+### Event-Driven Architecture
12994
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
95+The framework triggers events throughout the application lifecycle for extensibility.
13396
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
97+### Proxy Pattern
98+
99+Models 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+
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`
119+
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>
137126 ```
138127
139−### Code Style
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
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)
140163 ```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)
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
144168 ```
169+Tests use **Pest 3** with package-specific TestCase classes. Each package's tests live in `packages/Webkul/<Package>/tests/`.
145170
146−### Frontend (run from within each package: Admin, Shop, or Installer)
171+### E2E Tests (Playwright)
172+Run from within each package directory:
147173 ```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
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
152181 ```
182+Tests require a running Laravel server (`php artisan serve`) and seeded database.
153183
154−### Database
184+### Translations
185+When adding new translation keys, provide translations for **all 21 locales** in the package's `Resources/lang/` directory. Verify with:
155186 ```bash
156−php artisan migrate # Run migrations
157−php artisan db:seed # Seed database
187+php artisan bagisto:translations:check
158188 ```
159189
160−## CI Workflows (.github/workflows/)
190+## Documentation References
161191
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 |
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)
169200
170−## Safety Rails
201+## Important Notes
171202
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−
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`
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
187207
