# powerbidevcamp/app-owns-data-starter-kit architecture

> Architecture diagram of the GitHub repository powerbidevcamp/app-owns-data-starter-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/powerbidevcamp/app-owns-data-starter-kit
- Repository: https://github.com/powerbidevcamp/app-owns-data-starter-kit

## Overview

##### Project type and purpose
- This is a multi-project full-stack starter kit for App-Owns-Data embedding with Power BI.
- It includes four web applications, a shared class library, a SQL Server database, integration with Azure AD for identity, and calls to the Power BI Service API.
- The purpose is to demonstrate best practices for multi-tenant embedding, workspace provisioning, user authorization, and custom telemetry.

##### File-structure overview
- Top-level solution: AppOwnsDataStarterKit.sln
- Five projects under solution:
- AppOwnsDataAdmin (ASP.NET MVC)
- AppOwnsDataWebApi (ASP.NET Core Web API)
- AppOwnsDataClient (jQuery/Bootstrap SPA)
- AppOwnsDataReactClient (React-JS/Material-UI SPA)
- AppOwnsDataShared (Class library with EF Core models & services)
- Shared:
- Database migrations under AppOwnsDataShared/Migrations
- Client apps each have TS/webpack configs, libman or npm package files, and generated bundle.js in wwwroot.
- Admin and WebApi have appsettings.json for AzureAD, PowerBI, and DB.
- External templates under Admin/wwwroot/PBIX and AppOwsDataUsageReporting.pbix at the solution root.

##### Key README insights
- Solution architecture uses:
- A custom SQL database (AppOwnsDataDB) via EF Core Code-First in Shared library.
- AppOwnsDataAdmin: provisions tenants (creates Power BI workspaces, imports PBIX/RDL templates, patches parameters & credentials, refreshes datasets) using service-principal profiles.
- AppOwnsDataWebApi: backend for client SPAs, generates Power BI embed tokens (Client Credentials Flow, service principal), enforces per-user authorization by querying AppOwnsDataDB for permissions, and logs telemetry.
- AppOwnsDataClient & AppOwnsDataReactClient: two SPA implementations that authenticate users via Azure AD (MSAL.js), call WebAPI endpoints, receive embed tokens, and embed Power BI reports (view/edit/create).
- Custom telemetry: SPAs call WebAPI ActivityLog endpoint; WebAPI logs events in DB; AppOwsDataUsageReporting.pbix analyzes usage/performance.

##### Components
- Server-side components (hosted on IIS/Azure App Services):
- AppOwnsDataAdmin (ASP.NET MVC)
- AppOwnsDataWebApi (ASP.NET Core Web API)
- AppOwnsDataShared (Class Library, EF Core)
- AppOwnsDataDB (SQL Server)
- Client-side components (user’s browser):
- AppOwnsDataClient SPA (jQuery/TypeScript)
- AppOwnsDataReactClient SPA (React-JS/TypeScript)
- Power BI JavaScript Client Library
- External services:
- Azure AD (Identity Provider)
- Power BI Service API (embedding, workspace & report management)
- (Optional) Dedicated Power BI Capacity (P or A SKUs)

##### Relationships and data flows
- Client SPA → Azure AD: user authentication (acquire access token for WebAPI).
- Client SPA → AppOwnsDataWebApi: call /UserLogin, /Embed, /ActivityLog endpoints, passing access token.
- AppOwnsDataWebApi → Azure AD: Client Credentials Flow to get app-only token (to call Power BI REST).
- AppOwnsDataWebApi → AppOwnsDataDB via AppOwnsDataShared → store/retrieve Tenants, Users, ActivityLog.
- AppOwnsDataWebApi → Power BI Service REST API: generate embed token, import RDL, etc.
- AppOwnsDataAdmin → Azure AD: authentication for admin users, then uses service principal profiles via Power BI REST API to provision tenants.
- AppOwnsDataAdmin → AppOwnsDataDB: record tenants and service principal profile IDs.
- AppOwnsDataAdmin → Power BI Service: create workspaces, import PBIX/RDL, set params, refresh.
- AppOwnsDataClient/ReactClient → Power BI JavaScript API: client-side embed using embed token received from WebAPI.

