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