| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 3 | 25 | 13 | 7% |
| Commands | 4 | 5 | 7 | 25% |
| Section tags | 7 | 2 | 4 | 54% |
What each file covers
Sections
3 shared · 25 only in A · 13 only in B- − 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
- + 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)
- Code Style
- Testing
- Pest (PHP)
Commands
4 shared · 5 only in A · 7 only in B- − composer require bagisto/bagisto-package-generator
- − php artisan package:make Webkul/<PackageName>
- − php artisan optimize:clear
- − npm install
- − php artisan serve
- + 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
- php artisan bagisto:translations:check
- composer.json
- composer dump-autoload
- npm run build
Section tags
7 shared · 2 only in A · 4 only in B- − types
- − docs
- + database
- + monorepo
- + do-not
- + agent-behaviour
- setup
- build
- test
- code-style
- architecture
- testing-strategy
- dependencies
Line diff
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
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−# Bagisto Development Guide
1+# AGENTS.md — Cross-Agent Instructions for Bagisto 2.4.x
22
3−## Project Overview
3+## Do Not Edit
44
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)
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
1010
11−## Architecture
11+## Repository Map
1212
13−### Modular Package Structure
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+```
1477
15−Bagisto follows a modular, package-based architecture. All core features are organized into Laravel packages located in `packages/Webkul/`.
78+## Package Internal Structure
1679
17−### Available Packages
80+Every package in `packages/Webkul/{Name}/src/` follows:
1881
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−
6282 ```
63−Package/src/
64−├── Config/ # Configuration files (admin-menu.php, system.php)
83+├── Config/ # admin-menu.php, system.php, acl.php, carriers.php, etc.
84+├── Contracts/ # Interfaces for each model
6585 ├── Database/
66−│ ├── Migrations/ # Database migrations
67−│ ├── Seeders/ # Database seeders
68−│ └── Factories/ # Model factories
86+│ ├── Migrations/
87+│ ├── Factories/
88+│ └── Seeders/
89+├── DataGrids/ # DataGrid classes (extends Webkul\DataGrid\DataGrid)
6990 ├── 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)
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
75102 ├── 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
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
82110 ```
83111
84−## Development Patterns
112+## Key Architecture Patterns
85113
86−### Repository Pattern
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`.
87120
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
121+## Commands
92122
93−### Event-Driven Architecture
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
94129
95−The framework triggers events throughout the application lifecycle for extensibility.
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
96133
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>
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
126137 ```
127138
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)
139+### Code Style
163140 ```bash
164−vendor/bin/pest # Run all tests
165−vendor/bin/pest --testsuite="Admin Feature Test" # Run a specific test suite
166−vendor/bin/pest packages/Webkul/Admin/tests/Feature # Run tests in a directory
167−vendor/bin/pest --filter="test name" # Run a single test by name
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)
168144 ```
169−Tests use **Pest 3** with package-specific TestCase classes. Each package's tests live in `packages/Webkul/<Package>/tests/`.
170145
171−### E2E Tests (Playwright)
172−Run from within each package directory:
146+### Frontend (run from within each package: Admin, Shop, or Installer)
173147 ```bash
174−# Admin
175−cd packages/Webkul/Admin && npm install && npx playwright install --with-deps chromium
176−cd packages/Webkul/Admin && npx playwright test --config=tests/e2e-pw/playwright.config.ts
177−
178−# Shop
179−cd packages/Webkul/Shop && npm install && npx playwright install --with-deps chromium
180−cd packages/Webkul/Shop && npx playwright test --config=tests/e2e-pw/playwright.config.ts
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
181152 ```
182−Tests require a running Laravel server (`php artisan serve`) and seeded database.
183153
184−### Translations
185−When adding new translation keys, provide translations for **all 21 locales** in the package's `Resources/lang/` directory. Verify with:
154+### Database
186155 ```bash
187−php artisan bagisto:translations:check
156+php artisan migrate # Run migrations
157+php artisan db:seed # Seed database
188158 ```
189159
190−## Documentation References
160+## CI Workflows (.github/workflows/)
191161
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)
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 |
200169
201−## Important Notes
170+## Safety Rails
202171
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
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`
207187