##### Architectural patterns & principles
- Layered architecture:
- UI (SPAs)
- API layer (AppOwnsDataWebApi)
- Business/data layer (AppOwnsDataShared + EF Core + SQL DB)
- External integration layer (Power BI REST, Azure AD)
- Shared library for reuse (AppOwnsDataShared)
- Separation of concerns: admin vs. user workloads
- Secure token flows: OAuth2 Client Credentials for backend, MSAL.js for front-end.
- Multi-tenant isolation via service-principal profiles.

##### Essential elements
- Components: AppOwnsDataAdmin, AppOwnsDataWebApi, AppOwnsDataClient, AppOwnsDataReactClient, AppOwnsDataShared, AppOwnsDataDB, Azure AD, Power BI Service, Dedicated Capacity
- Flows:
- User → SPA → WebAPI → DB & Power BI
- SPA → Azure AD (login)
- Admin App → WebAPI & Power BI provisioning

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client-side
    subgraph "Client-side (Browser)"
        direction TB
        SPA1["AppOwnsDataClient SPA"]:::client
        SPA2["AppOwnsDataReactClient SPA"]:::client
        PBI_JS["Power BI JS Client Library"]:::client
    end

    %% Server-side
    subgraph "Server-side (IIS/Azure App Services)"
        direction TB
        ADMIN["AppOwnsDataAdmin"]:::server
        WEBAPI["AppOwnsDataWebApi"]:::server
        SHARED["AppOwnsDataShared Library"]:::server
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB["AppOwnsDataDB (SQL Server)"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AAD["Azure AD"]:::external
        PBI_SERVICE["Power BI Service API"]:::external
        CAPACITY["Dedicated Power BI Capacity"]:::external
    end

    %% Client flows
    SPA1 -->|"MSAL.js login\nAcquire AAD token"| AAD
    SPA2 -->|"MSAL.js login\nAcquire AAD token"| AAD
    SPA1 -->|"Call WebAPI endpoints\n/UserLogin,/Embed,/ActivityLog"| WEBAPI
    SPA2 -->|"Call WebAPI endpoints\n/UserLogin,/Embed,/ActivityLog"| WEBAPI
    SPA1 -->|"Embed via JS API"| PBI_JS
    SPA2 -->|"Embed via JS API"| PBI_JS

    %% WebAPI flows
    WEBAPI -->|"OAuth2 Client Credentials\nAcquire app-only token"| AAD
    WEBAPI -->|"Generate embed token\nImport RDL, etc"| PBI_SERVICE
    WEBAPI -->|"Use EF Core\nGet/Update Tenants, Users, ActivityLog"| SHARED
    SHARED -->|"EF Core Code-First\nSQL queries"| DB

    %% Admin flows
    ADMIN -->|"User login & admin auth"| AAD
    ADMIN -->|"Provision tenants\nImport PBIX/RDL\nSet params\nRefresh"| PBI_SERVICE
    ADMIN -->|"Record tenants & profiles"| SHARED

    %% Power BI capacity
    PBI_SERVICE -->|"Optional dedicated capacity"| CAPACITY

    %% Click Events
    click ADMIN "https://github.com/powerbidevcamp/app-owns-data-starter-kit/tree/main/AppOwnsDataAdmin/"
    click WEBAPI "https://github.com/powerbidevcamp/app-owns-data-starter-kit/tree/main/AppOwnsDataWebApi/"
    click SHARED "https://github.com/powerbidevcamp/app-owns-data-starter-kit/tree/main/AppOwnsDataShared/"
    click DB "https://github.com/powerbidevcamp/app-owns-data-starter-kit/blob/main/AppOwnsDataShared/Models/AppOwnsDataDB.cs"
    click SPA1 "https://github.com/powerbidevcamp/app-owns-data-starter-kit/tree/main/AppOwnsDataClient/"
    click SPA2 "https://github.com/powerbidevcamp/app-owns-data-starter-kit/tree/main/AppOwnsDataReactClient/"
    click PBI_JS "https://github.com/powerbidevcamp/app-owns-data-starter-kit/tree/main/AppOwnsDataClient/wwwroot/lib/powerbi-client/"

    %% Styles
    classDef server fill:#DAE8FC,stroke:#6C8EBF;
    classDef client fill:#E1F5FE,stroke:#0277BD;
    classDef db fill:#FFE0B2,stroke:#FB8C00;
    classDef external fill:#E2F4C9,stroke:#82B366;
```
