diff --git a/README.md b/README.md index 343e659369..cbef4b7567 100644 --- a/README.md +++ b/README.md @@ -262,6 +262,7 @@ You can find extensive documentation in the [docs](docs/README.md) folder: - [Sharing deployment environments](docs/sharing_environments.md) - [Local development](docs/localdev.md) - [Customizing the app](docs/customization.md) +- [App architecture](docs/architecture.md) - [HTTP Protocol](docs/http_protocol.md) - [Data ingestion](docs/data_ingestion.md) - [Evaluation](docs/evaluation.md) diff --git a/docs/README.md b/docs/README.md index 56ec17bc45..d61625fe9d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,7 @@ These are advanced topics that are not necessary for a basic deployment. - [Sharing deployment environments](sharing_environments.md) - [Local development](localdev.md) - [Customizing the app](customization.md) +- [App architecture](architecture.md) - [HTTP Protocol](http_protocol.md) - [Data ingestion](data_ingestion.md) - [Evaluation](docs/evaluation.md) diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000000..d676363ea5 --- /dev/null +++ b/docs/architecture.md @@ -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
Chat Interface
Settings Panel
Citation Display] + end + + subgraph "Backend" + API[🐍 Python API
Flask/Quart
Chat Endpoints
Document Upload
Authentication] + + subgraph "Approaches" + CRR[ChatReadRetrieveRead
Approach] + RTR[RetrieveThenRead
Approach] + end + end + end + + subgraph "Azure Services" + subgraph "AI Services" + OpenAI[🤖 Azure OpenAI
GPT-4 Mini
Text Embeddings
GPT-4 Vision] + Search[🔍 Azure AI Search
Vector Search
Semantic Ranking
Full-text Search] + DocIntel[📄 Azure Document
Intelligence
Text Extraction
Layout Analysis] + Vision2[👁️ Azure AI Vision
optional] + Speech[🎤 Azure Speech
Services optional] + end + + subgraph "Storage & Data" + Blob[💾 Azure Blob Storage
Document Storage
User Uploads] + Cosmos[🗃️ Azure Cosmos DB
Chat History
optional] + end + + subgraph "Platform Services" + ContainerApps[📦 Azure Container Apps
or App Service
Application Hosting] + AppInsights[📊 Application Insights
Monitoring
Telemetry] + KeyVault[🔐 Azure Key Vault
Secrets Management] + end + end + + subgraph "Data Processing" + PrepDocs[⚙️ Document Preparation
Pipeline
Text Extraction
Chunking
Embedding Generation
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).