# virtocommerce/vc-platform architecture

> Architecture diagram of the GitHub repository virtocommerce/vc-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/virtocommerce/vc-platform
- Repository: https://github.com/virtocommerce/vc-platform

## Overview

1. **What this repo is**
   This is the Virto Commerce Platform runtime: an ASP.NET Core/.NET 10 backend plus an AngularJS-based admin SPA. It is designed as a modular commerce platform, not a single business app. Most business capabilities are delivered as loadable modules rather than hard-coded features.

2. **Top-level runtime shape**
   The main executable is `src/VirtoCommerce.Platform.Web`. It hosts HTTP APIs, authentication, Swagger, health checks, SignalR push notifications, static SPA assets, and startup/configuration wiring. The rest of the solution is split into reusable libraries that the host composes.

3. **API and host boundary**
   Controllers under `Controllers/Api` expose the platform surface for modules, security, settings, localization, jobs, diagnostics, licensing, change log, and push notifications. Middleware in the web project handles API error wrapping, cache headers, security headers, and authentication/authorization behavior.

4. **Core domain and contracts**
   `VirtoCommerce.Platform.Core` defines the platform’s shared abstractions and domain primitives: entities, repositories, unit of work, commands, events, settings, dynamic properties, localization, export/import, push notifications, modularity, and security contracts. This layer is intentionally persistence- and transport-agnostic.

5. **Persistence and business services**
   `VirtoCommerce.Platform.Data` contains the concrete EF Core implementations for the shared platform features. It provides repository/unit-of-work infrastructure, CRUD/search services, settings storage, dynamic properties, localization, change log, countries, file/zip helpers, and transaction-aware file operations.

6. **Database provider split**
   The repo has separate provider packages for SQL Server, PostgreSQL, and MySQL. Each contains provider-specific EF Core configuration, migrations, health checks, and certificate loading. Architecturally, this means the platform core data model is shared, while storage behavior and schema evolution are provider-specific.

7. **Security subsystem**
   `VirtoCommerce.Platform.Security` and the web project together implement identity and authorization. The stack includes ASP.NET Core Identity, OpenIddict, custom user/role stores and managers, API key and basic auth handlers, permission authorization, external sign-in, server certificate management, and background jobs for token pruning and account lockout.

8. **Modularity and module lifecycle**
   `VirtoCommerce.Platform.Modules` is the module runtime. It handles module discovery, manifests, cataloging, installation, versioning, optional dependencies, assembly loading, and app manifest management. This is the central extensibility boundary: modules can contribute APIs, UI, settings, data, and startup behavior.

9. **Caching and scale-out coordination**
   `VirtoCommerce.Platform.Caching` and `VirtoCommerce.Platform.DistributedLock` provide cache regions, memory cache abstractions, Redis-backed cache invalidation, and distributed locks. This matters for multi-instance deployments where module state, settings, and notifications must stay consistent across nodes.

10. **Background processing**
   `VirtoCommerce.Platform.Hangfire` integrates Hangfire for recurring and background jobs. The web host uses it for scheduled jobs and operational tasks, with explicit user-context middleware and authorization hooks for the admin experience.

11. **Push notifications and real-time UI**
   Push notifications are modeled in Core and implemented in Web with SignalR hubs, in-memory storage, and a scalable notification manager. This is used by admin workflows and long-running operations such as module installation, export/import, and job progress.

12. **Admin UI structure**
   The admin front end lives in `wwwroot/js/app` and is organized by feature areas such as security, settings, modularity, dynamic properties, change log, diagnostics, and user profile. The UI uses a blade/navigation pattern, feature-specific resources/services/widgets, and localized JSON bundles under `wwwroot/Localizations`.

13. **Data flow through the platform**
   Typical request flow is: SPA or external client -> web controller -> application/service layer -> repository/EF Core -> relational database. For cross-cutting concerns, the same flow may also trigger events, cache invalidation, push notifications, or background jobs.

14. **Operational/deployment boundaries**
   The repo includes Docker Compose files, Azure deployment templates, and GitHub workflows, indicating it is meant to run in containerized and cloud deployments. The docs also reference Redis and a broader local stack, reinforcing that the platform is built for distributed, modular commerce environments.

