# microsoft/botframework-sdk architecture

> Architecture diagram of the GitHub repository microsoft/botframework-sdk, 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/microsoft/botframework-sdk
- Repository: https://github.com/microsoft/botframework-sdk

## Overview

##### Project type and purpose
- This is an open-source, cross-platform Bot Framework CLI tool and SDK repository. It provides a command-line interface (“bf” or “botframework-cli”) for working with conversational assets (LU files, QnA, orchestrator models, transcripts, telemetry), plus related schemas and specs.

##### High-level file-structure analysis
- Top level:
- Common/Telemetry & Transcripts – shared modules for recording and replaying conversation events
- Orchestrator – .NET-based NLU module plus samples, versioned model artifacts
- parsers/LU/JS – Node-based LU file parser packaged via Rush (monorepo)
- dri – Python scripts for Data Reporting & Insights (reads telemetry, outputs reports)
- schemas & specs – JSON schemas and markdown specs for validation and protocol definition
- tools/changelog – release automation
- Build/config: Rush config under parsers/LU/JS/common/config/rush; package.json files in each package; tsconfig/linters in JS packages.

##### Key components
a. CLI Host (Node.js process)
b. Command Plugins (dynamically loaded modules):
- LU Parser (JS package)
- QnA Maker parser (JS)
- Dispatch tool (JS)
- Orchestrator CLI (calls .NET binary or library)
- Transcripts module (JS/Python)
- Telemetry module (JS collects, Python dri reports)
c. Language/Runtimes:
- Node.js runtime for JS modules (Rush monorepo)
- .NET Core runtime for Orchestrator engine
- Python runtime for DRI scripts
d. Static assets:
- JSON Schemas (schemas/) used by “validate” commands
- Markdown Specs (specs/) for human-readable protocol definitions

##### Component interactions and data flow
- The user invokes the CLI host using a command (e.g., `bf luis:parse`, `bf orchestrator:train`, `bf telemetry:report`).
- The CLI uses a plugin-loader to dispatch the call to the appropriate module.
- Parser modules read conversational resource files (LU/QnA), produce JSON outputs.
- Orchestrator module submits/consumes trained model files (nlr_versions.json) via .NET library.
- Telemetry collector instruments commands and writes events to a telemetry store.
- DRI Python scripts read telemetry logs and generate HTML/JSON reports.
- Validation commands consume JSON Schemas from schemas/ to validate manifests or protocol messages.

##### Architectural patterns and principles
- Plugin-based modularity: each CLI command is a separate package under Rush, loaded at runtime by the host
- Polyglot micro-services: JS, .NET, and Python runtimes co‐exist in a single toolchain
- Separation of concerns: parsing, orchestration, telemetry, schema validation, and reporting each live in their own module
- Monorepo management: Yarn/Rush orchestrates versioning, building, and publishing of multiple packages

