# FruitBank Plugin – Claude Skill Reference

> **Purpose:** This file is a reference document for Claude to quickly understand the FruitBank NopCommerce plugin codebase, patterns, and conventions so that new work sessions can ramp up without re-reading the entire codebase from scratch.

---

## 1. Project Identity

| Property | Value |
|---|---|
| Plugin system name | `Misc.FruitBankPlugin` |
| DLL | `Nop.Plugin.Misc.FruitBankPlugin.dll` |
| Namespace root | `Nop.Plugin.Misc.FruitBankPlugin` |
| NopCommerce version | **4.80** |
| Author | Adam Gelencser |
| Plugin source path | `D:\REPOS\MANGO\source\Nopcommerce.Common\4.70\Plugins\Nop.Plugin.Misc.AIPlugin` |
| Theme path | `D:\REPOS\MANGO\source\FruitBank\Presentation\Nop.Web\Themes\CarHaven` |

The plugin is called **AIPlugin** on disk (folder/csproj) but the assembly and namespace use `FruitBankPlugin`. Both names are the same thing.

---

## 2. Business Domain

FruitBank is a **Hungarian fruit and vegetable wholesale company** running a private B2B NopCommerce webshop. The typical user is a warehouse employee or admin working on mobile. Key business concepts:

- **Partners** – business customers (companies), matched by name across multiple systems
- **Shipping documents** – PDF/image documents received from suppliers, parsed by AI
- **Measurable products** – products that require physical weighing before price is finalized; `IsMeasurable` is determined server-side only
- **Stock taking** – periodic inventory audit workflow with discrepancy reports
- **InnVoice** – external accounting/invoicing system, synced via `InnVoiceOrderService` / `InnVoiceApiService`
- **Voice ordering** – warehouse staff dictate orders in Hungarian; transcribed via Whisper

---

## 3. Folder Structure

```
Nop.Plugin.Misc.AIPlugin/
├── Areas/Admin/
│   ├── Controllers/          # All admin-area controllers
│   ├── Components/           # Admin view components
│   ├── Factories/            # CustomOrderModelFactory, CustomProductModelFactory
│   ├── Models/               # Admin view models (extended Nop models)
│   ├── Validators/
│   └── Views/                # Admin Razor views; custom layouts: _FruitBankAdminLayout.cshtml
├── Controllers/              # Public-facing controllers (QuickOrder, Checkout, FruitBankData)
├── Components/               # Widget view components (ProductAI, ProductAttributes, OrderAttributes)
├── css/ / js/                # Static assets for the plugin
├── Domains/
│   └── DataLayer/            # LinqToDB table classes + DbContexts
│       ├── FruitBankDbContext.cs
│       ├── StockTakingDbContext.cs
│       └── *DbTable.cs       # One file per custom table
├── Infrastructure/
│   ├── PluginNopStartup.cs   # DI registration + SignalR + middleware
│   ├── RouteProvider.cs
│   ├── ViewLocationExpander.cs
│   └── FruitBankMessageTokenProvider.cs   # Overrides IMessageTokenProvider
├── Services/                 # Business logic services
├── Localization/
│   ├── quickorder.en.xml
│   └── quickorder.hu.xml
├── FruitBankPlugin.cs        # Main plugin class (IWidgetPlugin)
├── FruitBankSettings.cs      # Plugin settings (ApiKey etc.)
├── FruitBankConst.cs         # Constants
└── plugin.json
```

---

## 4. Key Services

### AI / LLM
| Service | Purpose |
|---|---|
| `OpenAIApiService` | Primary OpenAI integration – chat completions, Whisper transcription |
| `OpenAiService` | Lightweight wrapper using `gpt-4o-mini` for simple prompts |
| `CerebrasAPIService` | Alternative LLM provider |
| `ReplicateService` | Replicate.com API (image/audio models); registered with a hardcoded Bearer token |
| `AICalculationService` | AI-assisted price/measurement calculations |

### Storage
| Service | Purpose |
|---|---|
| `FileStorageService` | Generic file storage: SHA256 hash dedup, GZip compression, path building |
| `IFileStorageProvider` / `LocalFileStorageProvider` | Strategy pattern storage backend (currently local disk / wwwroot/uploads) |

