# microsoft/sample-app-aoai-chatgpt architecture

> Architecture diagram of the GitHub repository microsoft/sample-app-aoai-chatgpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/sample-app-aoai-chatgpt
- Repository: https://github.com/microsoft/sample-app-aoai-chatgpt

## Overview

1. **Overall shape**
   - This is a two-tier sample app: a Python backend exposes chat/API endpoints, and a React/TypeScript frontend provides the UI.
   - The app is designed around Azure OpenAI, with multiple optional “data source” backends for retrieval-augmented chat.

2. **Backend entrypoint and runtime**
   - `app.py` is the backend entrypoint, served in production through `gunicorn.conf.py` and `python3 -m gunicorn app:app`.
   - The backend is the integration boundary for Azure OpenAI calls, auth checks, data-source querying, chat-history persistence, and security-related request handling.

3. **Frontend presentation layer**
   - `frontend/` is a Vite-based React SPA written in TypeScript.
   - Main UI areas are the chat page, answer rendering, question input, and chat history panel under `frontend/src/pages` and `frontend/src/components`.
   - `frontend/src/state` holds shared app state, while `frontend/src/api` centralizes client calls to the backend.

4. **Static asset build pipeline**
   - Frontend build output is copied into `static/`, which is what the backend serves in deployed environments.
   - This repo therefore has a clear source/build split: source lives in `frontend/`, deployable browser assets live in `static/`.
   - Custom logos/favicon assets are expected to be placed in `frontend/public` and end up in `static/assets` after build.

5. **Primary data flow: user chat to model response**
   - The user submits a question in the frontend.
   - The frontend sends the request to the Python backend.
   - The backend forwards the prompt to Azure OpenAI, optionally including retrieved context from a configured data source and/or prior chat history.
   - The generated response, citations, and metadata come back to the frontend for rendering.

6. **Retrieval/data-source boundary**
   - The app supports several mutually exclusive retrieval backends selected by environment variables:
     - Azure AI Search
     - Azure Cosmos DB Mongo vCore
     - Elasticsearch
     - Pinecone
     - MongoDB
     - Azure SQL Server
     - Promptflow endpoint
   - The retrieval layer is a major architectural boundary: the chat UI and core orchestration stay the same, while the backend swaps in different query/connectors depending on `DATASOURCE_TYPE` or related flags.

7. **Chat history persistence**
   - When enabled, chat history is stored separately in Azure Cosmos DB using the `AZURE_COSMOSDB_*` settings.
   - This is distinct from the document/retrieval data source: one Cosmos DB path is for conversation history, another may be used for document retrieval depending on configuration.
   - The chat history UI in `frontend/src/components/ChatHistory` reflects this persisted conversation state.

8. **Authentication and access control**
   - Authentication is optional but treated as important for production; the README notes chat can be blocked if no identity provider is configured.
   - `backend/auth` contains auth helpers and sample user logic, indicating the backend can enforce or simulate user identity.
   - Access control is also tied to data retrieval, including optional group-based filtering via fields like `AZURE_SEARCH_PERMITTED_GROUPS_COLUMN`.

9. **Security and compliance hooks**
   - `backend/security/ms_defender_utils.py` suggests integration with Microsoft Defender for Cloud threat protection context.
   - `SANITIZE_ANSWER` and related UI settings indicate a post-processing boundary where model output may be cleaned before display.
   - The repo also includes `backend/settings.py` and shared utils, which likely centralize environment parsing and request/runtime configuration.

10. **Offline/data-prep and indexing tooling**
   - The `scripts/` directory is a substantial operational subsystem for preparing documents, chunking, embedding, and pushing content into target stores.
   - There are separate prep paths for ACS, Cosmos, Pinecone, and batch indexing, which supports the repo’s multi-datasource architecture.
   - `data/employee_handbook.pdf` is the sample corpus used by those pipelines.

11. **Infrastructure and deployment**
   - `infra/` contains Bicep modules for Azure resources: App Service hosting, AI/Cognitive Services, Cosmos DB, Search, Storage, and role assignments.
   - `infrastructure/deployment.json` supports one-click deployment, while `azure.yaml` and `README_azd.md` indicate Azure Developer CLI support.
   - This means the repo is deployable as a managed Azure application rather than a self-contained local demo only.

