# azure/commercial-marketplace-saas-accelerator architecture

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

- Interactive diagram: https://gitdiagram.com/azure/commercial-marketplace-saas-accelerator
- Repository: https://github.com/azure/commercial-marketplace-saas-accelerator

## Overview

##### Main components
- Publisher Portal (AdminSite): This web application is designed for managing usage events, application logs, and other administrative tasks. It follows an MVC pattern with controllers, views (with partials, shared layouts, etc.), and integrates with front-end assets (CSS, JavaScript libraries, FontAwesome, etc.).
- Customer Portal (CustomerSite): This is the front-end web application that demonstrates how end customers register, manage subscriptions, and interact with the SaaS solution. It also adheres to the MVC pattern.
- Client Data Access Layer (DataAccess): A library using Entity Framework for persisting SaaS data to an Azure SQL Database. It includes the data context, entities, contract repositories, and migration scripts.
- Services Client Library (Services): This library contains business logic and service implementations that call the SaaS Fulfillment API and the Marketplace Metering Service API. It orchestrates API interactions and acts as the intermediary between the presentation (portals) and the data layer.
- Background Job (MeteredTriggerJob): A scheduled or triggered job that likely manages metered billing events by interfacing with the metering API.
- Unit and UI Tests (Services.Test and UI.Test): These projects support testing of functionality and provide validation of the major components.
- Deployment & CI/CD: The presence of the /deployment folder (with PowerShell scripts) and multiple GitHub Actions workflows (.github/workflows) shows that there are automated build, test, and deployment processes.
- Supporting Documentation: Extensive documentation in the /docs directory (including architecture, security, monitoring guidelines, etc.) further explains design decisions and usage.

##### Relationships and Interactions
- The Customer and Publisher portals both serve as distinct presentation layers – each with controllers, views, and static assets – consuming the Services client library.
- The Services layer exposes functionality (e.g., subscription management, billing, and event logging) and communicates with both the SaaS Fulfillment API and the Marketplace Metering API.
- The DataAccess library is used by the Services layer (and possibly directly by the Admin portal) for entity persistence and is built on top of Entity Framework. The migration scripts and SQL server monitoring docs indicate its reliance on Azure SQL (or a similar relational database).
- The MeteredTriggerJob acts as a background processor to periodically drive metering operations, ensuring usage events and billing information are updated.
- External dependencies include Microsoft Commercial Marketplace APIs (SaaS Fulfillment and Metering), as well as standard open-source frameworks/libraries (Bootstrap, jQuery, FontAwesome).

##### Architectural Patterns and Design Principles
- MVC Pattern: Both web applications (AdminSite and CustomerSite) clearly follow the Model-View-Controller pattern.
- Layered Architecture: The separation between presentation (web apps), services (business logic and API integrations), and data access (repository pattern using Entity Framework) is evident.
- API Integration: The design acknowledges external SaaS marketplace APIs (fulfillment and metering), which are key in managing subscriptions and billing.
- CI/CD and Automated Build: The GitHub Actions workflows indicate that there’s a continuous integration/continuous deployment pipeline integrated with the project.
- Extensibility: The modular organization (separate libraries, background jobs, and test projects) enables easy extension or customization to meet customer-specific requirements.

##### Adding Relevant Technologies
- Frameworks/Libraries: .NET 8, ASP.NET Core (for both portals), Entity Framework Core, Bootstrap, jQuery, and external marketplace API client libraries.
- External Services: Microsoft Commercial Marketplace (SaaS Fulfillment API and Marketplace Metering Service API) and Azure SQL Database.
- Development and Pipeline: Visual Studio (or VS Code), GitHub Actions for CI/CD, and PowerShell scripts for deployment tasks.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        AdminSite["Admin Portal (Publisher)"]
        CustomerSite["Customer Portal (Customer)"]
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        Services["Services Client Library"]
        MeteredTriggerJob["Background Job (MeteredTriggerJob)"]
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        DataAccess["Client Data Access Layer (DataAccess)"]
    end

    %% External APIs
    subgraph "External APIs"
        SaaSFulfillment["SaaS Fulfillment API"]
        MeteringService["Marketplace Metering API"]
    end

    %% Testing
    subgraph "Testing"
        ServicesTest["Unit Tests (Services.Test)"]
        UITest["UI Tests (UI.Test)"]
    end

    %% DevOps & Documentation
    subgraph "DevOps & Documentation"
        DeploymentScripts["Deployment Scripts (PowerShell)"]
        GitHubActions["CI/CD Workflows"]
        Docs["Supporting Documentation"]
    end

    %% Relationships
    AdminSite -->|"uses"| Services
    CustomerSite -->|"uses"| Services

    Services -->|"persistsTo"| DataAccess
    Services -->|"calls"| SaaSFulfillment
    Services -->|"calls"| MeteringService

    MeteredTriggerJob -->|"invokes"| MeteringService

    DeploymentScripts -->|"deploys"| AdminSite
    DeploymentScripts -->|"deploys"| CustomerSite
    GitHubActions -->|"runsTestsOn"| ServicesTest
    GitHubActions -->|"runsTestsOn"| UITest

    %% Styles
    classDef presentation fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef business fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef data fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef testing fill:#F6DDCC,stroke:#D68910,stroke-width:2px;
    classDef devops fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
    classDef docs fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;

    %% Assign classes
    class AdminSite,CustomerSite presentation;
    class Services,MeteredTriggerJob business;
    class DataAccess data;
    class SaaSFulfillment,MeteringService external;
    class ServicesTest,UITest testing;
    class DeploymentScripts,GitHubActions devops;
    class Docs docs;

    %% Click Events
    click AdminSite "https://github.com/azure/commercial-marketplace-saas-accelerator/tree/main/src/AdminSite"
    click CustomerSite "https://github.com/azure/commercial-marketplace-saas-accelerator/tree/main/src/CustomerSite"
    click DataAccess "https://github.com/azure/commercial-marketplace-saas-accelerator/tree/main/src/DataAccess"
    click Services "https://github.com/azure/commercial-marketplace-saas-accelerator/tree/main/src/Services"
    click MeteredTriggerJob "https://github.com/azure/commercial-marketplace-saas-accelerator/tree/main/src/MeteredTriggerJob"
    click ServicesTest "https://github.com/azure/commercial-marketplace-saas-accelerator/blob/main/src/Services.Test"
    click UITest "https://github.com/azure/commercial-marketplace-saas-accelerator/blob/main/src/UI.Test"
    click DeploymentScripts "https://github.com/azure/commercial-marketplace-saas-accelerator/tree/main/deployment"
    click GitHubActions "https://github.com/azure/commercial-marketplace-saas-accelerator/tree/main/.github/workflows"
    click Docs "https://github.com/azure/commercial-marketplace-saas-accelerator/tree/main/docs"
```
