1. System Overview

EGU Common API is a unified .NET 8 API gateway that implements the Bright Kit API specification. It provides a single, consistent interface to multiple utility billing and customer management backends using a multi-tenant adapter pattern.

Supported backends:

2. High-Level Architecture

                        ┌─────────────────────────────────────────────────────┐
                        │                    Bright App                        │
                        └─────────────────────┬───────────────────────────────┘
                                              │  HTTPS + JWT Bearer
                        ┌─────────────────────▼───────────────────────────────┐
                        │                 EGU Common API                       │
                        │                                                     │
                        │  ┌──────────────────────────────────────────────┐  │
                        │  │               API Layer (WebApp)             │  │
                        │  │                                              │  │
                        │  │  AccountsApi  BankIdApi  AuthApi  EventsApi  │  │
                        │  │  SystemApi    WebViewApi                     │  │
                        │  └──────────────────┬───────────────────────────┘  │
                        │                     │                               │
                        │  ┌──────────────────▼───────────────────────────┐  │
                        │  │           Orchestration Layer                │  │
                        │  │                                              │  │
                        │  │  AccountApiService    BankIdApiService       │  │
                        │  │  AuthenticationApiService  EventsApiService  │  │
                        │  └──────────┬─────────────────┬─────────────────┘  │
                        │             │                 │                     │
                        │  ┌──────────▼──────┐  ┌──────▼──────────────────┐  │
                        │  │ Shared Services │  │   Adapter Factory       │  │
                        │  │                 │  │                         │  │
                        │  │ InvoiceArchive  │  │  Resolves adapter by    │  │
                        │  │  - EDB          │  │  AdapterType from       │  │
                        │  │  - IData        │  │  SubscriptionSetting    │  │
                        │  │  - Stralfors    │  └──────────┬──────────────┘  │
                        │  │  - TietoEvry    │             │                  │
                        │  │  - Url          │  ┌──────────▼──────────────┐  │
                        │  │                 │  │      Adapter Layer      │  │
                        │  │ ZignSec BankID  │  │                         │  │
                        │  │  - V5 client    │◄─┤  CST  Xellent  Zynergy  │  │
                        │  │                 │  │  Gasell SonWin ProBill  │  │
                        │  └─────────────────┘  └──────────┬──────────────┘  │
                        │                                   │                 │
                        └───────────────────────────────────┼─────────────────┘
                                                            │
                        Backend Systems (External APIs)     │
                    ┌───────────┬──────────┬────────┴───┬──────────┬──────────────┐
                    │           │          │            │          │              │
              ┌─────▼────┐  ┌───▼────┐  ┌──▼──────┐  ┌─▼──────┐  ┌──▼──────┐  ┌──▼──────┐
              │ CST API  │  │Xellent │  │ Zynergy │  │ Gasell │  │ SonWin │  │ ProBill │
              │          │  │  API   │  │   API   │  │   API  │  │   API  │  │Bright AP│
              └──────────┘  └────────┘  └─────────┘  └────────┘  └────────┘  └─────────┘

3. Request Flow

1. Client sends request to:
   POST /subscriptions/{subscriptionId}/accounts/search

2. API endpoint (AccountsApi) receives the request
   └── extracts subscriptionId from route

3. AccountFactoryService is called
   └── ISubscriptionSettingService looks up the subscription
   └── reads AdapterType from configuration (e.g. AdapterType.CST)
   └── returns the matching IAccountAdapterService instance

4. Adapter executes the operation
   └── calls InternalServices for business logic
   └── InternalServices call ApiCallServices for HTTP communication
   └── maps backend response to standard Bright Kit DTO

5. Unified response returned to client

4. Layer Breakdown

Project Structure

EGU.CommonAPI.sln
├── src/
│   ├── App/
│   │   └── EGU.CommonAPI.WebApp          # ASP.NET Core Minimal API host
│   │       ├── Apis/                     # Endpoint definitions
│   │       └── Adapters/
│   │           ├── Factories/            # Adapter factory services
│   │           └── Services/             # Orchestration (API → adapter)
│   │
│   ├── Domain/
│   │   ├── EGU.CommonAPI.Domain.Contracts  # Interfaces, DTOs, enums, settings
│   │   ├── EGU.CommonAPI.Domain.Core       # Base classes, shared utilities
│   │   └── EGU.CommonAPI.Domain.InvoiceArchive  # Invoice PDF infrastructure
│   │
│   └── Adapters/
│       ├── EGU.CommonAPI.Adapters.CST
│       ├── EGU.CommonAPI.Adapters.Xellent
│       ├── EGU.CommonAPI.Adapters.Zynergy
│       ├── EGU.CommonAPI.Adapters.Gasell
│       ├── EGU.CommonAPI.Adapters.SonWin
│       └── EGU.CommonAPI.Adapters.ProBill
│
└── test/
    └── EGU.CommonAPI.UnitTests             # MSTest + NSubstitute

Each Adapter's Internal Structure

src/Adapters/{Adapter}/
├── AdapterServices/          # Implements IAccountAdapterService, etc.
├── InternalServices/
│   ├── AdapterServices/      # Business logic per operation
│   ├── ApiCallServices/      # HTTP calls to backend
│   └── CommonServices/       # Mappers, helpers, constants
└── Models/                   # Backend-specific DTOs

Adapter Interfaces (Domain.Contracts)

5. Multi-Tenancy & Subscription Routing

The system is multi-tenant via subscription configuration in appsettings.json:

{
  "Subscriptions": [
    {
      "SubscriptionId": "my-tenant-id",
      "AdapterType": "CST",
      "CstSetting": { ... }
    },
    {
      "SubscriptionId": "another-tenant",
      "AdapterType": "Xellent",
      "XellentSetting": { ... }
    }
  ]
}

Routing logic:

1. Every request path includes {subscriptionId}.
2. ISubscriptionSettingService resolves the settings record for that ID.
3. The factory (e.g. AccountFactoryService) selects the adapter whose AdapterType matches.
4. The selected adapter handles the request — callers never need to know which backend is used.

6. Public API Endpoints

All routes are prefixed with /subscriptions/{subscriptionId}.

Auth

Accounts

Users & Roles

Invoices

Measurements & Costs

Resolution options: month \| day \| hour \| 15min

Features

BankID

Events & System

7. Adapter Feature Matrix

✓ = Implemented ✓* = Implemented via shared base class ◐ = Partial/stub ✗ = NotImplementedException

Account Operations

BankID Operations

All BankID operations route through ZignSec (configurable API version per subscription, defaults to V5).

Events

¹ Zynergy and Gasell support SSN search only ² SonWin and ProBill support monthly, daily, hourly, and 15-minute (quarterly) resolution ³ SonWin's single-invoice lookup returns a minimal stub (account/invoice id + empty OCR), not real backend data † Invoice PDF is served via the shared InvoiceArchive infrastructure (EDB, IData, Stralfors, TietoEvry, or Url) configured per subscription

8. Authentication Methods

9. Backend API Endpoints

CST

Xellent

Gasell

ProBill 

SonWin 

Dates are sent as yyyy-MM-ddTHH:mm:ss using the UTC components of the value, with no Z suffix (SonWin's validator rejects a Z/offset-bearing value).