Add comprehensive Mermaid architecture diagrams for application documentation #2653

Copilot · 2025-07-29T18:54:41Z

This PR adds detailed Mermaid diagrams to visualize the architecture of the Azure Search OpenAI demo application, providing a maintainable and version-controlled alternative to static PNG diagrams.

Changes Made

New Architecture Documentation (`docs/architecture.md`)

Created comprehensive documentation with three detailed Mermaid diagrams:

Main Architecture Diagram - Shows the complete system architecture including:
- User interface layer (browser, React frontend)
- Application layer (Python backend with chat approaches)
- Azure services (OpenAI, AI Search, Blob Storage, Container Apps, etc.)
- Data flow connections between all components
Chat Query Flow - Sequence diagram illustrating:
- User question processing
- Document retrieval from Azure AI Search
- OpenAI integration for response generation
- Citation and source handling
Document Ingestion Flow - Sequence diagram showing:
- Document upload to Blob Storage
- Text extraction via Document Intelligence
- Embedding generation through OpenAI
- Indexing in Azure AI Search

Updated Documentation Links

README.md: Added architecture documentation link to the main documentation list
docs/README.md: Added architecture overview to the documentation index

Diagram Syntax Fixes

Fixed Mermaid parse errors by removing problematic dash characters from node labels
Ensured all diagrams render correctly in GitHub's Mermaid renderer
Updated service names to current Azure naming conventions (Azure AI Vision)

Benefits

Maintainable: Text-based diagrams can be easily updated with code changes
Version Controlled: Architecture changes are tracked in git history
Interactive: GitHub renders Mermaid with zoom and pan capabilities
Accessible: Text-based format works with screen readers
Comprehensive: Covers user flows, system components, and data processing pipelines

The diagrams complement the existing PNG architecture image by providing detailed, interactive visualizations that can evolve with the codebase.

Fixes #2598.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: pamelafox <[email protected]>

pamelafox · 2025-07-29T23:25:39Z

docs/README.md

 Consult the main [README](../README.md) for general information about the project.
 These are advanced topics that are not necessary for a basic deployment.

+- **[Architecture Overview](architecture.md)** - Detailed diagrams and component descriptions


Move the link to the list below, above "HTTP Protocol"

Moved the Architecture Overview link to the list above HTTP Protocol as requested (commit 481c539).

Co-authored-by: pamelafox <[email protected]>

pamelafox · 2025-07-29T23:26:05Z

README.md


 ![RAG Architecture](docs/images/appcomponents.png)

+📋 **[View detailed architecture documentation with interactive Mermaid diagrams](docs/architecture.md)**


Move the link to the documentation list later in the README

Moved the architecture documentation link to the documentation list later in the README as requested (commit 0ebaa1f).

pamelafox · 2025-07-29T23:26:37Z

docs/architecture.md