12. **Validation and test boundaries**
   - `tests/` includes unit tests for settings and utilities plus integration tests for datasource-related behavior.
   - Frontend components also have targeted tests, e.g. answer parsing.
   - CI workflows in `.github/workflows` validate static files, test updates, and app builds, reflecting the separation between frontend build artifacts, backend Python code, and infrastructure/configuration.

13. **Useful diagram boundaries**
   - A useful architecture diagram should separate: browser/UI, Python web backend, Azure OpenAI, retrieval datasource(s), Cosmos DB for chat history, and Azure deployment/infrastructure.
   - The most important arrows are user input to backend, backend to Azure OpenAI, backend to retrieval store, and backend to chat-history store.

Main entry points: [`app.py`](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/app.py) (App Entrypoint), [`scripts/datastore.yml`](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/scripts/datastore.yml) (Datasource Switch), [`frontend/src/pages/chat/Chat.tsx`](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/pages/chat/Chat.tsx) (Chat UI), [`infra/main.bicep`](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/infra/main.bicep) (Infra Stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_frontend["Frontend"]
  node_frontend_chat["Chat UI<br/>React page<br/>[Chat.tsx]"]
  node_frontend_input["Question Input<br/>React component<br/>[QuestionInput.tsx]"]
  node_frontend_answer["Answer View<br/>React component<br/>[Answer.tsx]"]
  node_frontend_history["Chat History<br/>React component"]
  node_frontend_state["App State<br/>React state<br/>[AppProvider.tsx]"]
  node_frontend_api["API Client<br/>TS client<br/>[api.ts]"]
end

subgraph group_grp_backend["Backend"]
  node_backend_app["App Entrypoint<br/>Python WSGI<br/>[app.py]"]
  node_backend_settings["Settings<br/>Python config<br/>[settings.py]"]
  node_backend_auth["Auth Helpers<br/>Python auth<br/>[auth_utils.py]"]
  node_backend_history[("Chat History<br/>Cosmos service<br/>[cosmosdbservice.py]")]
  node_backend_security["Defender Hooks<br/>Python security"]
  node_backend_utils["Shared Utils<br/>Python utils<br/>[utils.py]"]
end

subgraph group_grp_retrieval["Retrieval"]
  node_retrieval_router{{"Datasource Switch<br/>Python retrieval<br/>[datastore.yml]"}}
  node_azure_search[("Azure Search<br/>retrieval backend<br/>[push_to_acs.py]")]
  node_cosmos_source[("Cosmos vCore<br/>retrieval backend")]
  node_elasticsearch[("Elasticsearch<br/>retrieval backend")]
  node_pinecone[("Pinecone<br/>retrieval backend")]
  node_docprep["Doc Prep<br/>pipeline<br/>[prepdocs.py]"]
end

subgraph group_grp_platform["Platform"]
  node_openai[("Azure OpenAI<br/>LLM service")]
  node_cosmos_history_store[("History Store<br/>Cosmos DB")]
  node_infra_main["Infra Stack<br/>Bicep deployment<br/>[main.bicep]"]
  node_appservice["App Service<br/>Azure host<br/>[appservice.bicep]"]
  node_search_service[("Search Service<br/>Azure search")]
end

node_frontend_chat -->|"uses"| node_frontend_input
node_frontend_chat -->|"renders"| node_frontend_answer
node_frontend_chat -->|"shows"| node_frontend_history
node_frontend_chat -->|"reads/writes"| node_frontend_state
node_frontend_state -->|"calls"| node_frontend_api
node_frontend_api -->|"requests"| node_backend_app
node_backend_app -->|"loads"| node_backend_settings
node_backend_app -->|"checks"| node_backend_auth
node_backend_app -->|"applies"| node_backend_security
node_backend_app -->|"uses"| node_backend_utils
node_backend_app -->|"calls"| node_openai
node_backend_app -->|"queries"| node_retrieval_router
node_retrieval_router -.->|"can use"| node_azure_search
node_retrieval_router -.->|"can use"| node_cosmos_source
node_retrieval_router -.->|"can use"| node_elasticsearch
node_retrieval_router -.->|"can use"| node_pinecone
node_retrieval_router -->|"feeds"| node_docprep
node_backend_app -->|"persists"| node_backend_history
node_backend_history -->|"stores in"| node_cosmos_history_store
node_infra_main -->|"provisions"| node_appservice
node_infra_main -->|"provisions"| node_search_service
node_infra_main -->|"provisions"| node_cosmos_history_store
node_appservice -->|"runs"| node_backend_app
node_search_service -->|"supports"| node_azure_search

click node_frontend_chat "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/pages/chat/Chat.tsx"
click node_frontend_input "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/components/QuestionInput/QuestionInput.tsx"
click node_frontend_answer "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/components/Answer/Answer.tsx"
click node_frontend_history "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/components/ChatHistory/ChatHistoryPanel.tsx"
click node_frontend_state "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/state/AppProvider.tsx"
click node_frontend_api "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/api/api.ts"
click node_backend_app "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/app.py"
click node_backend_settings "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/backend/settings.py"
click node_backend_auth "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/backend/auth/auth_utils.py"
click node_backend_history "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/backend/history/cosmosdbservice.py"
click node_backend_security "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/backend/security/ms_defender_utils.py"
click node_backend_utils "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/backend/utils.py"
click node_retrieval_router "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/scripts/datastore.yml"
click node_azure_search "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/scripts/push_to_acs.py"
click node_cosmos_source "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/scripts/cosmos_mongo_vcore_data_preparation.py"
click node_elasticsearch "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/notebooks/AzureOpenAI_OnYourData_Elasticsearch.ipynb"
click node_pinecone "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/scripts/pinecone_data_preparation.py"
click node_docprep "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/scripts/prepdocs.py"
click node_cosmos_history_store "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/infra/core/database/cosmos/cosmos-account.bicep"
click node_infra_main "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/infra/main.bicep"
click node_appservice "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/infra/core/host/appservice.bicep"
click node_search_service "https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/infra/core/search/search-services.bicep"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_chat,node_frontend_input,node_frontend_answer,node_frontend_history,node_frontend_state,node_frontend_api toneBlue
class node_backend_app,node_backend_settings,node_backend_auth,node_backend_history,node_backend_security,node_backend_utils toneAmber
class node_retrieval_router,node_azure_search,node_cosmos_source,node_elasticsearch,node_pinecone,node_docprep toneMint
class node_openai,node_cosmos_history_store,node_infra_main,node_appservice,node_search_service toneRose
```

## Components

### Frontend

React/TypeScript SPA and browser-facing build

- [Chat UI](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/pages/chat/Chat.tsx): React page · Main chat page and layout shell · `frontend/src/pages/chat/Chat.tsx`
- [Question Input](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/components/QuestionInput/QuestionInput.tsx): React component · Prompt entry and submit control · `frontend/src/components/QuestionInput/QuestionInput.tsx`
- [Answer View](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/components/Answer/Answer.tsx): React component · Renders answers and parsed citations · `frontend/src/components/Answer/Answer.tsx`
- [Chat History](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/components/ChatHistory/ChatHistoryPanel.tsx): React component · Conversation list and history panel · `frontend/src/components/ChatHistory/ChatHistoryPanel.tsx`
- [App State](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/state/AppProvider.tsx): React state · Shared client state and reducer flow · `frontend/src/state/AppProvider.tsx`
- [API Client](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/frontend/src/api/api.ts): TS client · Centralized browser calls to backend APIs · `frontend/src/api/api.ts`

### Backend

Python web app, auth, history, and security boundaries

- [App Entrypoint](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/app.py): Python WSGI · Backend application entrypoint · `app.py`
- [Settings](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/backend/settings.py): Python config · Environment parsing and runtime configuration · `backend/settings.py`
- [Auth Helpers](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/backend/auth/auth_utils.py): Python auth · Identity and access-control helpers · `backend/auth/auth_utils.py`
- [Chat History](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/backend/history/cosmosdbservice.py): Cosmos service · Conversation persistence in Cosmos DB · `backend/history/cosmosdbservice.py`
- [Defender Hooks](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/backend/security/ms_defender_utils.py): Python security · Security and threat-protection integration · `backend/security/ms_defender_utils.py`
- [Shared Utils](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/backend/utils.py): Python utils · Common backend helpers and request utilities · `backend/utils.py`

### Retrieval

Optional data-source connectors and document preparation

- [Datasource Switch](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/scripts/datastore.yml): Python retrieval · Selects the active retrieval backend by configuration · `scripts/datastore.yml`
- [Azure Search](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/scripts/push_to_acs.py): retrieval backend · Search-based document retrieval · `scripts/push_to_acs.py`
- [Cosmos vCore](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/scripts/cosmos_mongo_vcore_data_preparation.py): retrieval backend · Mongo vCore document retrieval path · `scripts/cosmos_mongo_vcore_data_preparation.py`
- [Elasticsearch](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/notebooks/AzureOpenAI_OnYourData_Elasticsearch.ipynb): retrieval backend · Elasticsearch retrieval path · `notebooks/AzureOpenAI_OnYourData_Elasticsearch.ipynb`
- [Pinecone](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/scripts/pinecone_data_preparation.py): retrieval backend · Vector-store retrieval path · `scripts/pinecone_data_preparation.py`
- [Doc Prep](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/scripts/prepdocs.py): pipeline · Chunking, embedding, and indexing pipelines · `scripts/prepdocs.py`

### Platform

Azure deployment, infrastructure, and runtime assets

- **Azure OpenAI**: LLM service · Chat completion and response generation
- [History Store](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/infra/core/database/cosmos/cosmos-account.bicep): Cosmos DB · Separate Cosmos DB store for chat transcripts · `infra/core/database/cosmos/cosmos-account.bicep`
- [Infra Stack](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/infra/main.bicep): Bicep deployment · Azure resource composition and provisioning · `infra/main.bicep`
- [App Service](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/infra/core/host/appservice.bicep): Azure host · Production hosting target for the backend · `infra/core/host/appservice.bicep`
- [Search Service](https://github.com/microsoft/sample-app-aoai-chatgpt/blob/main/infra/core/search/search-services.bicep): Azure search · Azure AI Search resource used by retrieval · `infra/core/search/search-services.bicep`

## Connections

- Chat UI → Question Input: uses · Chat page embeds prompt entry
- Chat UI → Answer View: renders · Chat page displays generated answers
- Chat UI → Chat History: shows · Chat page includes conversation history
- Chat UI → App State: reads/writes · Page state is managed through shared app state
- App State → API Client: calls · State actions invoke backend APIs
- API Client → App Entrypoint: requests · Browser sends chat and history requests to backend
- App Entrypoint → Settings: loads · Entry point uses runtime settings
- App Entrypoint → Auth Helpers: checks · Backend validates identity and access
- App Entrypoint → Defender Hooks: applies · Security hooks run on requests and responses
- App Entrypoint → Shared Utils: uses · Shared helpers support runtime behavior
- App Entrypoint → Azure OpenAI: calls · Backend forwards prompts to Azure OpenAI
- App Entrypoint → Datasource Switch: queries · Backend selects and queries the active datasource
- Datasource Switch → Azure Search: can use · Search-backed retrieval option
- Datasource Switch → Cosmos vCore: can use · Cosmos vCore retrieval option
- Datasource Switch → Elasticsearch: can use · Elasticsearch retrieval option
- Datasource Switch → Pinecone: can use · Pinecone retrieval option
- Datasource Switch → Doc Prep: feeds · Prepared documents are indexed for retrieval
- App Entrypoint → Chat History: persists · Conversation state can be written to Cosmos DB
- Chat History → History Store: stores in · Chat transcripts are stored separately from retrieval data
- Infra Stack → App Service: provisions · Deployment stack includes application hosting
- Infra Stack → Search Service: provisions · Deployment stack includes search infrastructure
- Infra Stack → History Store: provisions · Deployment stack includes Cosmos DB storage
- App Service → App Entrypoint: runs · Production service hosts the Python backend
- Search Service → Azure Search: supports · Infrastructure backing for search retrieval