# ismaelmartinez/teams-for-linux architecture

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

- Interactive diagram: https://gitdiagram.com/ismaelmartinez/teams-for-linux
- Repository: https://github.com/ismaelmartinez/teams-for-linux

## Overview

##### Project Type and Purpose
- This is a desktop application built on Electron that wraps the Microsoft Teams web client in a standalone shell for Linux (and other OSes).
- It is neither a traditional full-stack web app nor a microservice system; it’s a single-process Electron app with multiple renderer windows and modular features.

##### High-Level Architectural Components
a. Operating System
- Linux (with support for other OSes via the Electron layer)
b. Electron Runtime
- Main Process – orchestrates windows, modules, native integrations, packaging
- Renderer Processes – BrowserWindow instances that host web content or HTML UIs:
– Main Teams window (webview)
– Login window
– Stream selector window
c. Internal Modules (all loaded by the Main Process)
- appConfiguration – runtime settings loader
- config & logger – feature flags, logging configuration
- connectionManager – manages network events, offline/online state
- certificate – custom certificate handling for webview
- customBackground & customCSS – user-supplied UI tweaks
- spellCheckProvider – spellcheck dictionaries and API hooking
- intune – optional enterprise integration
- menus – application menu and tray menu management
- helpers – utility libraries
d. Build & Packaging
- scripts/afterpack.js and build/* manifest files generate AppImage, snap, deb, rpm, tar.gz
e. External Services
- Microsoft Teams web servers (HTTPS)
- OS native APIs (notifications, tray, file system)
- Extension points (firejail sandbox script, AppImageLauncher)

##### Interactions and Data Flow
- On launch, Main Process loads appConfiguration → config → logger → modules.
- Main Process creates the main BrowserWindow, preloading custom scripts (settings, theme, shortcuts, etc.).
- Renderer (webview) loads teams.microsoft.com → standard Teams UI.
- IPC channels connect Renderer ↔ Main for events (new meetings, notifications, spellcheck).
- User triggers in UI (e.g., change theme, custom CSS) → Renderer sends IPC to Main → Main applies settings dynamically.
- ConnectionManager monitors connectivity and informs Renderer via IPC.

##### Key Architectural Patterns & Principles
- Modular Main Process: each feature is a self-contained module under `app/`
- Clear separation between Main and Renderer (Electron’s multi-process model)
- IPC for cross-process communication
- Configuration-driven behavior (JSON + README docs in `app/config`)
- Plugin-style hooking: customCSS and customBackground load user assets at runtime

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Electron Runtime"
        direction TB
        subgraph "Main Process"
            direction TB
            MP_Index["index.js"]:::mainProc
            AppConfig["appConfiguration"]:::mainProc
            ConfigLoader["config"]:::mainProc
            Logger["logger"]:::mainProc
            ConnectionMgr["connectionManager"]:::mainProc
            Certificate["certificate"]:::mainProc
            CustomBG["customBackground"]:::mainProc
            CustomCSS["customCSS"]:::mainProc
            SpellCheck["spellCheckProvider"]:::mainProc
            Intune["intune"]:::mainProc
            subgraph "Menus"
                direction TB
                AppMenu["appMenu"]:::mainProc
                TrayMenu["tray"]:::mainProc
                MenusIndex["index"]:::mainProc
            end
            Helpers["helpers"]:::mainProc
        end

        subgraph "Renderer Processes"
            direction TB
            subgraph "Main Teams Window"
                direction TB
                MW_Manager["browserWindowManager"]:::renderer
                MW_Index["index.js"]:::renderer
            end
            subgraph "Login Window"
                direction TB
                LoginLogic["login/index.js"]:::renderer
                LoginHTML["login.html"]:::renderer
                LoginPreload["preload.js"]:::renderer
            end
            subgraph "Stream Selector Window"
                direction TB
                SS_UI["index.js"]:::renderer
                SS_Browser["browser.js"]:::renderer
                SS_HTML["index.html"]:::renderer
                SS_CSS["index.css"]:::renderer
                SS_Preload["preload.js"]:::renderer
            end
        end
    end

    subgraph "Build & Packaging"
        direction TB
        AfterPack["afterpack.js"]:::packaging
        AppData["com.github.IsmaelMartinez.teams_for_linux.appdata.xml"]:::packaging
        BuildIcons["build/icons"]:::packaging
    end

    subgraph "External Services"
        direction TB
        TeamsServer[(Microsoft Teams Web Servers)]:::external
        OS_APIs[(OS Native APIs)]:::external
    end

    %% Initialization Flow
    MP_Index --> AppConfig --> ConfigLoader --> Logger
    Logger --> ConnectionMgr --> Certificate --> CustomBG --> CustomCSS --> SpellCheck --> Intune --> Helpers --> MP_Index

    %% Renderer Creation
    MP_Index --> MW_Manager --> MW_Index
    MP_Index --> LoginLogic --> LoginHTML
    MP_Index --> SS_UI --> SS_HTML

    %% Preload Scripts
    MP_Index -->|"preload"| MW_Manager
    MP_Index -->|"preload"| LoginPreload
    MP_Index -->|"preload"| SS_Preload

    %% IPC Channels
    ConnectionMgr -->|IPC| MW_Index
    ConnectionMgr -->|IPC| LoginLogic
    ConnectionMgr -->|IPC| SS_UI
    CustomCSS -->|IPC| MW_Index
    CustomBG -->|IPC| MW_Index
    SpellCheck -->|IPC| MW_Index
    MenusIndex -->|IPC| MW_Index

    %% External Communications
    MW_Index -->|HTTPS| TeamsServer
    MW_Index -->|calls| OS_APIs
    LoginLogic -->|calls| OS_APIs
    SS_UI -->|calls| OS_APIs

    %% Build & Packaging Link
    MP_Index --> AfterPack
    AfterPack --> AppData
    AfterPack --> BuildIcons

    %% Styles
    classDef mainProc fill:#cce5ff,stroke:#007bff
    classDef renderer fill:#d4edda,stroke:#28a745
    classDef external fill:#f8d7da,stroke:#dc3545,stroke-width:2px
    classDef packaging fill:#e2e3e5,stroke:#6c757d
    classDef optional stroke-dasharray: 5 5

    %% Optional feature styling
    class Intune optional

    %% Click Events
    click MP_Index "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/index.js"
    click AppConfig "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/appConfiguration/index.js"
    click ConfigLoader "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/config/index.js"
    click Logger "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/config/logger.js"
    click ConnectionMgr "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/connectionManager/index.js"
    click Certificate "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/certificate/index.js"
    click CustomBG "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/customBackground/index.js"
    click CustomCSS "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/customCSS/index.js"
    click SpellCheck "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/spellCheckProvider/index.js"
    click Intune "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/intune/index.js"
    click AppMenu "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/menus/appMenu.js"
    click TrayMenu "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/menus/tray.js"
    click MenusIndex "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/menus/index.js"
    click Helpers "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/helpers/index.js"
    click MW_Manager "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/mainAppWindow/browserWindowManager.js"
    click MW_Index "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/mainAppWindow/index.js"
    click LoginLogic "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/login/index.js"
    click LoginHTML "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/login/login.html"
    click LoginPreload "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/login/preload.js"
    click SS_UI "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/streamSelector/index.js"
    click SS_Browser "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/streamSelector/browser.js"
    click SS_HTML "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/streamSelector/index.html"
    click SS_CSS "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/streamSelector/index.css"
    click SS_Preload "https://github.com/ismaelmartinez/teams-for-linux/blob/main/app/streamSelector/preload.js"
    click AfterPack "https://github.com/ismaelmartinez/teams-for-linux/blob/main/scripts/afterpack.js"
    click AppData "https://github.com/ismaelmartinez/teams-for-linux/blob/main/build/com.github.IsmaelMartinez.teams_for_linux.appdata.xml"
```