**FileStorageService patterns:**
- Calculates SHA256 on upload BEFORE any AI processing → prevents duplicate API calls
- Skips GZip for already-compressed formats (jpg, pdf, mp4, zip, etc.)
- Path format: `{userId}/{featureName}/{entityType}-{entityId}/{fileName}_{id}.ext`
- DB record created first to get ID, then file is saved; rolled back on failure

### Order / Measurement
| Service | Purpose |
|---|---|
| `OrderMeasurementService` / `IOrderMeasurementService` | Handles orders that contain measurable products |
| `MeasurementService` / `IMeasurementService` | Core weighing logic |
| `InnVoiceOrderService` | Syncs orders with InnVoice accounting system |
| `InnVoiceApiService` | HTTP client for the InnVoice REST API |

### Infrastructure
| Service | Purpose |
|---|---|
| `FruitBankAttributeService` | Custom product/order attribute helpers |
| `LockService` / `ILockService` | Singleton distributed lock |
| `PdfToImageService` | Converts PDF pages to images for AI vision processing |
| `EventConsumer` | Handles `OrderPlacedEvent` |
| `FruitBankHub` | SignalR hub for real-time admin notifications |

---

## 5. Admin Controllers

| Controller | Purpose |
|---|---|
| `CustomOrderController` | Extended order management: **split order** feature (audit-based + manual selection modes), order notes, SignalR events |
| `CustomDashboardController` | AI-powered admin dashboard with `GetWelcomeMessageAsync` (store summary, order totals, stock discrepancies, OpenWeatherMap weather) |
| `ShippingController` | Shipping document management + AI PDF extraction workflow |
| `VoiceOrderController` | Voice-to-order admin tool (mobile-optimized) |
| `FruitBankAudioController` | Audio upload/processing endpoint for Whisper transcription |
| `InvoiceController` | Invoice generation and management |
| `InnVoiceOrderController` | InnVoice order sync UI |
| `InnVoiceOrderSyncController` | InnVoice sync API endpoints |
| `ManagementPageController` | General management page |
| `FileManagerController` + `FileManagerScriptsApiController` | File manager UI |
| `FileStorageController` | File storage API endpoints |
| `AppDownloadController` | App download/distribution page |
| `FruitBankPluginAdminController` | Plugin configuration page |
| `CustomProductController` | Extended product admin (IsMeasurable etc.) |

---

## 6. Public Controllers

| Controller | Route | Purpose |
|---|---|---|
| `QuickOrderController` | `/gyors-rendeles` | Customer-facing quick order page with voice + text search |
| `CheckoutController` | `/checkout/*` | Custom checkout flow override |
| `FruitBankDataController` | `/fruitbankdata/*` | Public data API endpoints; also implements `IFruitBankDataControllerServer` |

---

## 7. Widget Zones

The plugin registers widgets in:
- `PublicWidgetZones.ProductBoxAddinfoBefore` → `ProductAIWidgetViewComponent`
- `PublicWidgetZones.ProductDetailsBottom` → `ProductAIWidgetViewComponent`
- `AdminWidgetZones.ProductDetailsBlock` → `ProductAttributesViewComponent`
- `AdminWidgetZones.OrderDetailsBlock` → `OrderAttributesViewComponent`

---

## 8. DI Registration Patterns (PluginNopStartup)

Important overrides / replacements:
```csharp
// Replaces the default NopCommerce price calculator
services.Replace(ServiceDescriptor.Scoped<IPriceCalculationService, CustomPriceCalculationService>());

// Overrides email order table rendering
services.Replace(ServiceDescriptor.Scoped<IMessageTokenProvider, FruitBankMessageTokenProvider>());

// Overrides generic attribute service
services.AddScoped<IGenericAttributeService, GenericAttributeService>();

// Overrides order model and product model factories
services.AddScoped<IOrderModelFactory, CustomOrderModelFactory>();
services.AddScoped<IProductModelFactory, CustomProductModelFactory>();

// Overrides WorkflowMessageService (order emails)
services.AddScoped<IWorkflowMessageService, WorkflowMessageService>();
```

SignalR is configured with:
- MaximumReceiveMessageSize / StatefulReconnectBufferSize: 30 MB
- `DevAdminSignalRHub` on `/{FruitBankConstClient.DefaultHubName}` (WebSockets only)
- `LoggerSignalRHub` on `/{FruitBankConstClient.LoggerHubName}`

