# ukho/erp-facade architecture

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

- Interactive diagram: https://gitdiagram.com/ukho/erp-facade
- Repository: https://github.com/ukho/erp-facade

## Overview

##### Project Type and Purpose
- Type: Cloud‐hosted, event‐driven middleware/Webhook service with batch-oriented JSON→SOAP translation.
- Purpose: Subscribe to ENC Publishing events (CloudEvents) from the Enterprise Event Service (EES), transform relevant data, and call SAP’s inbound SOAP web service. Additional background tasks (aggregation, cleanup) run as Azure WebJobs.

##### Top-Level Components
- External Systems
– Enterprise Event Service (EES) – emits uk.gov.ukho.encpublishing.enccontentpublished.v2.1 events.
– SAP Inbound SOAP Web Service – on-prem or mock (UKHO.SAP.MockAPIService).
- Azure Infrastructure (provisioned via Terraform under Deployment/Modules)
– App Service (WebApp) hosting the API and WebJobs
– Storage Account (Tables, Queues, Blob)
– Key Vault (secrets: SAP endpoint, AAD, Storage keys)
– Event Hub & Application Insights (logging/telemetry)
- Runtime Components (in src/)
– UKHO.ERPFacade.API – ASP.NET Core Web API
– UKHO.ERPFacade.CleanUp.WebJob – scheduled cleanup of old events/records
– UKHO.ERPFacade.EventAggregation.WebJob – scheduled aggregation of Record-Of-Sale events into SAP batches
– UKHO.SAP.MockAPIService – local/mock SOAP endpoints for testing
– UKHO.ERPFacade.Common – shared code for configuration, HTTP clients, Azure IO, decryption, health checks
- Testing & Support
– Functional and Unit Tests under tests/
– Postman Collections (tests/ERP Facade.postman_collection.json)
– Performance Script (load tests simulating webhooks)
– Deployment pipelines & Terraform templates in Deployment/templates and azure-pipelines.yml

##### Architectural Patterns & Principles
- Event‐Driven: decoupled ingestion (EES) → processing → outbound SOAP
- Separation of Concerns: Web API vs WebJobs vs Common library
- Dependency Injection: all HTTP clients, storage helpers, message builders registered in Program.cs
- Resilience & Logging: middleware, retries in HttpClients, Application Insights
- IaC: Terraform modules for each Azure resource

##### Technologies & Frameworks
- .NET 6 (likely) Web API & WebJobs
- Azure Storage (Tables, Queues, Blob) via Azure SDK
- Azure Key Vault for secrets
- Terraform for provisioning (Deployment/Modules/*)
- xUnit/MSTest for Unit/Functional tests
- Postman & custom JS load scripts for performance testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems Left
    subgraph "External Systems" 
        direction TB
        EES["Enterprise Event Service\n(CloudEvents)"]:::external
    end

    %% Azure Resource Group Center
    subgraph "Azure Resource Group"
        direction TB
        subgraph "App Service (WebApp)" 
            direction TB
            API["ERPFacade API\n(Webhook)"]:::app
            Cleanup["CleanUp WebJob\n(Timer)"]:::app
            Aggregation["EventAggregation WebJob\n(Timer)"]:::app
        end
        subgraph "Storage Account" 
            direction TB
            Table["Azure Table"]:::storage
            Queue["Azure Queue"]:::storage
            Blob["Azure Blob"]:::storage
        end
        KeyVault["Key Vault"]:::storage
        EventHub["Event Hub"]:::azure
        AppInsights["App Insights"]:::azure
        subgraph "IaC (Terraform Modules)" 
            direction TB
            WebappModule["WebApp Module"]:::iact
            StorageModule["Storage Module"]:::iact
            KeyVaultModule["KeyVault Module"]:::iact
            EventHubModule["EventHub Module"]:::iact
            AppInsightsModule["AppInsights Module"]:::iact
            PipelinesTemplates["CI/CD & Testing Templates"]:::iact
        end
    end

    %% External Systems Right
    subgraph "External Systems" 
        direction TB
        SAP["SAP Inbound SOAP\nWeb Service"]:::external
    end

    %% Testing & Support Bottom
    subgraph "Testing & Support"
        direction TB
        Postman["Postman Collections"]:::support
        Perf["Performance Scripts"]:::support
        Pipelines["Azure Pipelines & IaC Templates"]:::support
    end

    %% Data Flows
    EES -->|HTTP POST /webhook| API
    API -->|"Writes trace"| Table
    API -->|"Enqueues if needed"| Queue
    API -->|"Stores payload"| Blob
    API -->|"SOAP 1.2"| SAP
    Cleanup -->|"Timer Trigger"| Table
    Cleanup -->|"Timer Trigger"| Queue
    Cleanup -->|"Timer Trigger"| Blob
    Aggregation -->|"Timer Trigger\naggregate & SOAP"| SAP
    API -->|logs & metrics| EventHub
    Cleanup -->|logs & metrics| AppInsights
    Aggregation -->|logs & metrics| AppInsights

    %% Click Events for Code Components
    click API "https://github.com/ukho/erp-facade/blob/main/src/UKHO.ERPFacade.API"
    click Cleanup "https://github.com/ukho/erp-facade/blob/main/src/UKHO.ERPFacade.CleanUp.WebJob"
    click Aggregation "https://github.com/ukho/erp-facade/blob/main/src/UKHO.ERPFacade.EventAggregation.WebJob"
    click WebappModule "https://github.com/ukho/erp-facade/tree/main/Deployment/Modules/Webapp"
    click StorageModule "https://github.com/ukho/erp-facade/tree/main/Deployment/Modules/Storage"
    click KeyVaultModule "https://github.com/ukho/erp-facade/tree/main/Deployment/Modules/KeyVault"
    click EventHubModule "https://github.com/ukho/erp-facade/tree/main/Deployment/Modules/EventHub"
    click AppInsightsModule "https://github.com/ukho/erp-facade/tree/main/Deployment/Modules/AppInsights"
    click PipelinesTemplates "https://github.com/ukho/erp-facade/blob/main/Deployment/templates/continuous-deployment.yml"
    click Postman "https://github.com/ukho/erp-facade/blob/main/Postman Scripts/ERP Facade.postman_collection.json"
    click Perf "https://github.com/ukho/erp-facade/blob/main/Performance Script/WebhookLoadTest.js"
    click Pipelines "https://github.com/ukho/erp-facade/blob/main/azure-pipelines.yml"

    %% Styles
    classDef external fill:#dddddd,stroke:#333,stroke-width:1px
    classDef azure fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef app fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef storage fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef iact fill:#b2dfdb,stroke:#333,stroke-width:1px
    classDef support fill:#fff9c4,stroke:#333,stroke-width:1px
```
