# microsoft/semantic-link-labs architecture

> Architecture diagram of the GitHub repository microsoft/semantic-link-labs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/semantic-link-labs
- Repository: https://github.com/microsoft/semantic-link-labs

## Overview

The Semantic Link Labs project is a Python library built to extend and automate many tasks related to managing semantic models and Power BI (and now Fabric) environments. Its purpose is to provide a rich set of functionalities (such as model migration, best practice analysis, report handling, and more) that integrate with Microsoft Fabric notebooks, Direct Lake migration, Power BI, Azure, and Microsoft Graph APIs.

##### Main Components
- Core Library (sempy_labs): This is the heart of the project and contains all the submodules which are organized into multiple domains:
- Semantic Model Management (e.g., modules related to model BPA, translations, auto-generation, refresh, etc.)
- Migration & Direct Lake Components (e.g., migration, directlake, lakehouse subpackages)
- Administration & Configuration (e.g., admin subpackage for managing capacities, users, and workspaces)
- Analytics & Reporting (e.g., report subpackage that handles BPA reporting, export, rebind, etc.)
- Tabular Object Model (TOM) tools for advanced model interactions
- Utilities such as authentication, helper functions, and various API wrappers (Graph, Power BI, Fabric, Azure)
- Notebooks and Documentation: The notebooks folder provides helper notebooks (for migration, analysis, administration) that are used to demonstrate the library’s functionalities. The docs folder holds extended documentation with configuration for generating documentation via ReadTheDocs.
- CI/CD and Development Tools: The top-level folders (.github, pyproject.toml, environment.yml, tests) capture continuous integration, build configurations, and testing setups.

##### Component Relationships and Interactions
- Library API Layer: Represent the sempy_labs package as the core API. Inside it, show several submodules (for example, “_ai”, “_authentication”, “_bpa_translation”, “_dashboards”, “_migration”, “_directlake”, “_lakehouse”, “_report”, “_tom”, etc.). Position these as modules that encapsulate distinct functionalities.
- External Service Integrations: From these modules, show connections to:
– Microsoft Graph APIs (via the graph subpackage)
– Power BI / Fabric API endpoints (through the API wrappers integrated into several modules)
– Azure Services and Dataflows / Delta Lake for migration and Direct Lake operations
– External Data Sources or data storage (e.g., OneLake, Fabric lakehouse)
- CI/CD and Testing: Include a separate component that shows integration with Github Actions (via the .github/workflows folder), testing (tests folder), and documentation generation (docs folder and .readthedocs.yaml).

