Write agents.md

[muratcakir]

[muratcakir]

This is what DeepSeek came up with (ChatGPT failed):

Smartstore Agents Guide

Overview

Smartstore is a modular, open-source e-commerce platform built on ASP.NET Core. This document helps Codex understand the structure, conventions, and key concepts of the Smartstore project.

Core Architecture Concepts

Modular Architecture

Smartstore follows a highly modular design. Features are packaged as modules that can be installed, updated, and uninstalled independently.

Module Structure Example:

[ModuleInfo(
    Name = "MyCustomModule",
    Author = "Developer Name",
    Version = "1.0",
    Description = "Adds custom functionality to Smartstore"
)]
public class MyCustomModule : ModuleBase
{
    public override async Task InstallAsync(ModuleInstallationContext context)
    {
        // Installation logic - create database tables, seed data, etc.
        await base.InstallAsync(context);
    }
    
    public override async Task UninstallAsync()
    {
        // Cleanup logic
        await base.UninstallAsync();
    }
}

Dependency Injection & IoC

Smartstore uses dependency injection extensively. Services are typically registered in module initialization:

public override void ConfigureServices(IServiceCollection services, IApplicationContext appContext)
{
    services.AddScoped<ICustomProductService, CustomProductService>();
    services.AddTransient<IOrderProcessingService, OrderProcessingService>();
    services.AddSingleton<ICacheManager, CacheManager>();
}

Key Project Structure

src/
├── Smartstore.Web/                 # Web frontend (MVC)
├── Smartstore.Core/                # Core business logic
│   ├── Common/                     # Common utilities
│   ├── Catalog/                    # Product catalog functionality
│   ├── Checkout/                   # Order processing
│   ├── Customers/                  # Customer management
│   └── Content/                    # Media management
├── Smartstore.Data/                # Data access layer (Entity Framework)
├── Smartstore.Engine/              # Application engine & bootstrapping
└── Smartstore.Web/Views/           # Razor views

modules/                            # Extension modules
├── Smartstore.OfflinePayment/      # Payment providers
├── Smartstore.Shipping/            # Shipping providers
└── Smartstore.Tax/                 # Tax calculation

tests/                              # Test projects

Common Patterns & Conventions

1. Entity Framework Usage

// Typical repository pattern usage
public class ProductService : IProductService
{
    private readonly IRepository<Product> _productRepository;
    
    public ProductService(IRepository<Product> productRepository)
    {
        _productRepository = productRepository;
    }
    
    public async Task<Product> GetProductByIdAsync(int productId)
    {
        return await _productRepository.GetByIdAsync(productId);
    }
}

2. Plugin System

Modules can extend core functionality through events and hooks:

public class CustomEventConsumer : IConsumer<OrderPlacedEvent>
{
    public async Task HandleEventAsync(OrderPlacedEvent eventMessage)
    {
        // React to order placement
        await SendConfirmationEmail(eventMessage.Order);
    }
}

3. Settings Management

// Accessing application settings
public class MyService
{
    private readonly SmartDbContext _db;
    
    public async Task<string> GetSettingAsync()
    {
        var setting = await _db.Settings
            .FirstOrDefaultAsync(x => x.Name == "MySettingName");
        return setting?.Value;
    }
}

Common Extension Points

1. Widgets

[Widget("MyCustomWidget", Zones = "content_before")]
public class MyCustomWidgetViewComponent : ViewComponent
{
    public IViewComponentResult Invoke(object widgetContext)
    {
        return View();
    }
}

2. Payment Methods

public class CustomPaymentProvider : PaymentMethodBase
{
    public override Task<ProcessPaymentResult> ProcessPaymentAsync(ProcessPaymentRequest request)
    {
        // Custom payment processing logic
    }
}

3. Export Providers

public class CustomExportProvider : IExportProvider
{
    public async Task ExportAsync(ExportExecuteContext context)
    {
        // Data export implementation
    }
}

Database Schema Highlights

Key tables to understand:

• Product - Products and variants
• Category - Product categorization
• Customer - User accounts
• Order - Order management
• Store - Multi-store support
• Setting - Configuration storage
• LocaleStringResource - Localization

API Conventions

REST API Patterns

[Route("api/products")]
public class ProductApiController : ControllerBase
{
    [HttpGet]
    public async Task<IActionResult> GetProducts([FromQuery] ProductSearchQuery query)
    {
        // API endpoint implementation
    }
    
    [HttpPost]
    public async Task<IActionResult> CreateProduct([FromBody] ProductModel model)
    {
        // Create product logic
    }
}

Testing Approach

Unit Test Example

[TestFixture]
public class ProductServiceTests
{
    private Mock<IRepository<Product>> _mockRepository;
    private ProductService _productService;
    
    [SetUp]
    public void Setup()
    {
        _mockRepository = new Mock<IRepository<Product>>();
        _productService = new ProductService(_mockRepository.Object);
    }
    
    [Test]
    public async Task GetProductByIdAsync_ReturnsProduct_WhenExists()
    {
        // Arrange
        var testProduct = new Product { Id = 1, Name = "Test Product" };
        _mockRepository.Setup(x => x.GetByIdAsync(1)).ReturnsAsync(testProduct);
        
        // Act
        var result = await _productService.GetProductByIdAsync(1);
        
        // Assert
        Assert.That(result, Is.Not.Null);
        Assert.That(result.Name, Is.EqualTo("Test Product"));
    }
}

Common Development Tasks

1. Creating new modules - Inherit from ModuleBase and implement required methods
2. Extending entities - Use entity hooks or extension methods
3. Adding new payment methods - Implement PaymentMethodBase
4. Creating custom widgets - Use [Widget] attribute with ViewComponent
5. Adding API endpoints - Create controllers in appropriate areas

Performance Considerations

• Use built-in caching mechanisms (ICacheManager)
• Implement proper database indexing
• Use async/await patterns consistently
• Leverage Smartstore's built-in performance optimizations

This guide should help Codex understand the Smartstore architecture and development patterns. The modular nature and extensive use of dependency injection make it highly extensible while maintaining a clean separation of concerns.

[Michael-Herzog]

Create a /docs directory where all relevant information about smartstore is stored. Main focus is module development.