##### Essential elements
- Clear labels on each runtime boundary and module

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external
    subgraph "CLI Host"
        CLI["CLI Host (Node.js)"]:::nodejs
    end
    User -->|"invoke command"| CLI

    subgraph "Node.js Plugins"
        LU["LU Parser"]:::nodejs
        QNA["QnA Maker Parser"]:::nodejs
        DISPATCH["Dispatch Tool"]:::nodejs
        TRANS_JS["Transcripts Module"]:::nodejs
        TELE_JS["Telemetry Module"]:::nodejs
    end
    CLI -->|"load parser"| LU
    CLI -->|"load parser"| QNA
    CLI -->|"load tool"| DISPATCH
    CLI -->|"load module"| TRANS_JS
    CLI -->|"load module"| TELE_JS

    subgraph ".NET Runtime"
        ORCH_CLI["Orchestrator CLI"]:::dotnet
    end
    CLI -->|"invoke orchestrator"| ORCH_CLI

    subgraph "Python Scripts"
        DRI_REPORT["dri/report.py"]:::python
        DRI_HELP["dri/helpers.py"]:::python
        DRI_OUT["dri/output.py"]:::python
    end
    TELE_JS -->|"write logs"| TeleStore["Telemetry Store"]:::static
    TeleStore --> DRI_REPORT
    DRI_REPORT --> DRI_HELP
    DRI_REPORT --> DRI_OUT

    subgraph "Static Assets"
        SCHEMAS["JSON Schemas"]:::static
        SPECS["Markdown Specs"]:::static
    end
    CLI -->|"validate"| SCHEMAS
    CLI -->|"show specs"| SPECS

    subgraph "Build Config"
        RUSH_CFG["Rush Config"]:::static
        RUSH_JSON["rush.json"]:::static
    end
    CLI -->|"build/publish"| RUSH_CFG
    CLI --> RUSH_JSON

    subgraph "Orchestrator Artifacts"
        SAMPLE_DOTNET[".NET Samples"]:::dotnet
        MODEL_V1["v0.1 nlr_versions.json"]:::dotnet
        MODEL_V2["v0.2 nlr_versions.json"]:::dotnet
    end
    ORCH_CLI --> SAMPLE_DOTNET
    ORCH_CLI --> MODEL_V1
    ORCH_CLI --> MODEL_V2

    subgraph "Tools"
        CHANGE_TOOL["Changelog Tool"]:::static
    end
    CLI -->|"release automation"| CHANGE_TOOL

    click CLI "https://github.com/microsoft/botframework-sdk/blob/main/parsers/LU/JS/packages/lu/src/index.ts"
    click LU "https://github.com/microsoft/botframework-sdk/tree/main/parsers/LU/JS/packages/lu/src/parser"
    click QNA "https://github.com/microsoft/botframework-sdk/tree/main/parsers/LU/JS/packages/lu/src/parser/qna/qnamaker"
    click ORCH_CLI "https://github.com/microsoft/botframework-sdk/blob/main/Orchestrator/README.md"
    click SAMPLE_DOTNET "https://github.com/microsoft/botframework-sdk/tree/main/Orchestrator/Samples/dotnet/nlp-with-entities"
    click MODEL_V1 "https://github.com/microsoft/botframework-sdk/blob/main/Orchestrator/v0.1/nlr_versions.json"
    click MODEL_V2 "https://github.com/microsoft/botframework-sdk/blob/main/Orchestrator/v0.2/nlr_versions.json"
    click TRANS_JS "https://github.com/microsoft/botframework-sdk/tree/main/Common/Transcripts"
    click TELE_JS "https://github.com/microsoft/botframework-sdk/tree/main/Common/Telemetry"
    click DRI_REPORT "https://github.com/microsoft/botframework-sdk/blob/main/dri/report.py"
    click DRI_HELP "https://github.com/microsoft/botframework-sdk/blob/main/dri/helpers.py"
    click DRI_OUT "https://github.com/microsoft/botframework-sdk/blob/main/dri/output.py"
    click SCHEMAS "https://github.com/microsoft/botframework-sdk/tree/main/schemas/"
    click SPECS "https://github.com/microsoft/botframework-sdk/tree/main/specs/"
    click RUSH_CFG "https://github.com/microsoft/botframework-sdk/tree/main/parsers/LU/JS/common/config/rush"
    click RUSH_JSON "https://github.com/microsoft/botframework-sdk/blob/main/parsers/LU/JS/rush.json"
    click CHANGE_TOOL "https://github.com/microsoft/botframework-sdk/blob/main/tools/changelog/git-log.js"

    classDef nodejs fill:#cfe2f3,stroke:#0366d6,stroke-width:1px;
    classDef dotnet fill:#ffd8a8,stroke:#d97706,stroke-width:1px;
    classDef python fill:#d1fae5,stroke:#065f46,stroke-width:1px;
    classDef static fill:#e5e7eb,stroke:#6b7280,stroke-width:1px;
    classDef external fill:#f0f0f0,stroke:#a0a0a0,stroke-width:1px;
```