##### Architectural Patterns and Design Principles
- Modularity: Stress how each domain (e.g., migration, reports, directlake) is implemented as a separate module within the library to promote separation of concerns.
- Wrapper / Facade design: Many modules encapsulate complex interactions with external APIs, exposing a simplified interface.
- Extensibility: The library supports various external integrations and enables extension via new modules or notebooks.
- CI/CD Pipeline: The presence of workflows for building, code analysis (e.g., CodeQL) and automated testing indicates an overall emphasis on continuous integration.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top-level Components
    Notebooks["Fabric / Jupyter Notebooks"]:::notebooks
    Notebooks --> CoreLib["Core Library (sempy_labs)"]:::core

    %% Core Library Submodules
    subgraph "Core Library Modules"
        ModelBPA["Semantic Model: _model_bpa"]:::module
        Translations["Semantic Model: _translations"]:::module
        BPA_Translation["Semantic Model: _bpa_translation"]:::module
        Migration["Migration"]:::module
        DirectLake["Direct Lake"]:::module
        Admin["Administration"]:::module
        Reporting["Reporting"]:::module
        TOM["TOM Tools"]:::module
        Auth["Authentication"]:::module
        GraphQL["GraphQL"]:::module
        HelperFunctions["Helper Functions"]:::module
    end

    %% Linking CoreLib with its Modules
    CoreLib --> ModelBPA
    CoreLib --> Translations
    CoreLib --> BPA_Translation
    CoreLib --> Migration
    CoreLib --> DirectLake
    CoreLib --> Admin
    CoreLib --> Reporting
    CoreLib --> TOM
    CoreLib --> Auth
    CoreLib --> GraphQL
    CoreLib --> HelperFunctions

    %% External Services/APIs
    GraphAPI["Microsoft Graph API"]:::external
    PowerBI["Power BI/Fabric API"]:::external
    AzureDS["Azure Services/Dataflows"]:::external

    %% Module to External API Interactions
    ModelBPA -->|"calls"| PowerBI
    Translations -->|"calls"| PowerBI
    BPA_Translation -->|"calls"| PowerBI
    Migration -->|"calls"| AzureDS
    DirectLake -->|"integrates"| AzureDS
    Admin -->|"calls"| GraphAPI
    Reporting -->|"calls"| PowerBI
    Auth -->|"calls"| GraphAPI
    GraphQL -->|"calls"| GraphAPI

    %% CI/CD & Documentation Components
    CI_CD["CI/CD Workflows"]:::cicd
    Tests["Testing"]:::cicd
    Docs["Documentation"]:::cicd
    ReadTheDocs["ReadTheDocs Config"]:::cicd
    PyProject["PyProject.toml"]:::cicd
    EnvYML["environment.yml"]:::cicd

    %% Linking Core Library with CI/CD and Docs
    CoreLib --> CI_CD
    CoreLib --> Tests
    CoreLib --> Docs
    CoreLib --> ReadTheDocs
    CoreLib --> PyProject
    CoreLib --> EnvYML

    %% Styles
    classDef notebooks fill:#f1c232,stroke:#333,stroke-width:2px;
    classDef core fill:#abd1c6,stroke:#333,stroke-width:2px;
    classDef module fill:#c9daf8,stroke:#333,stroke-width:2px;
    classDef external fill:#f9cb9c,stroke:#333,stroke-width:2px;
    classDef cicd fill:#ead1dc,stroke:#333,stroke-width:2px;

    %% Click Events
    click CoreLib "https://github.com/microsoft/semantic-link-labs/tree/main/src/sempy_labs"
    click ModelBPA "https://github.com/microsoft/semantic-link-labs/blob/main/src/sempy_labs/_model_bpa.py"
    click Translations "https://github.com/microsoft/semantic-link-labs/blob/main/src/sempy_labs/_translations.py"
    click BPA_Translation "https://github.com/microsoft/semantic-link-labs/tree/main/src/sempy_labs/_bpa_translation"
    click Migration "https://github.com/microsoft/semantic-link-labs/tree/main/src/sempy_labs/migration"
    click DirectLake "https://github.com/microsoft/semantic-link-labs/tree/main/src/sempy_labs/directlake"
    click Admin "https://github.com/microsoft/semantic-link-labs/tree/main/src/sempy_labs/admin"
    click Reporting "https://github.com/microsoft/semantic-link-labs/tree/main/src/sempy_labs/report"
    click TOM "https://github.com/microsoft/semantic-link-labs/tree/main/src/sempy_labs/tom"
    click Auth "https://github.com/microsoft/semantic-link-labs/blob/main/src/sempy_labs/_authentication.py"
    click GraphQL "https://github.com/microsoft/semantic-link-labs/blob/main/src/sempy_labs/_graphQL.py"
    click HelperFunctions "https://github.com/microsoft/semantic-link-labs/blob/main/src/sempy_labs/_helper_functions.py"
    click Notebooks "https://github.com/microsoft/semantic-link-labs/tree/main/notebooks"
    click Docs "https://github.com/microsoft/semantic-link-labs/tree/main/docs"
    click ReadTheDocs "https://github.com/microsoft/semantic-link-labs/blob/main/.readthedocs.yaml"
    click CI_CD "https://github.com/microsoft/semantic-link-labs/tree/main/.github/workflows"
    click Tests "https://github.com/microsoft/semantic-link-labs/tree/main/tests"
    click PyProject "https://github.com/microsoft/semantic-link-labs/blob/main/pyproject.toml"
    click EnvYML "https://github.com/microsoft/semantic-link-labs/blob/main/environment.yml"
```
