-
Notifications
You must be signed in to change notification settings - Fork 5k
Add comprehensive Mermaid architecture diagrams for application documentation #2653
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
22c699f
Initial plan
Copilot c011b6e
Add comprehensive Mermaid architecture diagrams and documentation
Copilot 481c539
Move Architecture Overview link to list above HTTP Protocol
Copilot 0ebaa1f
Address PR feedback: fix Mermaid syntax, update architecture docs
Copilot a7bd26d
Fix formatting and Mermaid syntax issues per PR feedback
Copilot 57f0c93
Update README.md
pamelafox 1be53c3
Update docs/README.md
pamelafox 7e033d7
Fix Mermaid parse error by removing parentheses from optional service…
Copilot 7e9761e
Fix Mermaid parse error by removing dashes from node labels
Copilot 68f4172
Merge branch 'main' into copilot/fix-2598
pamelafox File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,190 @@ | ||
| # RAG Chat: Application Architecture | ||
|
|
||
| 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. | ||
|
|
||
| For getting started with the application, see the main [README](../README.md). | ||
|
|
||
| ## Architecture Diagram | ||
|
|
||
| The following diagram illustrates the complete architecture including user interaction flow, application components, and Azure services: | ||
|
|
||
| ```mermaid | ||
| graph TB | ||
| subgraph "User Interface" | ||
| User[👤 User] | ||
| Browser[🌐 Web Browser] | ||
| end | ||
|
|
||
| subgraph "Application Layer" | ||
| subgraph "Frontend" | ||
| React[⚛️ React/TypeScript App<br/>Chat Interface<br/>Settings Panel<br/>Citation Display] | ||
| end | ||
|
|
||
| subgraph "Backend" | ||
| API[🐍 Python API<br/>Flask/Quart<br/>Chat Endpoints<br/>Document Upload<br/>Authentication] | ||
|
|
||
| subgraph "Approaches" | ||
| CRR[ChatReadRetrieveRead<br/>Approach] | ||
| RTR[RetrieveThenRead<br/>Approach] | ||
| end | ||
| end | ||
| end | ||
|
|
||
| subgraph "Azure Services" | ||
| subgraph "AI Services" | ||
| OpenAI[🤖 Azure OpenAI<br/>GPT-4 Mini<br/>Text Embeddings<br/>GPT-4 Vision] | ||
| 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 AI Vision<br/>optional] | ||
| Speech[🎤 Azure Speech<br/>Services optional] | ||
| end | ||
|
|
||
| subgraph "Storage & Data" | ||
| Blob[💾 Azure Blob Storage<br/>Document Storage<br/>User Uploads] | ||
| Cosmos[🗃️ Azure Cosmos DB<br/>Chat History<br/>optional] | ||
| end | ||
|
|
||
| subgraph "Platform Services" | ||
| ContainerApps[📦 Azure Container Apps<br/>or App Service<br/>Application Hosting] | ||
| AppInsights[📊 Application Insights<br/>Monitoring<br/>Telemetry] | ||
| KeyVault[🔐 Azure Key Vault<br/>Secrets Management] | ||
| end | ||
| end | ||
|
|
||
| subgraph "Data Processing" | ||
| PrepDocs[⚙️ Document Preparation<br/>Pipeline<br/>Text Extraction<br/>Chunking<br/>Embedding Generation<br/>Indexing] | ||
| end | ||
|
|
||
| %% User Interaction Flow | ||
| User -.-> Browser | ||
| Browser <--> React | ||
| React <--> API | ||
|
|
||
| %% Backend Processing | ||
| API --> CRR | ||
| API --> RTR | ||
|
|
||
| %% Azure Service Connections | ||
| API <--> OpenAI | ||
| API <--> Search | ||
| API <--> Blob | ||
| API <--> Cosmos | ||
| API <--> Speech | ||
|
|
||
| %% Document Processing Flow | ||
| Blob --> PrepDocs | ||
| PrepDocs --> DocIntel | ||
| PrepDocs --> OpenAI | ||
| PrepDocs --> Search | ||
|
|
||
| %% Platform Integration | ||
| ContainerApps --> API | ||
| API --> AppInsights | ||
| API --> KeyVault | ||
|
|
||
| %% Styling | ||
| classDef userLayer fill:#e1f5fe | ||
| classDef appLayer fill:#f3e5f5 | ||
| classDef azureAI fill:#e8f5e8 | ||
| classDef azureStorage fill:#fff3e0 | ||
| classDef azurePlatform fill:#fce4ec | ||
| classDef processing fill:#f1f8e9 | ||
|
|
||
| class User,Browser userLayer | ||
| class React,API,CRR,RTR appLayer | ||
| class OpenAI,Search,DocIntel,Vision2,Speech azureAI | ||
| class Blob,Cosmos azureStorage | ||
| class ContainerApps,AppInsights,KeyVault azurePlatform | ||
| class PrepDocs processing | ||
| ``` | ||
|
|
||
| ## Chat Query Flow | ||
|
|
||
| The following sequence diagram shows how a user query is processed: | ||
|
|
||
| ```mermaid | ||
| sequenceDiagram | ||
| participant U as User | ||
| participant F as Frontend | ||
| participant B as Backend API | ||
| participant S as Azure AI Search | ||
| participant O as Azure OpenAI | ||
| participant Bl as Blob Storage | ||
|
|
||
| U->>F: Enter question | ||
| F->>B: POST /chat with query | ||
| B->>S: Search for relevant documents | ||
| S-->>B: Return search results with citations | ||
| B->>O: Send query + context to GPT model | ||
| O-->>B: Return AI response | ||
| B->>Bl: Log interaction (optional) | ||
| B-->>F: Return response with citations | ||
| F-->>U: Display answer with sources | ||
| ``` | ||
|
|
||
| ## Document Ingestion Flow | ||
|
|
||
| The following diagram shows how documents are processed and indexed: | ||
|
|
||
| ```mermaid | ||
| sequenceDiagram | ||
| participant D as Documents | ||
| participant Bl as Blob Storage | ||
| participant P as PrepDocs Script | ||
| participant DI as Document Intelligence | ||
| participant O as Azure OpenAI | ||
| participant S as Azure AI Search | ||
|
|
||
| D->>Bl: Upload documents | ||
| P->>Bl: Read documents | ||
| P->>DI: Extract text and layout | ||
| DI-->>P: Return extracted content | ||
| P->>P: Split into chunks | ||
| P->>O: Generate embeddings | ||
| O-->>P: Return vector embeddings | ||
| P->>S: Index documents with embeddings | ||
| S-->>P: Confirm indexing complete | ||
| ``` | ||
|
|
||
| ## Key Components | ||
|
|
||
| ### Frontend (React/TypeScript) | ||
|
|
||
| - **Chat Interface**: Main conversational UI | ||
| - **Settings Panel**: Configuration options for AI behavior | ||
| - **Citation Display**: Shows sources and references | ||
| - **Authentication**: Optional user login integration | ||
|
|
||
| ### Backend (Python) | ||
|
|
||
| - **API Layer**: RESTful endpoints for chat, search, and configuration. See [HTTP Protocol](http_protocol.md) for detailed API documentation. | ||
| - **Approach Patterns**: Different strategies for processing queries | ||
| - `ChatReadRetrieveRead`: Multi-turn conversation with retrieval | ||
| - `RetrieveThenRead`: Single-turn Q&A with retrieval | ||
| - **Authentication**: Optional integration with Azure Active Directory | ||
|
|
||
| ### Azure Services Integration | ||
|
|
||
| - **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 | ||
| - **Application Insights**: Provides monitoring and telemetry | ||
|
|
||
| ## Optional Features | ||
|
|
||
| The architecture supports several optional features that can be enabled. For detailed configuration instructions, see the [optional features guide](deploy_features.md): | ||
|
|
||
| - **GPT-4 with Vision**: Process image-heavy documents | ||
| - **Speech Services**: Voice input/output capabilities | ||
| - **Chat History**: Persistent conversation storage in Cosmos DB | ||
| - **Authentication**: User login and access control | ||
| - **Private Endpoints**: Network isolation for enhanced security | ||
|
|
||
| ## Deployment Options | ||
|
|
||
| The application can be deployed using: | ||
|
|
||
| - **Azure Container Apps** (default): Serverless container hosting | ||
| - **Azure App Service**: Traditional PaaS hosting option. See the [App Service hosting guide](appservice.md) for detailed instructions. | ||
|
|
||
| Both options support the same feature set and can be configured through the Azure Developer CLI (azd). | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed the Mermaid diagram parse error by removing the problematic vision approaches syntax. The diagram should now render correctly (commit 0ebaa1f).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@copilot Fix mermaid parse error
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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).