How amrelsehemy/sample-app-aoai-chatgpt works
Project type and purpose
• This is a full-stack sample chat application that integrates with Azure OpenAI and (optionally) Azure Cognitive Search and Cosmos DB to provide a “chat on your data” experience.
• The frontend is a React/Vite single-page app; the backend is a Python/Flask service. Infra as code (Bicep and ARM templates) and data-preparation scripts support deployment and document ingestion.
File structure
• Top-level:
• app.py – Flask entrypoint
• WebApp.Dockerfile / dockerignore – containerizing the app
• azure.yaml, infra/*.bicep, infrastructure/deployment.json – Azure resource definitions (App Service, Cosmos, Search, Storage, AI)
• scripts/ – ingestion, embedding, pipeline, auth init/update scripts
• frontend/ – React code, TS config, assets, components, pages
• backend/auth and backend/history – auth utilities and Cosmos DB history service
• Patterns:
• Clear separation of concerns: “frontend” vs. “backend” vs. “infra” vs. “scripts”
• Modular React components, centralized state via AppProvider/AppReducer
• API folder under src for typed HTTP interactions with Flask
• Bicep modules mirror Azure resource categories (AI, database, host, search, storage, security)
README for additional insights
• Describes deployment options (Azure Developer CLI, one-click, local)
• Environment variables drive Azure OpenAI, Cognitive Search, Cosmos DB integration
• Data ingestion flow uses scripts to chunk, embed, and push documents to a search index
• Optional chat history persistence in Cosmos DB via backend/history/cosmosdbservice.py
• Authentication guidance highlights external identity provider integration
Main components and relationships
A. User’s browser (Client)
B. Frontend SPA (React/Vite)
– Static assets served by Flask (or App Service static hosting)
– Calls HTTP endpoints on Flask backend
C. Backend API (Flask in app.py)
– /chat endpoint orchestrates requests to Azure OpenAI
– Uses auth_utils to validate user identity via external provider tokens
– Optionally logs chat history via cosmosdbservice to Azure Cosmos DB
– Optionally queries Azure Cognitive Search for on-your-data retrieval
D. Azure OpenAI Service
– Chat completions and embeddings
E. Azure Cognitive Search
– Stores and indexes ingested documents
– Provides retrieval results passed back to OpenAI as context
F. Azure Cosmos DB
– Persists conversation history
G. Azure Blob Storage (optional)
– Stores source documents referenced by Cognitive Search
H. Deployment/Infra layer
– Bicep modules deploy App Service, Cosmos, Search, Storage, Cognitive Services
I. Data-Preparation Pipeline (scripts folder)
– Chunk documents → generate embeddings → push to Cognitive Search index
Interactions:
• Frontend → HTTP requests → Backend
• Backend → SDK/API calls → Azure OpenAI
• Backend → HTTP calls → Azure Cognitive Search
• Backend → SDK calls → Cosmos DB
• Scripts → SDK calls → Cognitive Search & possibly Blob Storage during ingest
• Deployment templates → Azure CLI/Portal → Deploy infra resources
• User sign-in via Identity Provider → token passed to backend/auth_utils
Architectural patterns & design principles
• Separation of concerns: clear divide between presentation, business logic, and data/persistence
• Modular IaC: reusable Bicep modules for each Azure service category
• Typed API layer in frontend for maintainable contract with backend
• Stateless backend: configurations via environment variables
• Optional asynchronous data pipeline for document ingestion
• Use of provider-agnostic auth_utils to abstract identity checks
• React context and reducer for application state management
Elements
• Green for Azure PaaS services (OpenAI, Search, Cosmos, Storage)
• Orange for IaC modules