# azure/api-management-developer-portal architecture

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

- Interactive diagram: https://gitdiagram.com/azure/api-management-developer-portal
- Repository: https://github.com/azure/api-management-developer-portal

## Overview

##### Project type and purpose
- This is a full-stack, client-heavy, self-hosted “developer portal” for Azure API Management (APIM).
- It provides an admin/design UI, a runtime SPA for API consumers, and a publishing pipeline to push content to the APIM service.

##### File structure
- Top-level folders:
- src/ – portal front-end code (TypeScript, React, Knockout.js, CSS/SCSS)
- auth/, authentication/ – Azure AD/B2C auth logic
- clients/, services/ – MAPI (management API) clients and business logic
- persistence/ – blob/object storage abstractions
- publishing/ – build/publish plugins that package and push static assets and configuration
- themes/, styles/ – design assets for portal and website
- scripts.v2/, scripts.v3/ – CLI tooling for generation, deployment, media management
- .github/workflows/, .pipeline/ – CI/CD definitions
- Widget-based architecture: each component (APIs lists, operations, users, reports, etc.) has design.publish.runtime modules, model-binder, handlers, and both Knockout and React runtime implementations.
- Heavy use of webpack configs for multiple targets (designer UI, runtime UI, publisher, static data mocks).

##### Insights from README
- Purpose: a managed or self-hosted portal that ships daily from master (unstable) and official releases.
- It relies on Azure APIM service REST APIs and supports customization by community widgets.

