AGENTS.md

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