# simplcommerce/simplcommerce architecture

> Architecture diagram of the GitHub repository simplcommerce/simplcommerce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simplcommerce/simplcommerce
- Repository: https://github.com/simplcommerce/simplcommerce

## Overview

##### Project type and purpose
- This is a full‑stack “modulith” e‑commerce system (SimplCommerce) built on ASP.NET Core.
- Its purpose is to provide a highly modular monolithic architecture where each e‑commerce domain (Catalog, Orders, Payments, CMS, etc.) is implemented as a discrete module that the central WebHost loads at runtime.

##### File structure
- Top level:
- src/SimplCommerce.WebHost – the ASP.NET Core host application, IdentityServer configuration, EF Core migrations, static file serving, Angular‑based admin UI.
- src/SimplCommerce.Infrastructure – shared abstractions, repositories, model base classes, module loader, scheduling, validation.
- src/Modules – one folder per domain module (Core, Catalog, Orders, Payments, Tax, Shipping, Inventory, Notifications, etc.). Each module contains Areas/[Feature]/Controllers, ViewModels, Views, Models, Services, Data (custom EF model builders), module.json and bundleconfig.json.
- A test/ folder for unit and integration tests.
- Build scripts, Dockerfiles, CI/CD pipelines, sample SQL seeds under src/Database.

##### README for additional insights
- Tech stack: ASP.NET Core, EF Core, ASP.NET Identity, Angular 1.x, MediatR for domain events.
- Deployment options: SQL Server or PostgreSQL, Docker, AWS Elastic Beanstalk, Azure Pipelines.

