Skip to content

Commit c011b6e

Browse files
Copilotpamelafox
Copilot
and
pamelafox
committed
Add comprehensive Mermaid architecture diagrams and documentation
Co-authored-by: pamelafox <[email protected]>
1 parent 22c699f commit c011b6e

File tree

3 files changed

+204
-0
lines changed

3 files changed

+204
-0
lines changed

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,8 @@ The repo includes sample data so it's ready to try end to end. In this sample ap
7070

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

73+
📋 **[View detailed architecture documentation with interactive Mermaid diagrams](docs/architecture.md)**
74+
7375
## Azure account requirements
7476

7577
**IMPORTANT:** In order to deploy and run this example, you'll need:

‎docs/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
Consult the main [README](../README.md) for general information about the project.
44
These are advanced topics that are not necessary for a basic deployment.
55

6+
- **[Architecture Overview](architecture.md)** - Detailed diagrams and component descriptions
7+
68
- Deploying:
79
- [Troubleshooting deployment](docs/deploy_troubleshooting.md)
810
- [Debugging the app on App Service](appservice.md)

‎docs/architecture.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Application Architecture
2+
3+
This document provides a detailed architectural overview of the Azure Search OpenAI demo application using Mermaid diagrams.
4+
5+
## Overview
6+
7+
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.
8+
9+
## Architecture Diagram
10+
11+
The following diagram illustrates the complete architecture including user interaction flow, application components, and Azure services:
12+
13+
```mermaid
14+
graph TB
15+
subgraph "User Interface"
16+
User[👤 User]
17+
Browser[🌐 Web Browser]
18+
end
19+
20+
subgraph "Application Layer"
21+
subgraph "Frontend"
22+
React[⚛️ React/TypeScript App<br/>- Chat Interface<br/>- Settings Panel<br/>- Citation Display]
23+
end
24+
25+
subgraph "Backend"
26+
API[🐍 Python API<br/>Flask/Quart<br/>- Chat Endpoints<br/>- Document Upload<br/>- Authentication]
27+
28+
subgraph "Approaches"
29+
CRR[ChatReadRetrieveRead<br/>Approach]
30+
RTR[RetrieveThenRead<br/>Approach]
31+
Vision[Vision Approaches<br/>GPT-4V Support]
32+
end
33+
end
34+
end
35+
36+
subgraph "Azure Services"
37+
subgraph "AI Services"
38+
OpenAI[🤖 Azure OpenAI<br/>- GPT-4 Mini<br/>- Text Embeddings<br/>- GPT-4V (optional)]
39+
Search[🔍 Azure AI Search<br/>- Vector Search<br/>- Semantic Ranking<br/>- Full-text Search]
40+
DocIntel[📄 Azure Document<br/>Intelligence<br/>- Text Extraction<br/>- Layout Analysis]
41+
Vision2[👁️ Azure Computer Vision<br/>(optional)]
42+
Speech[🎤 Azure Speech<br/>Services (optional)]
43+
end
44+
45+
subgraph "Storage & Data"
46+
Blob[💾 Azure Blob Storage<br/>- Document Storage<br/>- User Uploads]
47+
Cosmos[🗃️ Azure Cosmos DB<br/>- Chat History<br/>(optional)]
48+
end
49+
50+
subgraph "Platform Services"
51+
ContainerApps[📦 Azure Container Apps<br/>or App Service<br/>- Application Hosting]
52+
AppInsights[📊 Application Insights<br/>- Monitoring<br/>- Telemetry]
53+
KeyVault[🔐 Azure Key Vault<br/>- Secrets Management]
54+
end
55+
end
56+
57+
subgraph "Data Processing"
58+
PrepDocs[⚙️ Document Preparation<br/>Pipeline<br/>- Text Extraction<br/>- Chunking<br/>- Embedding Generation<br/>- Indexing]
59+
end
60+
61+
%% User Interaction Flow
62+
User -.-> Browser
63+
Browser <--> React
64+
React <--> API
65+
66+
%% Backend Processing
67+
API --> CRR
68+
API --> RTR
69+
API --> Vision
70+
71+
%% Azure Service Connections
72+
API <--> OpenAI
73+
API <--> Search
74+
API <--> Blob
75+
API <--> Cosmos
76+
API <--> Speech
77+
78+
%% Document Processing Flow
79+
Blob --> PrepDocs
80+
PrepDocs --> DocIntel
81+
PrepDocs --> OpenAI
82+
PrepDocs --> Search
83+
84+
%% Vision Processing
85+
Vision --> Vision2
86+
Vision --> OpenAI
87+
88+
%% Platform Integration
89+
ContainerApps --> API
90+
API --> AppInsights
91+
API --> KeyVault
92+
93+
%% Styling
94+
classDef userLayer fill:#e1f5fe
95+
classDef appLayer fill:#f3e5f5
96+
classDef azureAI fill:#e8f5e8
97+
classDef azureStorage fill:#fff3e0
98+
classDef azurePlatform fill:#fce4ec
99+
classDef processing fill:#f1f8e9
100+
101+
class User,Browser userLayer
102+
class React,API,CRR,RTR,Vision appLayer
103+
class OpenAI,Search,DocIntel,Vision2,Speech azureAI
104+
class Blob,Cosmos azureStorage
105+
class ContainerApps,AppInsights,KeyVault azurePlatform
106+
class PrepDocs processing
107+
```
108+
109+
## Chat Query Flow
110+
111+
The following sequence diagram shows how a user query is processed:
112+
113+
```mermaid
114+
sequenceDiagram
115+
participant U as User
116+
participant F as Frontend
117+
participant B as Backend API
118+
participant S as Azure AI Search
119+
participant O as Azure OpenAI
120+
participant Bl as Blob Storage
121+
122+
U->>F: Enter question
123+
F->>B: POST /chat with query
124+
B->>S: Search for relevant documents
125+
S-->>B: Return search results with citations
126+
B->>O: Send query + context to GPT model
127+
O-->>B: Return AI response
128+
B->>Bl: Log interaction (optional)
129+
B-->>F: Return response with citations
130+
F-->>U: Display answer with sources
131+
```
132+
133+
## Document Ingestion Flow
134+
135+
The following diagram shows how documents are processed and indexed:
136+
137+
```mermaid
138+
sequenceDiagram
139+
participant D as Documents
140+
participant Bl as Blob Storage
141+
participant P as PrepDocs Script
142+
participant DI as Document Intelligence
143+
participant O as Azure OpenAI
144+
participant S as Azure AI Search
145+
146+
D->>Bl: Upload documents
147+
P->>Bl: Read documents
148+
P->>DI: Extract text and layout
149+
DI-->>P: Return extracted content
150+
P->>P: Split into chunks
151+
P->>O: Generate embeddings
152+
O-->>P: Return vector embeddings
153+
P->>S: Index documents with embeddings
154+
S-->>P: Confirm indexing complete
155+
```
156+
157+
## Key Components
158+
159+
### Frontend (React/TypeScript)
160+
161+
- **Chat Interface**: Main conversational UI
162+
- **Settings Panel**: Configuration options for AI behavior
163+
- **Citation Display**: Shows sources and references
164+
- **Authentication**: Optional user login integration
165+
166+
### Backend (Python)
167+
168+
- **API Layer**: RESTful endpoints for chat, search, and configuration
169+
- **Approach Patterns**: Different strategies for processing queries
170+
- `ChatReadRetrieveRead`: Multi-turn conversation with retrieval
171+
- `RetrieveThenRead`: Single-turn Q&A with retrieval
172+
- `Vision Approaches`: Support for image-based documents
173+
- **Authentication**: Optional integration with Azure Active Directory
174+
175+
### Azure Services Integration
176+
177+
- **Azure OpenAI**: Powers the conversational AI capabilities
178+
- **Azure AI Search**: Provides semantic and vector search over documents
179+
- **Azure Blob Storage**: Stores original documents and processed content
180+
- **Azure Container Apps**: Hosts the application with automatic scaling
181+
- **Application Insights**: Provides monitoring and telemetry
182+
183+
## Optional Features
184+
185+
The architecture supports several optional features that can be enabled:
186+
187+
- **GPT-4 with Vision**: Process image-heavy documents
188+
- **Speech Services**: Voice input/output capabilities
189+
- **Chat History**: Persistent conversation storage in Cosmos DB
190+
- **Authentication**: User login and access control
191+
- **Private Endpoints**: Network isolation for enhanced security
192+
193+
## Deployment Options
194+
195+
The application can be deployed using:
196+
197+
- **Azure Container Apps** (default): Serverless container hosting
198+
- **Azure App Service**: Traditional PaaS hosting option
199+
200+
Both options support the same feature set and can be configured through the Azure Developer CLI (azd).

0 commit comments

Comments
 (0)