---

## 9. Database / Data Layer

Custom tables use **LinqToDB** (not EF Core) through wrapper DbTable classes registered in DI. Two DbContext wrappers:
- `FruitBankDbContext` – main plugin data
- `StockTakingDbContext` – stock taking workflow data

Key custom tables:
| DbTable class | Purpose |
|---|---|
| `PartnerDbTable` | Business partners (wholesale customers) |
| `ShippingDbTable` | Shipping records |
| `ShippingDocumentDbTable` | Parsed shipping document metadata |
| `ShippingItemDbTable` | Line items from shipping documents |
| `ShippingDocumentToFilesDbTable` | Junction: document ↔ file |
| `FilesDbTable` | Generic file records (hash, compression flag, raw text) |
| `OrderDtoDbTable` / `OrderItemDtoDbTable` | Order DTO projections |
| `OrderItemPalletDbTable` / `ShippingItemPalletDbTable` / etc. | Pallet tracking for measurement workflow |
| `StockTakingDbTable` / `StockTakingItemDbTable` | Stock audit records |
| `StockQuantityHistoryDtoDbTable` | Stock movement history |
| `MeasuringItemPalletBaseDbTable` | Base pallet measuring data |

**N+1 query prevention:** Always batch DB calls with `Task.WhenAll`. Never query per-item inside a loop.

---

## 10. Localization

All resource keys follow the prefix: `Plugins.Misc.FruitBankPlugin.*`

- Keys are registered programmatically in `FruitBankPlugin.InstallAsync()` for **both EN and HU**
- XML locale files in `/Localization/`: `quickorder.en.xml`, `quickorder.hu.xml`
- When adding new keys: update **all three places** (InstallAsync + both XML files)
- Hungarian is the **primary** language; English is secondary
- Use `_localizationService.AddOrUpdateLocaleResourceAsync("key", "value", "HU")` pattern

Common key prefixes:
- `Plugins.Misc.FruitBankPlugin.Menu.*` – navigation
- `Plugins.Misc.FruitBankPlugin.QuickOrder.*` – quick order page (extensive set)

---

## 11. Quick Order Page (`/gyors-rendeles`)

**Controller:** `QuickOrderController`  
**View:** `/Views/QuickOrder/`  
**CSS:** `/css/quick-order.css` (in plugin) + deployed to CarHaven theme

Design system tokens (CarHaven theme):
```css
--theme-color: #2d7a3a   /* green */
--active-color: #f4a236  /* amber */
--dark:         #1a3c22
--light-bg:     #f5f7f2
font-family:    'DM Sans'
border-radius:  8px
```

Product cards use full-width flex rows: `.product-card { flex-direction: row }` with `.pc-body` (left, grows) and `.pc-actions` (right, fixed).

Navigation menu integration:
- CarHaven `TopMenu/Default.cshtml` has a `<li class="quick-order-menu-item">` for both desktop (`.notmobile`) and mobile (`.mobile`) menu blocks
- Guarded by `@if (Model.DisplayCustomerInfoMenuItem)` (login-gated)
- Menu item styled in `quick-order-menu.css` (amber, bold) included via `Head.cshtml`
- Uses `fa fa-bolt` icon

Voice input:
- Records audio in browser, POSTs to `FruitBankAudioController`
- Whisper transcription with Hungarian vocabulary hints (partner names + produce terms)
- **Prompt character limit is 224** – use keyword extraction, not full company names
- Fallback: manual text search input

---

## 12. Split Order Feature

Admin page on order detail. Two modes selectable via radio buttons:

| Mode | Behaviour |
|---|---|
| **Audit-based** | Available only when order has both "started" and "non-started" audit items. Audited items stay; non-audited items move to new order. |
| **Manual selection** | Always available (except for fully audited orders). Checkbox per item; user chooses what moves. |

Split button is always enabled (except audited orders). Mode availability is communicated visually if a mode is disabled.

**Critical lesson:** `TransactionSafeAsync` caused deadlocks because `TaskHelper.ToThreadPoolTask` creates async/await context switching in ASP.NET. The transaction wrapper was removed. Avoid wrapping split logic in `TransactionSafeAsync`.