+
+The following diagram illustrates the complete architecture including user interaction flow, application components, and Azure services:
+
+```mermaid


Error:

Parse error on line 25:
...ddings
- GPT-4V (optional)]
-----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'PS'

For more information, see https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

Fixed the Mermaid diagram parse error by removing the problematic vision approaches syntax. The diagram should now render correctly (commit 0ebaa1f).

It still says--

Unable to render rich display

Parse error on line 24:
...ddings
- GPT-4V (optional)]
-----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'PS'

For more information, see https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

Fixed the Mermaid parse error by removing parentheses from the GPT-4V text. Changed "GPT-4V (optional)" to "GPT-4 Vision" to resolve the syntax issue (commit a7bd26d).

Still error'ing

Parse error on line 27:
...Azure AI Vision
(optional)]
-----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'PS'

For more information, see https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

@copilot Fix mermaid parse error

Fixed the Mermaid parse error by removing parentheses from the optional service labels. Changed "(optional)" to "optional" for Azure AI Vision, Azure Speech Services, and Azure Cosmos DB (commit 7e033d7).

Fixed the Mermaid parse error by removing dashes from node labels throughout the diagram. The issue was caused by the dash characters (-) within the node text, which Mermaid was interpreting as syntax elements rather than display text (commit 7e9761e).

pamelafox · 2025-07-29T23:27:00Z

docs/architecture.md

@@ -0,0 +1,200 @@
+# Application Architecture


Suggested change

# Application Architecture

# RAG Chat: Application Architecture

All documents use "RAG Chat" as prefix in title, I believe

Updated the title to "RAG Chat: Application Architecture" to match the pattern used in other documents (commit 0ebaa1f).

pamelafox · 2025-07-29T23:27:42Z

docs/architecture.md

+
+This document provides a detailed architectural overview of the Azure Search OpenAI demo application using Mermaid diagrams.
+
+## Overview


Combine Overview with intro sentence, remove mention of Mermaid

Link back to README as well, for people who find this that want to get started with the repo.

Combined the Overview with the intro sentence, removed mention of Mermaid, and added a link back to README as requested (commit 0ebaa1f).

Added link back to README for people who find this document and want to get started with the repo (commit 0ebaa1f).

pamelafox · 2025-07-29T23:27:58Z

docs/architecture.md

+            OpenAI[🤖 Azure OpenAI<br/>- GPT-4 Mini<br/>- Text Embeddings<br/>- GPT-4V (optional)]
+            Search[🔍 Azure AI Search<br/>- Vector Search<br/>- Semantic Ranking<br/>- Full-text Search]
+            DocIntel[📄 Azure Document<br/>Intelligence<br/>- Text Extraction<br/>- Layout Analysis]
+            Vision2[👁️ Azure Computer Vision<br/>(optional)]


Rename "Azure Computer Vision" to "Azure AI Vision"

Renamed "Azure Computer Vision" to "Azure AI Vision" in the diagram (commit 0ebaa1f).

pamelafox · 2025-07-29T23:28:20Z

docs/architecture.md

+- **Approach Patterns**: Different strategies for processing queries
+  - `ChatReadRetrieveRead`: Multi-turn conversation with retrieval
+  - `RetrieveThenRead`: Single-turn Q&A with retrieval
+  - `Vision Approaches`: Support for image-based documents


Remove "Vision Approaches" as they're going away soon

Removed "Vision Approaches" from both the diagram and documentation as they're going away soon (commit 0ebaa1f).

pamelafox · 2025-07-29T23:28:30Z

docs/architecture.md

+
+### Backend (Python)
+
+- **API Layer**: RESTful endpoints for chat, search, and configuration


Link to HTTP protocol doc here

Added link to the HTTP protocol documentation in the Backend section (commit 0ebaa1f).

pamelafox · 2025-07-29T23:29:06Z

docs/architecture.md

+- **Azure OpenAI**: Powers the conversational AI capabilities
+- **Azure AI Search**: Provides semantic and vector search over documents
+- **Azure Blob Storage**: Stores original documents and processed content
+- **Azure Container Apps**: Hosts the application with automatic scaling


Remove Container Apps from this list since its below

Removed Container Apps from the Azure Services Integration list since it's mentioned separately in the Deployment Options section (commit 0ebaa1f).

pamelafox · 2025-07-29T23:29:25Z

docs/architecture.md

+
+## Optional Features
+
+The architecture supports several optional features that can be enabled:


Link to the guide about optional features

Added link to the optional features guide in the Optional Features section (commit 0ebaa1f).

pamelafox · 2025-07-29T23:29:34Z

docs/architecture.md

+The application can be deployed using:
+
+- **Azure Container Apps** (default): Serverless container hosting
+- **Azure App Service**: Traditional PaaS hosting option


Link to doc about app service hosting

Added link to the App Service hosting guide in the Deployment Options section (commit 0ebaa1f).

Co-authored-by: pamelafox <[email protected]>

pamelafox · 2025-07-29T23:49:52Z

README.md

  - [Sharing deployment environments](docs/sharing_environments.md)
 - [Local development](docs/localdev.md)
 - [Customizing the app](docs/customization.md)
+- **[Architecture documentation with interactive diagrams](docs/architecture.md)**


Don't bold it

Removed bold formatting from the architecture link in the documentation list (commit a7bd26d).

pamelafox · 2025-07-29T23:50:38Z

docs/architecture.md

@@ -0,0 +1,190 @@
+# RAG Chat: Application Architecture
+
+This document provides a detailed architectural overview of the Azure Search OpenAI demo application. The Azure Search OpenAI demo is a Retrieval Augmented Generation (RAG) application that creates a ChatGPT-like experience over your own documents. It combines Azure OpenAI Service for AI capabilities with Azure AI Search for document indexing and retrieval.


Suggested change

This document provides a detailed architectural overview of the Azure Search OpenAI demo application. The Azure Search OpenAI demo is a Retrieval Augmented Generation (RAG) application that creates a ChatGPT-like experience over your own documents. It combines Azure OpenAI Service for AI capabilities with Azure AI Search for document indexing and retrieval.

This document provides a detailed architectural overview of this application, a Retrieval Augmented Generation (RAG) application that creates a ChatGPT-like experience over your own documents. It combines Azure OpenAI Service for AI capabilities with Azure AI Search for document indexing and retrieval.

Updated the intro text to be more concise and focused on "this application" (commit a7bd26d).

pamelafox · 2025-07-29T23:51:10Z

docs/architecture.md

+
+The following diagram illustrates the complete architecture including user interaction flow, application components, and Azure services:
+
+```mermaid


It still says--

Unable to render rich display

Parse error on line 24:
...ddings
- GPT-4V (optional)]
-----------------------^
Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'PS'

For more information, see https://docs.github.com/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams#creating-mermaid-diagrams

Co-authored-by: pamelafox <[email protected]>

docs/README.md

README.md

… labels Co-authored-by: pamelafox <[email protected]>

Co-authored-by: pamelafox <[email protected]>