- Browser/Client UI
– Designer/Admin SPA (React/TSX + Knockout bindings for widget editors)
– Runtime SPA (widget modules for API consumers)
- CI/CD & Publishing Pipeline
– GitHub Actions / .pipeline scripts
– scripts.v2 / scripts.v3 CLI tools
- Portal Backend APIs (no custom server in repo)
– Azure API Management MAPI REST endpoints (management API)
– Azure AD / B2C OAuth2/OIDC endpoints
- Storage & Configuration
– Azure Blob Storage for media and static assets
– APIM internal storage for portal configuration
- Telemetry & Logging
– Azure Application Insights via appInsightsLogger
b. Relationships & interactions:
1. Developer/admin uses Designer SPA → communicates to Publishing pipeline (via scripts or GitHub Actions) → pushes JSON config, widgets, and static assets to APIM management API.
2. End user loads Runtime SPA (hosted in Azure blob/CDN or from APIM) → SPA calls MAPI REST to fetch API definitions, operations, products, user profiles.
3. SPA invokes Azure AD B2C for sign-in/up flows → receives OAuth tokens → passes to MAPI client for authenticated calls.
4. SPA assets are versioned/bundled by webpack and published via pipeline to blob storage or directly to APIM.
5. Telemetry events from SPA are sent to Application Insights.
c. Architectural patterns & design principles:
- Widget-based modularity: each feature is a self-contained design/publish/runtime module.
- MVVM: Knockout.js view models + model binders.
- Progressive enhancement: both Knockout and React runtimes co-exist.
- CI/CD as code: GitHub Actions and build scripts.
- Abstraction layers: clients/services, persistence providers, authentication providers allow pluggability.
d. Key technologies/frameworks:
– TypeScript + ES modules
– React + Knockout.js
– Webpack multi-target configs
– Azure API Management REST (MAPI)
– Azure AD / B2C OAuth2/OIDC
– Azure Blob Storage
– GitHub Actions / Azure Pipelines
– Application Insights SDK

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Client/UI Layer
  subgraph "Client/UI Layer"
    direction TB
    AdminUI["Browser SPA (Designer/Admin)"]:::client
    RuntimeSPA["Browser SPA (Runtime/API Consumer)"]:::client
    Widgets["Widget Modules"]:::client
  end

  %% Publishing Pipeline
  subgraph "Publishing Pipeline"
    direction TB
    CLITools["CLI Tools (scripts.v2 & scripts.v3)"]:::pipeline
    PublishPlugins["Publish Plugins"]:::pipeline
    CI_CD["CI/CD Definitions"]:::pipeline
    WebpackConfigs["Webpack Multi-target Configs"]:::pipeline
  end

  %% Backend Services
  subgraph "Azure Services & APIs"
    direction TB
    APIM["Azure API Management REST API"]:::external
    OAuth["Azure AD/B2C OAuth2/OIDC Endpoints"]:::external
  end

  %% Storage & Telemetry
  subgraph "Storage & Telemetry"
    direction TB
    BlobStorage["Azure Blob Storage"]:::storage
    AppInsights["Application Insights"]:::storage
  end

  %% Supporting Components
  subgraph "Core Modules"
    direction TB
    LegacyAuth["Legacy ARM Auth"]:::external
    AuthClient["Auth Client Code"]:::client
    MAPIClient["Low-level MAPI Client"]:::client
    MAPIService["High-level MAPI Service"]:::client
    Persistence["Persistence Abstractions"]:::storage
    AppInsightsLogger["App Insights Logger"]:::storage
    TelemetryConfig["Telemetry Config"]:::storage
    ConfigProviders["Configuration Providers"]:::client
    Routing["SPA Routing & Guards"]:::client
    ServicesBL["Business Logic Services"]:::client
    DataContracts["Data Contracts"]:::client
    DomainModels["Domain Models"]:::client
    Mocks["Static Data & Mocks"]:::client
    MockBuild["Mock Build Target"]:::pipeline
    ThemesDesigner["Designer Portal Theme"]:::client
    ThemesWebsite["Website Theme"]:::client
    SharedStyles["Shared Styles"]:::client
  end

  %% Connections
  AdminUI -->|"build & publish"| CLITools
  PublishPlugins -->|packages assets| APIM
  CLITools -->|invoked by| CI_CD
  CI_CD -->|runs webpack| WebpackConfigs
  WebpackConfigs -->|bundles| PublishPlugins
  CI_CD -->|deploys assets| BlobStorage
  RuntimeSPA -->|"fetch definitions"| APIM
  RuntimeSPA -->|"sign-in flow"| OAuth
  OAuth -->|issues tokens| RuntimeSPA
  RuntimeSPA -->|"use tokens"| APIM
  RuntimeSPA -->|"send telemetry"| AppInsights
  RuntimeSPA -->|"loads widgets"| Widgets
  AdminUI -->|uses| MAPIService
  MAPIService -->|calls| MAPIClient
  RuntimeSPA -->|uses| AuthClient
  AuthClient -->|fallback| LegacyAuth
  MAPIService -->|persists data| Persistence
  Persistence -->|stores assets| BlobStorage
  AppInsightsLogger -->|reports to| AppInsights
  RuntimeSPA -->|config from| ConfigProviders
  RuntimeSPA -->|routing via| Routing
  AdminUI -->|logic via| ServicesBL
  RuntimeSPA -->|logic via| ServicesBL
  AdminUI -->|types via| DataContracts
  RuntimeSPA -->|models via| DomainModels
  AdminUI -->|mock dev| Mocks
  WebpackConfigs -->|mock target| MockBuild
  AdminUI -->|styling| ThemesDesigner
  RuntimeSPA -->|styling| ThemesWebsite
  AdminUI -->|styles| SharedStyles
  RuntimeSPA -->|styles| SharedStyles

  %% Click Events
  click AdminUI "https://github.com/azure/api-management-developer-portal/tree/master/src/admin"
  click RuntimeSPA "https://github.com/azure/api-management-developer-portal/blob/master/src/startup.runtime.ts"
  click Widgets "https://github.com/azure/api-management-developer-portal/tree/master/src/components"
  click CLITools "https://github.com/azure/api-management-developer-portal/tree/master/scripts.v2/"
  click CLITools "https://github.com/azure/api-management-developer-portal/tree/master/scripts.v3/"
  click PublishPlugins "https://github.com/azure/api-management-developer-portal/tree/master/src/publishing"
  click CI_CD "https://github.com/azure/api-management-developer-portal/tree/master/.github/workflows/"
  click CI_CD "https://github.com/azure/api-management-developer-portal/tree/master/.pipeline/"
  click WebpackConfigs "https://github.com/azure/api-management-developer-portal/blob/master/webpack.*.js"
  click LegacyAuth "https://github.com/azure/api-management-developer-portal/blob/master/auth/arm-auth.js"
  click AuthClient "https://github.com/azure/api-management-developer-portal/tree/master/src/authentication/"
  click MAPIClient "https://github.com/azure/api-management-developer-portal/tree/master/src/clients/"
  click MAPIService "https://github.com/azure/api-management-developer-portal/blob/master/src/services/mapiClient.ts"
  click Persistence "https://github.com/azure/api-management-developer-portal/tree/master/src/persistence/"
  click AppInsightsLogger "https://github.com/azure/api-management-developer-portal/blob/master/src/logging/appInsightsLogger.ts"
  click TelemetryConfig "https://github.com/azure/api-management-developer-portal/tree/master/src/telemetry/"
  click ConfigProviders "https://github.com/azure/api-management-developer-portal/tree/master/src/configuration/"
  click Routing "https://github.com/azure/api-management-developer-portal/tree/master/src/routing/"
  click ServicesBL "https://github.com/azure/api-management-developer-portal/tree/master/src/services/"
  click DataContracts "https://github.com/azure/api-management-developer-portal/tree/master/src/contracts/"
  click DomainModels "https://github.com/azure/api-management-developer-portal/tree/master/src/models/"
  click Mocks "https://github.com/azure/api-management-developer-portal/tree/master/tests/mocks/"
  click MockBuild "https://github.com/azure/api-management-developer-portal/blob/master/webpack.mockStaticData.js"
  click ThemesDesigner "https://github.com/azure/api-management-developer-portal/tree/master/src/themes/designer/"
  click ThemesWebsite "https://github.com/azure/api-management-developer-portal/tree/master/src/themes/website/"
  click SharedStyles "https://github.com/azure/api-management-developer-portal/tree/master/src/styles/"

  %% Styles
  classDef client fill:#D0E8FF,stroke:#343434,stroke-width:1px
  classDef pipeline fill:#D5E8D4,stroke:#343434,stroke-width:1px
  classDef external fill:#F8CECC,stroke:#343434,stroke-width:1px
  classDef storage fill:#E8E8E8,stroke:#343434,stroke-width:1px
```
