# microsoft/simplechat architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/simplechat
- Repository: https://github.com/microsoft/simplechat

## Overview

##### Project Type and Purpose
- This is a full-stack web application that enables users to chat with an AI model (using OpenAI’s GPT) and incorporates Retrieval-Augmented Generation (RAG). Users can upload documents (both personal and group) which are processed via Document Intelligence and stored/indexed for hybrid search (using Azure AI Search and Azure Cosmos DB). The system also integrates optional features like Bing Web Search, image generation, content safety filtering, and secure user authentication with Azure Active Directory.

##### File Structure
- Notice the “application/single_app” folder contains all the core source code including the “app.py”, configuration files, various route files (both backend and frontend), functions for handling authentication, search, documents, groups, etc.
- The “static” and “templates” directories define the UI parts, while individual “route_backend_*.py” and “route_frontend_*.py” files clearly show the separation between frontend and backend routes.
- Docker-related files (Dockerfile, .dockerignore) indicate that the application can be containerized for deployment.

a. User Interface / Client:
- Web browser (client) for desktop/mobile accessing the chat UI.
b. Frontend Component:
c. Backend (API & Business Logic) Component:
d. AI and Search Services:
- GPT Model (for generating chat responses)
- Embedding Model (for vectorization of document chunks)
- Image Generation Model (optional)
- “Azure AI Search” for knowledge retrieval and “Azure Document Intelligence” for processing uploaded documents.
e. Data Storage:
- That the project uses inline temporary storage and persistent storage via Cognitive Search.
f. External and Optional Services:
- “Azure Bing Search” for web-based augmentation.
g. Authentication and RBAC:
- Detail “Azure Active Directory” integration and note that MSAL is used for authentication, with role-based access (Admins, Users, etc.). Clearly show that user requests are funneled through an AD login/auth service.

##### Establishing Relationships and Data Flows
- To Azure OpenAI endpoints (for chat responses, embeddings, image generation).
- To Azure AI Search for document indexing and query operations.
- To Azure Cosmos DB for storing conversations and metadata.
- To Azure Document Intelligence for processing incoming documents.
- Optionally, to Bing Search and Content Safety modules for additional functionality.
- Also, include a connection from the backend to Azure Active Directory to illustrate the flow for user authentication and role assignment.

##### Architectural Patterns and Design Principles
- Separation of concerns by distinguishing front-end (presentation/UI) from backend (logic, API routing, service orchestration).
- Security patterns such as the use of Azure AD, RBAC, and content safety checks placed as a gate before any service interactions.
- Demonstrate the microservice-like integration with multiple external Azure services, each handling specialist tasks (e.g., search, document intelligence).

##### Final Assembly
- Detail the flow: the frontend serves UI assets and interacts with backend routes; the backend orchestrates calls to AI services and data stores; external Azure services such as OpenAI, Cognitive Search, Cosmos DB, Document Intelligence, and Bing Search are clearly marked.
- Don’t forget to include deployment aspects (Docker support, Azure App Service) since the project is designed for Azure and runs within containerized environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client Browser"]:::client

    %% Frontend Subgraph
    subgraph "Frontend"
        Frontend_Routes["Frontend Routes"]:::internal
        Static_Assets["Static Assets"]:::internal
        HTML_Templates["HTML Templates"]:::internal
        Frontend_Groups["Frontend Group Management"]:::internal
        Frontend_Safety["Frontend Safety"]:::internal
    end

    %% Backend Subgraph
    subgraph "Backend"
        Backend_API["Backend API & Logic"]:::internal
        Doc_Management["Document Management"]:::internal
        Group_Documents["Group Documents"]:::internal
        Group_Management["Group Management"]:::internal
        Search_Service["Search Service"]:::internal
        Bing_Search["Bing Web Search Integration"]:::internal
        Content_Safety_API["Content Safety API"]:::internal
        Auth_Service["Authentication Service"]:::internal
    end

    %% External Services Subgraph
    subgraph "External Services"
        GPT_Model["GPT Model (Azure OpenAI)"]:::external
        Embedding_Model["Embedding Model (Azure OpenAI)"]:::external
        Image_Generation["Image Generation Model (Azure OpenAI)"]:::external
        Azure_AI_Search["Azure AI Search"]:::external
        Doc_Intelligence["Azure Document Intelligence"]:::external
        Cosmos_DB["Azure Cosmos DB"]:::database
        Azure_AD["Azure Active Directory"]:::external
    end

    %% Connections - Vertical flow
    Client -->|"accesses"| Frontend_Routes
    Frontend_Routes -->|"renders"| Backend_API

    %% Frontend internal connections
    Frontend_Routes -->|"includes"| Static_Assets
    Frontend_Routes -->|"includes"| HTML_Templates
    Frontend_Routes -->|"navigates to"| Frontend_Groups
    Frontend_Routes -->|"integrates"| Frontend_Safety

    %% Backend internal connections
    Backend_API -->|"handles"| Doc_Management
    Backend_API -->|"handles"| Group_Documents
    Backend_API -->|"handles"| Group_Management
    Backend_API -->|"handles"| Search_Service
    Backend_API -->|"handles"| Bing_Search
    Backend_API -->|"handles"| Content_Safety_API
    Backend_API -->|"handles"| Auth_Service

    %% Backend calling external services
    Backend_API -->|"calls"| GPT_Model
    Backend_API -->|"calls"| Embedding_Model
    Backend_API -->|"calls"| Image_Generation
    Backend_API -->|"calls"| Azure_AI_Search
    Backend_API -->|"calls"| Doc_Intelligence
    Backend_API -->|"calls"| Cosmos_DB
    Auth_Service -->|"authenticates via"| Azure_AD

    %% Click Events for Frontend Component
    click Frontend_Routes "https://github.com/microsoft/simplechat/blob/main/application/single_app/route_frontend_*.py"
    click Static_Assets "https://github.com/microsoft/simplechat/tree/main/application/single_app/static"
    click HTML_Templates "https://github.com/microsoft/simplechat/tree/main/application/single_app/templates"
    click Frontend_Groups "https://github.com/microsoft/simplechat/blob/main/application/single_app/route_frontend_groups.py"
    click Frontend_Safety "https://github.com/microsoft/simplechat/blob/main/application/single_app/route_frontend_safety.py"

    %% Click Event for Backend Component
    click Backend_API "https://github.com/microsoft/simplechat/blob/main/application/single_app/app.py"

    %% Click Events for Authentication and RBAC
    click Auth_Service "https://github.com/microsoft/simplechat/blob/main/application/single_app/functions_authentication.py"

    %% Click Events for Document Management
    click Doc_Management "https://github.com/microsoft/simplechat/blob/main/application/single_app/functions_documents.py"
    click Group_Documents "https://github.com/microsoft/simplechat/blob/main/application/single_app/functions_group_documents.py"

    %% Click Event for Search Functionality
    click Search_Service "https://github.com/microsoft/simplechat/blob/main/application/single_app/functions_search.py"

    %% Click Event for Bing Web Search Integration
    click Bing_Search "https://github.com/microsoft/simplechat/blob/main/application/single_app/functions_bing_search.py"

    %% Click Event for Content Safety
    click Content_Safety_API "https://github.com/microsoft/simplechat/blob/main/application/single_app/route_backend_safety.py"

    %% Click Event for Group Management
    click Group_Management "https://github.com/microsoft/simplechat/blob/main/application/single_app/functions_group.py"

    %% Styles
    classDef client fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef database fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