a. Main components
- WebHost (ASP.NET Core application)
- Infrastructure library
- Domain Modules (Core, Catalog, Orders, Payments, CMS, etc.)
- Database (SQL Server, PostgreSQL, MySQL, SQLite)
- Front‑end: Angular 1.x admin UI and MVC/Razor storefront views
- External services: Email (SendGrid/SMTP), Storage (Amazon S3/Azure Blob/Local), Hangfire (background jobs), SignalR (real‑time notifications)
b. Relationships and interactions
- WebHost loads Infrastructure + all Domain Modules on startup via IModuleInitializer and DynamicModelBuilder
- Each Module contributes EF model fragments (CustomModelBuilder) to a single DbContext
- HTTP requests to WebHost → routed to module controllers via ASP.NET Core routing (Areas)
- Angular UI invokes RESTful APIs exposed by module controllers
- Domain events (MediatR) propagate inside modules; handlers in other modules respond (e.g., Inventory listens to OrderCreated events)
- Background tasks (Hangfire) scheduled from modules or host
- Infrastructure utilities and cross‑cutting concerns (logging, caching, scheduling) used by all modules
- External dependencies (S3/Azure Blob) invoked by storage modules; email modules call SendGrid or SMTP
c. Architectural patterns and design principles
- Modular Monolith (“modulith”) with plugin‑style loading
- Onion/Clean architecture: modules define Services → Controllers → ViewModels, depend on Infrastructure abstractions via DI
- EF Core model composition via ICustomModelBuilder in each module
- Domain events (publisher/subscriber) implemented using MediatR
- Separation of concerns between UI assets (Angular, CSS, JS bundles) and server logic
d. Key technologies/frameworks
- ASP.NET Core 8 → WebHost, Controllers, Middleware, DI
- Entity Framework Core → DbContext, Migrations, SQL database
- ASP.NET Identity Core → authentication, user management
- Angular 1.x → admin SPA UI, RESTful services via $http
- MediatR → domain event bus
- Hangfire → background/recurring jobs
- SignalR → real‑time notifications

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        style FrontendLayer fill:#f9f,stroke:#333,stroke-width:1px
        AngularAdminUI["Angular 1.x Admin UI"]:::frontend
        RazorStorefront["Razor Storefront Views"]:::frontend
    end

    %% WebHost and Infrastructure
    subgraph "WebHost (ASP.NET Core)" 
        style WebHostContainer fill:#bbdefb,stroke:#1e88e5,stroke-width:2px
        WebHost["WebHost"]:::host
        IdentityServer["IdentityServerConfig"]:::host
        Migrations["EF Core Migrations"]:::host
        ModulesJson["modules.json"]:::host
        subgraph "Themes"
            CozaStore["CozaStore Theme"]:::host
        end
        subgraph "Infrastructure"
            style InfraContainer fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
            Infrastructure["Infrastructure Library"]:::host
            IModuleInitializer["IModuleInitializer.cs"]:::host
            ModuleConfigMgr["ModuleConfigurationManager.cs"]:::host
        end
    end

    %% Domain Modules
    subgraph "Domain Modules" 
        style ModulesContainer fill:#c8e6c9,stroke:#388e3c,stroke-width:2px
        Catalog["Catalog Module"]:::module
        Orders["Orders Module"]:::module
        Payments["Payments Module"]:::module
        CMS["CMS Module"]:::module
        Inventory["Inventory Module"]:::module
        Notifications["Notifications Module"]:::module
        HangfireJobs["Hangfire Jobs Module"]:::module
        SignalRMod["SignalR Module"]:::module
        EmailSG["Email SendGrid Module"]:::module
        EmailSMTP["Email SMTP Module"]:::module
        StorageS3["Storage Amazon S3 Module"]:::module
        StorageAzure["Storage Azure Blob Module"]:::module
        StorageLocal["Storage Local Module"]:::module
    end

    %% Database and External
    Database[(Database)]:::external
    HangfireDB[(Hangfire)]:::external
    EmailService[(SendGrid/SMTP)]:::external
    StorageService[(S3/Azure Blob/Local)]:::external
    SignalRService[(SignalR)]:::external

    %% UI to WebHost
    AngularAdminUI -->|"HTTP REST calls"| WebHost
    RazorStorefront -->|"MVC Requests"| WebHost

    %% WebHost to Infrastructure and Modules
    WebHost -->|"Loads on Startup"| Infrastructure
    WebHost -->|"Loads Modules via IModuleInitializer"| Catalog
    WebHost --> Orders
    WebHost --> Payments
    WebHost --> CMS
    WebHost --> Inventory
    WebHost --> Notifications
    WebHost --> HangfireJobs
    WebHost --> SignalRMod
    WebHost --> EmailSG
    WebHost --> EmailSMTP
    WebHost --> StorageS3
    WebHost --> StorageAzure
    WebHost --> StorageLocal

    %% Modules to Infrastructure
    Catalog -->|"Uses abstractions"| Infrastructure
    Orders --> Infrastructure
    Payments --> Infrastructure
    CMS --> Infrastructure
    Inventory --> Infrastructure
    Notifications --> Infrastructure

    %% EF Core model composition
    Catalog -->|"CustomModelBuilder"| Database
    Orders --> Database
    Payments --> Database
    CMS --> Database
    Inventory --> Database
    Notifications --> Database

    %% Domain events
    Orders -->|"OrderCreated Event"| Inventory
    Orders -->|"OrderCreated Event"| EmailSG

    %% Background jobs
    HangfireJobs -->|"Schedules Jobs"| HangfireDB

    %% Real-time notifications
    SignalRMod -->|"Push notifications"| SignalRService

    %% External service integrations
    EmailSG --> EmailService
    EmailSMTP --> EmailService
    StorageS3 --> StorageService
    StorageAzure --> StorageService
    StorageLocal --> StorageService

    %% Click Events
    click WebHost "https://github.com/simplcommerce/simplcommerce/blob/master/src/SimplCommerce.WebHost"
    click Infrastructure "https://github.com/simplcommerce/simplcommerce/blob/master/src/SimplCommerce.Infrastructure"
    click IModuleInitializer "https://github.com/simplcommerce/simplcommerce/blob/master/src/SimplCommerce.Infrastructure/Modules/IModuleInitializer.cs"
    click ModuleConfigMgr "https://github.com/simplcommerce/simplcommerce/blob/master/src/SimplCommerce.Infrastructure/Modules/ModuleConfigurationManager.cs"
    click Migrations "https://github.com/simplcommerce/simplcommerce/tree/master/src/SimplCommerce.WebHost/Migrations"
    click IdentityServer "https://github.com/simplcommerce/simplcommerce/blob/master/src/SimplCommerce.WebHost/IdentityServer/IdentityServerConfig.cs"
    click ModulesJson "https://github.com/simplcommerce/simplcommerce/blob/master/src/SimplCommerce.WebHost/modules.json"
    click CozaStore "https://github.com/simplcommerce/simplcommerce/tree/master/src/SimplCommerce.WebHost/Themes/CozaStore"
    click Catalog "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.Catalog"
    click Orders "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.Orders"
    click Payments "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.Payments"
    click CMS "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.Cms"
    click Inventory "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.Inventory"
    click Notifications "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.Notifications"
    click HangfireJobs "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.HangfireJobs"
    click SignalRMod "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.SignalR"
    click EmailSG "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.EmailSenderSendgrid"
    click EmailSMTP "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.EmailSenderSmtp"
    click StorageS3 "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.StorageAmazonS3"
    click StorageAzure "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.StorageAzureBlob"
    click StorageLocal "https://github.com/simplcommerce/simplcommerce/blob/master/src/Modules/SimplCommerce.Module.StorageLocal"

    %% Styles
    classDef host fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef module fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    classDef frontend fill:#fff59d,stroke:#fbc02d,color:#f57f17
    classDef external fill:#e0e0e0,stroke:#9e9e9e,color:#424242
```