15. **Where to draw the main diagram boxes**
   A useful architecture diagram would show: the Web host at the center; Core as shared contracts; Data and provider-specific persistence underneath; Modules as a runtime/plugin subsystem; Security, Caching, Distributed Lock, and Hangfire as cross-cutting services; and the AngularJS admin SPA and external clients as consumers of the APIs.

Main entry points: [`src/VirtoCommerce.Platform.Web`](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web) (Platform Web), [`src/VirtoCommerce.Platform.Data`](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Data) (Platform Data), [`src/VirtoCommerce.Platform.Web/wwwroot/js/app`](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web/wwwroot/js/app) (Admin SPA), [`src/VirtoCommerce.Platform.Modules`](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Modules) (Module runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Web host"]
  node_web_host["Platform Web<br/>ASP.NET Core host"]
  node_api_controllers["API controllers<br/>HTTP API<br/>[Api]"]
  node_web_security["Web security<br/>authn/authz<br/>[Security]"]
  node_web_push["Push runtime<br/>SignalR notifications<br/>[PushNotifications]"]
end

subgraph group_shared["Shared platform"]
  node_core["Platform Core<br/>contracts & primitives"]
  node_core_domain["Domain model<br/>entities & UoW<br/>[Domain]"]
  node_core_modularity["Modularity contracts<br/>plugin model<br/>[Modularity]"]
  node_core_security["Security contracts<br/>identity model<br/>[Security]"]
  node_core_settings["Settings model<br/>configuration model<br/>[Settings]"]
  node_core_push["Push contracts<br/>notification model<br/>[PushNotifications]"]
end

subgraph group_storage["Persistence"]
  node_data["Platform Data<br/>EF Core services"]
  node_data_security["Security store<br/>EF Core security"]
  node_provider_sql["SQL Server<br/>db provider"]
  node_provider_pg["PostgreSQL<br/>db provider"]
  node_provider_mysql["MySQL<br/>db provider"]
end

subgraph group_extensibility["Extensibility"]
  node_modules["Module runtime<br/>plugin loader"]
  node_caching["Caching<br/>cache regions"]
  node_dist_lock["Distributed lock<br/>coordination"]
  node_hangfire["Hangfire<br/>background jobs"]
end

subgraph group_client["Admin UI"]
  node_spa["Admin SPA<br/>AngularJS backoffice<br/>[app]"]
  node_locales["Translations<br/>ui localization<br/>[Localizations]"]
end

subgraph group_external["Consumers"]
  node_clients(("Clients<br/>api consumers"))
  node_deploy["Deploy stack<br/>ops artifacts"]
end

node_clients -->|"HTTP/SPA"| node_web_host
node_spa -->|"calls"| node_api_controllers
node_web_host -->|"hosts"| node_api_controllers
node_web_host -->|"configures"| node_web_security
node_web_host -->|"serves"| node_web_push
node_web_host -->|"loads modules"| node_modules
node_web_host -->|"runs jobs"| node_hangfire
node_web_host -->|"uses cache"| node_caching
node_web_host -->|"uses locks"| node_dist_lock
node_web_host -->|"uses"| node_data
node_web_security -->|"persists identity"| node_data_security
node_data -->|"implements"| node_core
node_data_security -->|"implements"| node_core_security
node_data -->|"provider split"| node_provider_sql
node_data -->|"provider split"| node_provider_pg
node_data -->|"provider split"| node_provider_mysql
node_modules -->|"implements"| node_core_modularity
node_caching -->|"supports"| node_core
node_dist_lock -->|"supports"| node_core
node_hangfire -->|"integrates"| node_web_host
node_web_push -->|"implements"| node_core_push
node_spa -->|"loads"| node_locales
node_spa -->|"extends via modules"| node_modules
node_modules -->|"publishes UI"| node_spa
node_deploy -.->|"deploys"| node_web_host

click node_web_host "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web"
click node_api_controllers "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web/Controllers/Api"
click node_web_security "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web/Security"
click node_web_push "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web/PushNotifications"
click node_core "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core"
click node_core_domain "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core/Domain"
click node_core_modularity "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core/Modularity"
click node_core_security "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core/Security"
click node_core_settings "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core/Settings"
click node_core_push "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core/PushNotifications"
click node_data "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Data"
click node_data_security "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Security"
click node_provider_sql "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Data.SqlServer"
click node_provider_pg "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Data.PostgreSql"
click node_provider_mysql "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Data.MySql"
click node_modules "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Modules"
click node_caching "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Caching"
click node_dist_lock "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.DistributedLock"
click node_hangfire "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Hangfire"
click node_spa "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web/wwwroot/js/app"
click node_locales "https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web/wwwroot/Localizations"
click node_deploy "https://github.com/virtocommerce/vc-platform/tree/dev/DockerCompose"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_host,node_api_controllers,node_web_security,node_web_push toneBlue
class node_core,node_core_domain,node_core_modularity,node_core_security,node_core_settings,node_core_push toneAmber
class node_data,node_data_security,node_provider_sql,node_provider_pg,node_provider_mysql toneMint
class node_modules,node_caching,node_dist_lock,node_hangfire toneRose
class node_spa,node_locales toneIndigo
class node_clients,node_deploy toneTeal
```

## Components

### Web host

ASP.NET Core runtime, API surface, middleware, Swagger, health checks, SignalR, and admin SPA delivery.

- [Platform Web](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web): ASP.NET Core host · Main executable that wires HTTP APIs, middleware, auth, Swagger, health checks, SignalR, static assets, and startup composition. · `src/VirtoCommerce.Platform.Web`
- [API controllers](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web/Controllers/Api): HTTP API · Controller surface for modules, security, settings, localization, jobs, diagnostics, licensing, change log, and push notifications. · `src/VirtoCommerce.Platform.Web/Controllers/Api`
- [Web security](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web/Security): authn/authz · Authentication handlers, OpenIddict integration, authorization policy provider, and security background jobs. · `src/VirtoCommerce.Platform.Web/Security`
- [Push runtime](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web/PushNotifications): SignalR notifications · SignalR hub, in-memory notification storage, scalable notification manager, and synchronization task. · `src/VirtoCommerce.Platform.Web/PushNotifications`

### Shared platform

Core abstractions and reusable platform services composed by the host.

- [Platform Core](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core): contracts & primitives · Shared domain abstractions, commands, events, settings, modularity contracts, security contracts, export/import, and push notification models. · `src/VirtoCommerce.Platform.Core`
- [Domain model](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core/Domain): entities & UoW · Base entities, repositories, unit of work, value objects, factories, and tracking primitives. · `src/VirtoCommerce.Platform.Core/Domain`
- [Modularity contracts](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core/Modularity): plugin model · Module manifests, dependency solving, install lifecycle, assembly loading contracts, startup hooks, and optional dependency support. · `src/VirtoCommerce.Platform.Core/Modularity`
- [Security contracts](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core/Security): identity model · Users, roles, permissions, API keys, server certificates, external sign-in, and security events/contracts. · `src/VirtoCommerce.Platform.Core/Security`
- [Settings model](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core/Settings): configuration model · Setting descriptors, localized settings, overrides, and search/update contracts. · `src/VirtoCommerce.Platform.Core/Settings`
- [Push contracts](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Core/PushNotifications): notification model · Push notification abstractions, search criteria, storage contract, and options. · `src/VirtoCommerce.Platform.Core/PushNotifications`

### Persistence

EF Core data layer plus database-provider specific configuration and migrations.

- [Platform Data](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Data): EF Core services · Concrete persistence, CRUD/search services, settings storage, dynamic properties, localization, change log, and file helpers. · `src/VirtoCommerce.Platform.Data`
- [Security store](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Security): EF Core security · Security DbContext, repositories, user/role/session services, API keys, and server certificate persistence. · `src/VirtoCommerce.Platform.Security`
- [SQL Server](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Data.SqlServer): db provider · SQL Server-specific EF Core configuration, migrations, health checks, and certificate loading. · `src/VirtoCommerce.Platform.Data.SqlServer`
- [PostgreSQL](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Data.PostgreSql): db provider · PostgreSQL-specific EF Core configuration, migrations, health checks, and certificate loading. · `src/VirtoCommerce.Platform.Data.PostgreSql`
- [MySQL](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Data.MySql): db provider · MySQL-specific EF Core configuration, migrations, health checks, and certificate loading. · `src/VirtoCommerce.Platform.Data.MySql`

### Extensibility

Module runtime, background jobs, caching, distributed coordination, and push notifications.

- [Module runtime](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Modules): plugin loader · Discovers, installs, catalogs, loads, and manages modules and app manifests. · `src/VirtoCommerce.Platform.Modules`
- [Caching](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Caching): cache regions · Memory and Redis-backed cache regions and invalidation messaging. · `src/VirtoCommerce.Platform.Caching`
- [Distributed lock](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.DistributedLock): coordination · No-op and Redis-backed distributed locking for multi-instance consistency. · `src/VirtoCommerce.Platform.DistributedLock`
- [Hangfire](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Hangfire): background jobs · Recurring/background job integration, user-context middleware, and authorization hooks. · `src/VirtoCommerce.Platform.Hangfire`

### Admin UI

AngularJS backoffice SPA, localized assets, and feature blades.

- [Admin SPA](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web/wwwroot/js/app): AngularJS backoffice · Feature-based admin UI with blades, resources, widgets, navigation, localization, and common UI components. · `src/VirtoCommerce.Platform.Web/wwwroot/js/app`
- [Translations](https://github.com/virtocommerce/vc-platform/blob/dev/src/VirtoCommerce.Platform.Web/wwwroot/Localizations): ui localization · Server and client localization bundles and country/language resources. · `src/VirtoCommerce.Platform.Web/wwwroot/Localizations`

### Consumers

External clients and deployment/runtime environments that interact with the platform.

- **Clients**: api consumers · External clients, storefronts, and deployment/runtime environments that consume the platform APIs.
- [Deploy stack](https://github.com/virtocommerce/vc-platform/tree/dev/DockerCompose): ops artifacts · Docker, compose, Azure templates, and CI/CD workflows used to run and ship the platform. · `DockerCompose`

## Connections

- Clients → Platform Web: HTTP/SPA · External clients and the admin UI reach the platform through the web host.
- Admin SPA → API controllers: calls · The backoffice SPA talks to the API controller surface.
- Platform Web → API controllers: hosts · The host exposes the platform API surface.
- Platform Web → Web security: configures · The host wires authentication, authorization, and security jobs.
- Platform Web → Push runtime: serves · The host publishes push notifications over SignalR.
- Platform Web → Module runtime: loads modules · Startup composes the module runtime and module contributions.
- Platform Web → Hangfire: runs jobs · The host integrates recurring and background job execution.
- Platform Web → Caching: uses cache · The host depends on shared caching and invalidation.
- Platform Web → Distributed lock: uses locks · The host coordinates multi-instance operations with distributed locks.
- Platform Web → Platform Data: uses · The host delegates business data operations to the persistence layer.
- Web security → Security store: persists identity · Security features are backed by EF Core repositories and stores.
- Platform Data → Platform Core: implements · Concrete data services implement shared platform contracts.
- Security store → Security contracts: implements · Security persistence and services implement core security contracts.
- Platform Data → SQL Server: provider split · SQL Server package supplies provider-specific persistence behavior.
- Platform Data → PostgreSQL: provider split · PostgreSQL package supplies provider-specific persistence behavior.
- Platform Data → MySQL: provider split · MySQL package supplies provider-specific persistence behavior.
- Module runtime → Modularity contracts: implements · The module runtime realizes the modularity contracts.
- Caching → Platform Core: supports · Caching primitives are defined in the shared core and implemented in the cache package.
- Distributed lock → Platform Core: supports · Distributed lock abstractions are shared through core contracts.
- Hangfire → Platform Web: integrates · Background job infrastructure is hosted by the web app.
- Push runtime → Push contracts: implements · SignalR and storage services implement push notification contracts.
- Admin SPA → Translations: loads · The SPA consumes localized UI bundles.
- Admin SPA → Module runtime: extends via modules · Feature areas in the admin shell are module-driven.
- Module runtime → Admin SPA: publishes UI · Modules contribute UI blades, widgets, and navigation.
- Deploy stack → Platform Web: deploys · Container and cloud artifacts target the web host.