# Architecture

## Dependency Graph

```
AyCode.Core (net9.0, DLL refs: AyCode.Interfaces, .Entities, .Core, .Utils, + .Server variants)
    ↑
Mango.Nop.Core (net9.0, no nopCommerce runtime dependency)
    ↑
Mango.Nop.Data (net9.0) → Nop.Core, Nop.Data
    ↑
Mango.Nop.Services (net9.0) → Nop.Core, Nop.Data, Nop.Services, Nop.Web.Framework
```

**Rule:** Dependencies flow upward only. `Mango.Nop.Core` has zero nopCommerce runtime dependency — it uses mirror copies in `NopDependencies/`.

## Project Roles

### Mango.Nop.Core — Domain Layer
Zero nopCommerce runtime dependency. Contains:
- **DTOs** (`Dtos/`) — `ModelDtoBase<TMainEntity>` with bidirectional entity mapping (`CopyEntityValuesToDto`, `CreateMainEntity`)
- **Entities** (`Entities/`) — `MgEntityBase` (inherits `BaseEntity`, implements `IEntityInt`)
- **NopDependencies** (`NopDependencies/`) — mirror copies of nopCommerce entities (`BaseEntity`, `Customer`, `Order`, `Product`, `GenericAttribute`, enums). Allows referencing without full nopCommerce dependency chain.
- **Extensions** (`Extensions/`) — `GenericAttributeExtensions` for typed attribute access, `CollectionExtensionsNopBaseEntity` for collection operations
- **Interfaces** (`Interfaces/`) — DTO interfaces, soft-delete, foreign key markers
- **Models** (`Models/`) — Login request/response
- **Loggers** (`Loggers/`) — `ILogger` abstraction

### Mango.Nop.Data — Data Access Layer
Wraps nopCommerce data infrastructure with custom base classes:
- **`MgDbTableBase<TEntity>`** — extends nopCommerce `EntityRepository<TEntity>`, adds `GetAll()`, timestamp handling (`ITimeStampCreated`, `ITimeStampUpdated`), event publishing
- **`MgDtoDbTableBase`** — DTO-aware repository with entity ↔ DTO mapping
- **`MgDbContextBase`** — EF Core context base for custom tables
- **`MgDalBase`** — Data Access Layer orchestrator

### Mango.Nop.Services — Service Layer
Service base classes for nopCommerce plugin development:
- **`MgBackgroundServiceBase`** — hosted background task base
- **`MgSessionServiceBase`** / `MgSessionItemBase` — session management
- **`MgEventConsumerBase`** — nopCommerce entity event handler base
- **`MgLockServiceBase`** — distributed locking
- **`NopLogWriter`** — logging bridge to nopCommerce log system

## NopDependencies Pattern

`Mango.Nop.Core/NopDependencies/` contains mirror copies of nopCommerce entity classes with the **same namespace** as the original nopCommerce types:

```csharp
// In NopDependencies/BaseEntity.cs — same namespace as nopCommerce
namespace Nop.Core;
public abstract partial class BaseEntity : IBaseEntity
{
    public int Id { get; set; }
}
```

This allows `Mango.Nop.Core` to be referenced by projects that don't have a direct nopCommerce dependency (e.g., Blazor/MAUI clients), while maintaining type compatibility with the real nopCommerce entities at the server level.

## Reference Modes

```
                      Mango.Nop Libraries
                     ┌──────────────────────┐
                     │  Core  Data  Services │
                     └──┬──────┬──────┬─────┘
                        │      │      │
        ┌───────────────┤      │      │
        │ (DLL, Core    │      │      │
        │  only)        │      │      │
        ▼               ▼      ▼      ▼
  Types-only clients   Full-stack nopCommerce
  (Blazor/MAUI/etc.)  plugins (server-side)
```