After split: inventory adjustments, order notes written, SignalR notification sent to admin clients.

---

## 13. AI Admin Dashboard (`GetWelcomeMessageAsync`)

Located in `CustomDashboardController`. Generates a structured OpenAI prompt containing:
- Store data summary
- Today's order totals
- Stock discrepancy summary (from stock taking audit)
- OpenWeatherMap weather data (real API key configured in settings)

Patterns used:
- Typed C# records for data transfer
- `Task.WhenAll` for parallel DB calls
- Batched product history queries (no N+1)
- Bilingual (Hungarian/English) system prompt with JSON field guide for the AI
- `salesAdjustmentSum` – be careful not to double-count

---

## 14. Shipping Document Processing

AI-driven workflow for extracting partner + product data from uploaded PDFs/images:

1. File uploaded → SHA256 hash calculated **before AI call**
2. Hash checked against DB → if duplicate, load existing data (skip AI, save API cost)
3. PDF converted to image(s) via `PdfToImageService` if needed
4. OpenAI vision API extracts structured product/partner data
5. Multi-stage matching: string search → historical shipping data → AI semantic match
6. UI shows visual matched/unmatched indicators + autocomplete for manual correction
7. `IsMeasurable` is **server-side only** – never expose in frontend forms

---

## 15. NopCommerce 4.80 Gotchas

| Issue | Correct approach |
|---|---|
| `ICustomerAttributeService` does not exist | Use direct `XDocument.Parse` on the XML stored in `GenericAttribute.Value` |
| `ParseAttributeValuesAsync` returns empty for free-text attributes | It's designed for predefined selection attributes (ID lookup). For free-text: parse XML directly: `<Attributes><CustomerAttribute ID="1"><CustomerAttributeValue><Value>...</Value>...` |
| `TransactionSafeAsync` + async = deadlock | `TaskHelper.ToThreadPoolTask` inside it causes context switching deadlocks in ASP.NET; remove transaction wrapper for affected code |
| Email order table customization | Override `IMessageTokenProvider` with `FruitBankMessageTokenProvider` (already done); base class constructor has many parameters – pass all through exactly |
| `OrderPlaced.CustomerNotification` email template | Configured in NopCommerce admin under Content → Message Templates; code hook is `WorkflowMessageService.SendOrderPlacedCustomerNotificationAsync` |

---

## 16. Theme (CarHaven)

Path: `D:\REPOS\MANGO\source\FruitBank\Presentation\Nop.Web\Themes\CarHaven`

Relevant files modified by this plugin's work:
- `TopMenu/Default.cshtml` – quick order nav item added
- `Head.cshtml` – includes `quick-order-menu.css`
- `css/quick-order-menu.css` – amber nav item styling

---

## 17. External APIs / Credentials

| Service | Usage | Notes |
|---|---|---|
| OpenAI | Chat completions (gpt-4o-mini / gpt-4o), Whisper transcription | API key in `FruitBankSettings.ApiKey` |
| OpenWeatherMap | Weather data for dashboard welcome message | Real API key confirmed in settings |
| Replicate | Image/audio AI models | Bearer token hardcoded in `PluginNopStartup` HTTP client registration |
| InnVoice | Hungarian accounting/invoicing system | REST API via `InnVoiceApiService` |

---

## 18. Conventions & Patterns to Follow

1. **Always bilingual** – every new locale resource key goes into InstallAsync (EN + HU) and both XML files.
2. **Mobile-first** for warehouse tools – large touch targets, step-by-step UX, pulse animations.
3. **Server-side business rules** – never expose `IsMeasurable` or similar computed flags in frontend forms.
4. **Batch DB calls** – use `Task.WhenAll`, never query inside a loop.
5. **Hash before AI** – always deduplicate files by SHA256 hash before calling any AI API.
6. **CarHaven design tokens** – use CSS variables (`--theme-color`, `--active-color`, `--dark`, `--light-bg`, `DM Sans` font) consistently.
7. **No `TransactionSafeAsync`** on code paths that use async/await through thread pool.
8. **Expect corrections** – Adam knows the codebase deeply; treat any correction as authoritative and apply it without re-litigating.

---

*Last updated: 2026-03-18 | Maintained by: Claude (auto-generated from codebase + project chat history)*