# atlassian-labs/msteams-jira-server architecture

> Architecture diagram of the GitHub repository atlassian-labs/msteams-jira-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atlassian-labs/msteams-jira-server
- Repository: https://github.com/atlassian-labs/msteams-jira-server

## Overview

##### Main Components
- Backend Application (MicrosoftTeamsIntegration.Jira):
– Contains the core integration logic including controllers (BotController, JiraApiController, etc.), dialogs (for creating, editing, and managing issues), and service layers (for Jira API, bot framework adapter, analytics, database interactions, etc.).
– Houses infrastructure for telemetrics, caching, and table storage integrations.
- Shared Artifacts (MicrosoftTeamsIntegration.Artifacts):
– Provides reusable components such as Teams bot adapters, middleware (for logging and telemetry), and common extensions or helper routines.
- Frontend Client (ClientApp under MicrosoftTeamsIntegration.Jira):
– An Angular-based client that powers the Teams tab interface, messaging extension, and interactive dialogs.
- External Integrations and Services:
– Microsoft Teams Channel and Bot Framework: The bot configuration, authentication with OAuth (via Azure AD), and messaging endpoints.
– Azure Services: SignalR (for real-time updates), Azure Cosmos (MongoDB), Redis Cache, and Azure Storage (for bot data storage).
– Jira Data Center: The plugin/add-on that must be installed on Jira, including its configuration and REST API interactions.
– OAuth and Authentication infrastructure (configuration via appsettings and Azure AD).

##### Relationships and Interactions
- Users in Microsoft Teams interact with:
– The Messaging Extension (for searching/submitting Jira issues).
– The Bot (for executing actions like create, comment, assign, or update issues).
– Custom Tabs (for viewing backlog and filters).
- The Frontend Angular app sends requests (via secure API endpoints provided by the Backend Controllers) to the server.
- The Backend processes these requests in a layered approach:
– Controllers receive and route requests.
– Dialogs and services in the business layer handle specific functionality (e.g., Jira API calls, proactive messages, and notifications).
– Integration with external services is facilitated by dedicated service classes (such as GraphApiService, SignalR Service, and Database Service).
- The Bot component also interacts with the Microsoft Bot Framework, with endpoints configured as per the Azure Bot registration.
- Each component records logs and telemetry, interacting with the telemetry and caching infrastructure.
- The add-on for Jira Data Center is separately installed on Jira and communicates (via webhooks and REST API calls) with this integration layer.

##### Architectural Patterns and Design Principles
- Layered Architecture – Separation between the presentation (Angular client), API controllers (HTTP endpoints), business logic (services, dialogs), and data/infrastructure layers.
- Dependency Injection – Evident by the structured services and extensions.
- Modular Design – Clear division into subdirectories such as Controllers, Dialogs, Models, Services, Middleware, and Extensions makes it easier to isolate responsibilities.
- External Integration – The design encapsulates integration with Microsoft Teams, Azure services, and Jira, keeping external dependencies configurable (using appsettings and environment-specific manifest files).

##### Relevant Technologies and Frameworks
- .NET (ASP.NET Core likely) as the backend framework.
- Angular for the frontend Microsoft Teams client application.
- Microsoft Bot Framework for Teams bot integration.
- Azure services (SignalR, Storage, Cosmos DB/MongoDB, Redis Cache) to support scalable, real-time, and persistent operations.
- OAuth 2.0 and OpenID Connect for authentication and authorization.
- Standard web deployment practices using Docker (Dockerfile present), CI/CD pipelines (GitHub Actions, bitbucket-pipelines.yml), and manifests for various environments (development, integration, production, staging).

##### Additional Points
- Be as detailed as possible by separating the project into many components. Don’t shy away from depicting each major module or service (e.g., individual dialogs, caching service, telemetry, and error-handling middleware).
- Incorporate configuration management elements – show how appsettings (in JSON) feed into the overall system configuration.
- Optionally, include a note about testing by highlighting the test projects that mirror the architecture (e.g., tests for Controllers, Services, and Dialogs).

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interaction Layer
    subgraph "User Interaction"
        T["Microsoft Teams (User)"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        A["Frontend (Angular Client)"]:::internal
    end

    %% Backend Application
    subgraph "Backend Application"
        C["Controllers (API)"]:::internal
        D["Dialogs (Business Logic)"]:::internal
        S["Services (Business Logic)"]:::internal
        C -->|"routes"| D
        D -->|"executes"| S
    end

    %% Reusable Artifacts
    subgraph "Reusable Artifacts"
        R["Reusable Components"]:::internal
    end

    %% External Integrations
    subgraph "External Integrations"
        subgraph "Azure Services"
            AS["Azure SignalR"]:::external
            AST["Azure Table Storage (Bot Data)"]:::external
            DC["Distributed Cache (Redis)"]:::external
            GA["Graph API"]:::external
        end
        O["OAuth (Azure AD)"]:::external
        B["Microsoft Bot Framework"]:::external
        J["Jira Data Center Plugin"]:::external
    end

    %% Connections between layers
    T -->|"interacts"| A
    A -->|"sends API requests"| C
    C -->|"validates/authenticates"| O
    C -->|"handles bot actions"| B
    A -->|"invokes messaging extension"| B
    S -->|"utilizes"| R
    S -->|"calls"| AS
    S -->|"calls"| AST
    S -->|"calls"| DC
    S -->|"calls"| GA
    S -->|"integrates with"| J

    %% Styles
    classDef internal fill:#bbf,stroke:#333,stroke-width:2px,color:#000;
    classDef external fill:#f9f,stroke:#333,stroke-width:2px,color:#000;

    %% Click Events
    click C "https://github.com/atlassian-labs/msteams-jira-server/tree/main/src/MicrosoftTeamsIntegration.Jira/Controllers"
    click D "https://github.com/atlassian-labs/msteams-jira-server/tree/main/src/MicrosoftTeamsIntegration.Jira/Dialogs"
    click S "https://github.com/atlassian-labs/msteams-jira-server/tree/main/src/MicrosoftTeamsIntegration.Jira/Services"
    click R "https://github.com/atlassian-labs/msteams-jira-server/blob/main/src/MicrosoftTeamsIntegration.Artifacts"
    click A "https://github.com/atlassian-labs/msteams-jira-server/tree/main/src/MicrosoftTeamsIntegration.Jira/ClientApp"
    click AS "https://github.com/atlassian-labs/msteams-jira-server/blob/main/src/MicrosoftTeamsIntegration.Jira/Services/SignalR/SignalRService.cs"
    click AST "https://github.com/atlassian-labs/msteams-jira-server/blob/main/src/MicrosoftTeamsIntegration.Artifacts/Services/TableStorage/AzureTableStorage.cs"
    click DC "https://github.com/atlassian-labs/msteams-jira-server/blob/main/src/MicrosoftTeamsIntegration.Artifacts/Services/DistributedCacheService.cs"
    click GA "https://github.com/atlassian-labs/msteams-jira-server/blob/main/src/MicrosoftTeamsIntegration.Artifacts/Services/GraphApiService.cs"
    click O "https://github.com/atlassian-labs/msteams-jira-server/blob/main/src/MicrosoftTeamsIntegration.Jira/Controllers/MicrosoftIdentityAssociationController.cs"
    click J "https://github.com/atlassian-labs/msteams-jira-server/blob/main/src/MicrosoftTeamsIntegration.Jira"
```
