# bjarnef/umbraco.community.hotspots architecture

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

- Interactive diagram: https://gitdiagram.com/bjarnef/umbraco.community.hotspots
- Repository: https://github.com/bjarnef/umbraco.community.hotspots

## Overview

##### Project type and purpose
- This is an Umbraco v13+ package (plugin) called “Umbraco Community Hotspots.”
- Purpose: provide a “hotspot” property editor in the Umbraco backoffice and delivery API extensions so frontend consumers (Razor sites or headless consumers) can render hotspot-able images or areas.

##### File structure
- Top-level:
- src/Umbraco.Community.Hotspots.TestSite – a sample ASP.NET Core web app illustrating how the package is consumed in a Razor/Umbraco site.
- src/Umbraco.Community.Hotspots – the actual plugin project, containing:
– Converters (C# classes that map stored data to runtime types)
– Extensions (Delivery API image extensions)
– PropertyEditors (definition of custom editor configuration, value editor, UI assets)
– wwwroot/… – JavaScript controllers and HTML views for the backoffice editor UI
– HotspotsComposer & HotspotsManifestFilter – code to register the editor with Umbraco’s DI and client-side manifest.
- Config/build: .csproj files, GitHub workflows, NuGet packaging (umbraco-marketplace.json), docs folder for NuGet instructions.

##### README
- Confirms it’s a NuGet-distributed Umbraco package.
- Installation is via dotnet CLI into an existing Umbraco site.

a. Main components
1. Umbraco Core CMS (ASP.NET Core host, Umbraco services, backoffice API)
2. Hotspots Package (server-side library loaded at application start)
– Composers & Filters to register manifest assets
– Converters & Models for data handling
– Delivery API Extensions for headless/data consumption
3. Backoffice Editor UI (JavaScript controllers + HTML in wwwroot)
4. Sample/Test Website (ASP.NET Razor site showing render of hotspots)
5. Underlying Database (Umbraco’s SQL store)
6. External Delivery API clients (optional headless consumers)
b. Relationships & interactions
- At startup, HotspotsComposer hooks into Umbraco’s startup pipeline → registers property editor manifest via HotspotsManifestFilter → backoffice loads JS controllers and HTML.
- Author uses backoffice UI to configure hotspots on images → data saved to Umbraco DB with custom data type (converter transforms stored JSON into .NET object).
- Razor website (TestSite) requests content via Umbraco Content Delivery API → DeliveryApiImageExtensions inject hotspot metadata into API response.
- Frontend rendering (Razor/JS) reads hotspot metadata and renders interactive image areas.
c. Architectural patterns/design principles
- Umbraco “Composer + Component” registration pattern
- Separation of concerns:
– UI assets served via manifest filter
– Data conversion in Converters
– Delivery API augmentation in Extensions
- Plugin packaged as NuGet for easy distribution
d. Key technologies/frameworks
- ASP.NET Core (Minimal host in TestSite/Umbraco host in target site)
- Umbraco CMS v13+
- JavaScript controllers (AngularJS-style backoffice)
- Razor views for sample site
- JSON-based property editor manifest

##### Capturing essential architectural elements
- Plugin registration pipeline (Composer, ManifestFilter)
- Data conversion layer
- Editor UI injection
- Delivery API augmentation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Umbraco Core
    subgraph "Umbraco CMS Host"
        direction TB
        UmbracoHost["Umbraco Host (ASP.NET Core)"]:::core
        BackofficeAPI["Backoffice API"]:::core
        DeliveryAPI["Content Delivery API"]:::core
    end

    %% Hotspots Plugin (Server-side Library)
    subgraph "Hotspots Plugin" 
        direction TB
        HotspotsCsproj["Hotspots Package (.csproj)"]:::plugin
        Composer["HotspotsComposer"]:::plugin
        ManifestFilter["HotspotsManifestFilter"]:::plugin
        subgraph "Data Layer"
            direction TB
            Converter["HotspotValueConverter"]:::plugin
            ApiModel["ApiHotspotValue"]:::plugin
        end
        Extensions["DeliveryApiImageExtensions"]:::plugin
        subgraph "Property Editors"
            direction TB
            ConfigModel["HotspotConfiguration"]:::plugin
            ConfigEditor["HotspotConfigurationEditor"]:::plugin
            PropertyEditor["HotspotPropertyEditor"]:::plugin
            ValueEditor["HotspotPropertyValueEditor"]:::plugin
        end
    end

    %% Backoffice UI
    subgraph "Backoffice UI Assets"
        direction TB
        UIController["hotspot.controller.js"]:::ui
        UIView["hotspot.html"]:::ui
        StaticCtrl["static-image.controller.js"]:::ui
        StaticView["static-image.html"]:::ui
        Localization["en.xml"]:::ui
    end

    %% Database and External Clients
    UmbracoDB["Umbraco SQL Database"]:::external
    HeadlessClient["External Headless Client"]:::external

    %% TestSite Sample
    subgraph "TestSite (Razor Umbraco Host)"
        direction TB
        TestCsproj["TestSite .csproj"]:::core
        TestStartup["Startup & Program"]:::core
        RazorPartials["Razor Partials"]:::core
    end

    %% Interactions
    UmbracoHost -->|uses| Composer
    Composer -->|registers| ManifestFilter
    ManifestFilter -->|serves UI assets| UIController
    UIController --> UIView
    StaticCtrl --> StaticView
    UIView -.->|localization| Localization

    UIController -->|Backoffice API calls| BackofficeAPI
    BackofficeAPI -->|save/load| UmbracoDB
    Converter -->|converts JSON to .NET| BackofficeAPI
    PropertyEditor -->|uses| Converter
    ConfigEditor -->|configures| PropertyEditor
    ConfigModel -->|defines| PropertyEditor
    ValueEditor -->|formats value| PropertyEditor

    DeliveryAPI -->|augmented by| Extensions
    Extensions -->|injects hotspot metadata| DeliveryAPI
    ApiModel -->|model for| Extensions

    TestCsproj -->|configures| TestStartup
    TestStartup -->|calls Delivery API| DeliveryAPI
    RazorPartials -->|renders| ApiModel

    HeadlessClient -->|calls| DeliveryAPI

    %% Click Events
    click HotspotsCsproj "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/Umbraco.Community.Hotspots.csproj"
    click Composer "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/HotspotsComposer.cs"
    click ManifestFilter "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/HotspotsManifestFilter.cs"
    click Converter "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/Converters/HotspotValueConverter.cs"
    click ApiModel "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/Models/DeliveryApi/ApiHotspotValue.cs"
    click Extensions "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/Extensions/DeliveryApiImageExtensions.cs"
    click ConfigModel "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/PropertyEditors/HotspotConfiguration.cs"
    click ConfigEditor "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/PropertyEditors/HotspotConfigurationEditor.cs"
    click PropertyEditor "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/PropertyEditors/HotspotPropertyEditor.cs"
    click ValueEditor "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/PropertyEditors/HotspotPropertyValueEditor.cs"
    click UIController "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/wwwroot/Umbraco.Community.Hotspots/hotspot.controller.js"
    click UIView "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/wwwroot/Umbraco.Community.Hotspots/hotspot.html"
    click StaticCtrl "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/wwwroot/Umbraco.Community.Hotspots/static-image.controller.js"
    click StaticView "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/wwwroot/Umbraco.Community.Hotspots/static-image.html"
    click Localization "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots/wwwroot/Umbraco.Community.Hotspots/lang/en.xml"
    click TestCsproj "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots.TestSite/Umbraco.Community.Hotspots.TestSite.csproj"
    click TestStartup "https://github.com/bjarnef/umbraco.community.hotspots/blob/main/src/Umbraco.Community.Hotspots.TestSite/Startup.cs"
    click RazorPartials "https://github.com/bjarnef/umbraco.community.hotspots/tree/main/src/Umbraco.Community.Hotspots.TestSite/Views/Partials/"

    %% Styles
    classDef core fill:#ccffcc,stroke:#006600,color:#003300
    classDef plugin fill:#cce5ff,stroke:#0059b3,color:#003366
    classDef ui fill:#ffe6cc,stroke:#cc6600,color:#663300
    classDef external fill:#f2f2f2,stroke:#808080,color:#404040
```
