Copilot instructions

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/&lt;PackageName&gt;
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=&quot;Admin Feature Test&quot;        # Run a specific test suite
166vendor/bin/pest packages/Webkul/Admin/tests/Feature     # Run tests in a directory
167vendor/bin/pest --filter=&quot;test name&quot;                    # 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