…entation (Azure-Samples#2653) * Initial plan * Add comprehensive Mermaid architecture diagrams and documentation Co-authored-by: pamelafox <[email protected]> * Move Architecture Overview link to list above HTTP Protocol Co-authored-by: pamelafox <[email protected]> * Address PR feedback: fix Mermaid syntax, update architecture docs Co-authored-by: pamelafox <[email protected]> * Fix formatting and Mermaid syntax issues per PR feedback Co-authored-by: pamelafox <[email protected]> * Update README.md * Update docs/README.md * Fix Mermaid parse error by removing parentheses from optional service labels Co-authored-by: pamelafox <[email protected]> * Fix Mermaid parse error by removing dashes from node labels Co-authored-by: pamelafox <[email protected]> --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: pamelafox <[email protected]> Co-authored-by: Pamela Fox <[email protected]>

Initial plan

22c699f

Copilot AI assigned Copilot and pamelafox Jul 29, 2025

Copilot started work on behalf of pamelafox July 29, 2025 18:54 View session

Add comprehensive Mermaid architecture diagrams and documentation

c011b6e

Co-authored-by: pamelafox <[email protected]>

Copilot AI changed the title ~~[WIP] Create a the mermaid diagram for the architecture of this app~~ Add comprehensive Mermaid architecture diagrams for application documentation Jul 29, 2025

Copilot AI requested a review from pamelafox July 29, 2025 19:14

Copilot finished work on behalf of pamelafox July 29, 2025 19:14

pamelafox reviewed Jul 29, 2025

View reviewed changes

Copilot started work on behalf of pamelafox July 29, 2025 23:25 View session

Move Architecture Overview link to list above HTTP Protocol

481c539

Co-authored-by: pamelafox <[email protected]>

Copilot AI requested a review from pamelafox July 29, 2025 23:28

Copilot finished work on behalf of pamelafox July 29, 2025 23:29

pamelafox requested changes Jul 29, 2025

View reviewed changes

Copilot started work on behalf of pamelafox July 29, 2025 23:30 View session

Address PR feedback: fix Mermaid syntax, update architecture docs

0ebaa1f

Co-authored-by: pamelafox <[email protected]>

Copilot finished work on behalf of pamelafox July 29, 2025 23:44

Copilot AI requested a review from pamelafox July 29, 2025 23:44

pamelafox requested changes Jul 29, 2025

View reviewed changes

Copilot started work on behalf of pamelafox July 29, 2025 23:51 View session

Fix formatting and Mermaid syntax issues per PR feedback

a7bd26d

Co-authored-by: pamelafox <[email protected]>

Copilot AI requested a review from pamelafox July 29, 2025 23:56

Copilot finished work on behalf of pamelafox July 29, 2025 23:56

pamelafox reviewed Jul 30, 2025

View reviewed changes

docs/README.md Outdated Show resolved Hide resolved

pamelafox reviewed Jul 30, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

Copilot started work on behalf of pamelafox July 30, 2025 03:27 View session

pamelafox and others added 3 commits July 29, 2025 20:27

Update README.md

57f0c93

Update docs/README.md

1be53c3

Fix Mermaid parse error by removing parentheses from optional service…

7e033d7

… labels Co-authored-by: pamelafox <[email protected]>

Copilot AI requested a review from pamelafox July 30, 2025 03:33

Copilot finished work on behalf of pamelafox July 30, 2025 03:33

Copilot started work on behalf of pamelafox July 30, 2025 03:33 View session

Fix Mermaid parse error by removing dashes from node labels

7e9761e

Co-authored-by: pamelafox <[email protected]>

Copilot finished work on behalf of pamelafox July 30, 2025 03:41

Merge branch 'main' into copilot/fix-2598

68f4172

pamelafox marked this pull request as ready for review July 30, 2025 05:05

pamelafox approved these changes Jul 30, 2025

View reviewed changes

pamelafox merged commit b5b4090 into main Jul 30, 2025
5 checks passed


		![RAG Architecture](docs/images/appcomponents.png)

		📋 [View detailed architecture documentation with interactive Mermaid diagrams](docs/architecture.md)


		The following diagram illustrates the complete architecture including user interaction flow, application components, and Azure services:

		```mermaid

	# Application Architecture
	# RAG Chat: Application Architecture


		This document provides a detailed architectural overview of the Azure Search OpenAI demo application using Mermaid diagrams.

		## Overview


		### Backend (Python)

		- API Layer: RESTful endpoints for chat, search, and configuration


		## Optional Features

		The architecture supports several optional features that can be enabled:

		@@ -0,0 +1,190 @@
		# RAG Chat: Application Architecture

		This document provides a detailed architectural overview of the Azure Search OpenAI demo application. The Azure Search OpenAI demo is a Retrieval Augmented Generation (RAG) application that creates a ChatGPT-like experience over your own documents. It combines Azure OpenAI Service for AI capabilities with Azure AI Search for document indexing and retrieval.

Add comprehensive Mermaid architecture diagrams for application documentation #2653

Add comprehensive Mermaid architecture diagrams for application documentation #2653

Uh oh!

Conversation

Copilot AI commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes Made

New Architecture Documentation (docs/architecture.md)

Updated Documentation Links

Diagram Syntax Fixes

Benefits

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 30, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Copilot AI commented Jul 29, 2025 •

edited

Loading

New Architecture Documentation (`docs/architecture.md`)