From 2bbe754e9baf8825691d3389d9e67e430e077dbb Mon Sep 17 00:00:00 2001 From: o2alex Date: Tue, 7 Jan 2025 11:05:55 -0800 Subject: [PATCH] docs: add comprehensive plugin architecture documentation with UML diagrams --- PLUGIN_ARCHITECTURE.md | 304 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100644 PLUGIN_ARCHITECTURE.md diff --git a/PLUGIN_ARCHITECTURE.md b/PLUGIN_ARCHITECTURE.md new file mode 100644 index 00000000000..65f1b3a2cbd --- /dev/null +++ b/PLUGIN_ARCHITECTURE.md @@ -0,0 +1,304 @@ +# nopCommerce Plugin Architecture Guide + +## Overview +nopCommerce plugins are modular components that extend the core functionality of the platform. Each plugin is a separate project that follows a specific structure and implements certain interfaces to integrate with the main application. + +## Plugin Types +nopCommerce supports various types of plugins, each serving different purposes: + +1. Widget Plugins (`IWidgetPlugin`) +2. Payment Plugins +3. Shipping Plugins +4. Tax Plugins +5. Authentication Plugins +6. Misc Plugins (`IMiscPlugin`) +7. Exchange Rate Plugins +8. Discovery Plugins +9. External Authentication Plugins + +## Basic Plugin Structure + +``` +Plugin.Name/ +├── Controllers/ # MVC Controllers +├── Models/ # View Models +├── Views/ # Razor Views +├── Infrastructure/ # Plugin infrastructure +├── Services/ # Plugin-specific services +├── plugin.json # Plugin metadata +└── PluginName.cs # Main plugin class +``` + +## Core Components + +### 1. Main Plugin Class +Every plugin must have a main class that inherits from `BasePlugin` and implements relevant plugin interface: + +```csharp +public class MyPlugin : BasePlugin, IPluginInterface +{ + // Constructor with dependency injection + public MyPlugin(IDependency dependency) + { + _dependency = dependency; + } + + // Required overrides + public override string GetConfigurationPageUrl() + { + // Return configuration page URL if plugin is configurable + } + + // Installation logic + public override async Task InstallAsync() + { + await base.InstallAsync(); + // Custom installation logic + } + + // Uninstallation logic + public override async Task UninstallAsync() + { + await base.UninstallAsync(); + // Custom uninstallation logic + } +} +``` + +### 2. Plugin Metadata (plugin.json) +Each plugin must include a `plugin.json` file with metadata: + +```json +{ + "Group": "Plugin category", + "FriendlyName": "Display name", + "SystemName": "Technical.Plugin.Name", + "Version": "1.0", + "SupportedVersions": ["4.60"], + "Author": "Plugin author", + "DisplayOrder": 1, + "FileName": "Plugin.Name.dll" +} +``` + +### 3. Dependencies +Plugins can use dependency injection to access nopCommerce services and infrastructure: + +- Core services (`IWebHelper`, `IWorkContext`, etc.) +- Data access (`IRepository`) +- Custom services specific to the plugin + +## Plugin Development Guidelines + +1. **Separation of Concerns** + - Keep plugin code modular and focused + - Use proper layering (presentation, business logic, data access) + +2. **Configuration** + - Implement `GetConfigurationPageUrl()` for configurable plugins + - Use nopCommerce's settings system for storing configuration + +3. **Dependency Injection** + - Use constructor injection + - Register plugin-specific services in DI container + +4. **Installation/Uninstallation** + - Override `InstallAsync()` and `UninstallAsync()` + - Handle database migrations, settings, and localization + +5. **Views and UI** + - Follow nopCommerce's UI conventions + - Use proper view locations and naming + +## Best Practices + +1. **Version Compatibility** + - Specify supported nopCommerce versions + - Test against target versions + +2. **Error Handling** + - Implement proper exception handling + - Log errors appropriately + +3. **Performance** + - Optimize database queries + - Cache when appropriate + - Minimize resource usage + +4. **Security** + - Validate all inputs + - Follow security best practices + - Use proper authorization + +5. **Localization** + - Support multiple languages + - Use resource files for strings + +## UML Diagrams + +### 1. Plugin Class Hierarchy +```mermaid +classDiagram + class IPlugin { + <> + +GetConfigurationPageUrl()* string + +InstallAsync()* Task + +UninstallAsync()* Task + +PreparePluginToUninstall()* Task + } + + class BasePlugin { + <> + +GetConfigurationPageUrl() string + +InstallAsync() Task + +UninstallAsync() Task + +PreparePluginToUninstall() Task + } + + class IWidgetPlugin { + <> + +GetWidgetZones()* Task> + +GetWidgetViewComponentName()* string + } + + class IMiscPlugin { + <> + } + + class IPaymentMethod { + <> + +ProcessPaymentAsync()* Task + +PostProcessPaymentAsync()* Task + +GetPaymentMethodDescription()* string + } + + IPlugin <|-- BasePlugin + BasePlugin <|-- CustomPlugin + IPlugin <|-- IWidgetPlugin + IPlugin <|-- IMiscPlugin + IPlugin <|-- IPaymentMethod + + class CustomPlugin { + -_dependencies + +Constructor(dependencies) + +GetConfigurationPageUrl() string + +InstallAsync() Task + +UninstallAsync() Task + } +``` + +### 2. Plugin Lifecycle +```mermaid +stateDiagram-v2 + [*] --> NotInstalled + NotInstalled --> Installing: Install Plugin + Installing --> Installed: InstallAsync() + Installed --> Configured: Configure + Configured --> Active: Enable + Active --> Inactive: Disable + Inactive --> Active: Enable + Active --> Uninstalling: Uninstall + Inactive --> Uninstalling: Uninstall + Uninstalling --> [*]: UninstallAsync() +``` + +### 3. Plugin Component Interaction +```mermaid +graph TB + A[nopCommerce Core] --> B[Plugin Manager] + B --> C[Plugin Loader] + C --> D[Plugin Discovery] + D --> E[Plugin Instance] + + E --> F[Plugin Services] + E --> G[Plugin Controllers] + E --> H[Plugin Views] + + I[Database] --> F + J[nopCommerce Services] --> F + + F --> G + G --> H +``` + +### 4. Plugin Request Flow +```mermaid +sequenceDiagram + participant U as User + participant C as Controller + participant P as Plugin + participant S as Services + participant D as Database + + U->>C: Request + C->>P: Process Request + P->>S: Use Core Services + S->>D: Data Operations + D-->>S: Return Data + S-->>P: Process Data + P-->>C: Return Result + C-->>U: Response +``` + +### 5. Plugin Dependencies +```mermaid +graph LR + A[Plugin] --> B[Core Services] + A --> C[Data Access] + A --> D[Settings] + A --> E[Localization] + + B --> F[IWorkContext] + B --> G[IWebHelper] + + C --> H[IRepository] + C --> I[DbContext] + + D --> J[ISettingService] + E --> K[ILocalizationService] +``` + +These diagrams illustrate: +1. The class hierarchy and relationships between different plugin types +2. The lifecycle of a plugin from installation to uninstallation +3. How plugin components interact with each other and the core system +4. The flow of a typical plugin request +5. Common dependencies and services used by plugins + +## Common Interfaces + +- `IPlugin`: Base interface for all plugins +- `IWidgetPlugin`: For widgets and UI components +- `IPaymentMethod`: For payment gateways +- `IShippingRateComputationMethod`: For shipping providers +- `ITaxProvider`: For tax calculation +- `IMiscPlugin`: For general purpose plugins +- `IExternalAuthenticationMethod`: For authentication providers + +## Testing + +1. **Unit Testing** + - Test plugin business logic + - Mock dependencies + +2. **Integration Testing** + - Test plugin integration with nopCommerce + - Test database operations + +## Deployment + +1. **Building** + - Build plugin against correct nopCommerce version + - Include all required dependencies + +2. **Installation** + - Copy to proper plugin directory + - Follow nopCommerce plugin installation guidelines + +## Common Pitfalls to Avoid + +1. Don't modify core nopCommerce files +2. Don't use hard-coded strings (use localization) +3. Don't ignore async/await patterns +4. Don't store sensitive data in plain text +5. Don't skip proper error handling