# amrelsehemy/sample-app-aoai-chatgpt architecture

> Architecture diagram of the GitHub repository amrelsehemy/sample-app-aoai-chatgpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amrelsehemy/sample-app-aoai-chatgpt
- Repository: https://github.com/amrelsehemy/sample-app-aoai-chatgpt

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Browser["Client (Browser)"]:::code
    click Browser "https://github.com/amrelsehemy/sample-app-aoai-chatgpt/blob/main/frontend/index.html"

    %% Frontend
    SPA["Frontend SPA<br/>React, Vite, TS"]:::code
    click SPA "https://github.com/amrelsehemy/sample-app-aoai-chatgpt/blob/main/frontend/src/index.tsx"

    APILayer["Typed HTTP Client"]:::code
    click APILayer "https://github.com/amrelsehemy/sample-app-aoai-chatgpt/blob/main/frontend/src/api/index.ts"

    %% Backend
    Backend["Flask API (app.py)"]:::code
    click Backend "https://github.com/amrelsehemy/sample-app-aoai-chatgpt/blob/main/app.py"

    AuthUtils["Auth Utilities"]:::code
    click AuthUtils "https://github.com/amrelsehemy/sample-app-aoai-chatgpt/blob/main/backend/auth/auth_utils.py"

    HistoryService["Chat History Service"]:::code
    click HistoryService "https://github.com/amrelsehemy/sample-app-aoai-chatgpt/blob/main/backend/history/cosmosdbservice.py"

    %% Azure Services
    OpenAI["Azure OpenAI Service"]:::azure
    Search["Azure Cognitive Search"]:::azure
    Cosmos["Azure Cosmos DB"]:::azure
    Storage["Azure Blob Storage"]:::azure_optional

    %% Data Pipeline
    Pipeline["Data-Preparation Pipeline<br/>(chunk, embed, push)"]:::code
    click Pipeline "https://github.com/amrelsehemy/sample-app-aoai-chatgpt/blob/main/scripts/data_preparation.py"

    %% Infrastructure as Code
    subgraph "Infra as Code" 
        direction TB
        Infra["Bicep & ARM Templates"]:::iac
        click Infra "https://github.com/amrelsehemy/sample-app-aoai-chatgpt/blob/main/infra/main.bicep"
    end

    %% Relationships
    Browser -->|"loads SPA"| SPA
    SPA -->|"uses HTTP client"| APILayer
    APILayer -->|"POST /chat"| Backend

    Backend -->|"validates token"| AuthUtils
    Backend -->|"optional: log chat"| HistoryService
    Backend -->|"calls completions"| OpenAI
    Backend -->|"retrieves context"| Search
    Backend -->|"persists history"| Cosmos

    Pipeline -->|"push data"| Search
    Pipeline -->|"store docs"| Storage

    Infra --> OpenAI
    Infra --> Search
    Infra --> Cosmos
    Infra --> Storage

    %% Styles
    classDef code fill:#D0E6FF,stroke:#0366d6,color:#000;
    classDef azure fill:#D5F5E3,stroke:#27AE60,color:#000;
    classDef azure_optional fill:#FCF3CF,stroke-dasharray:5 5,stroke:#F1C40F,color:#000;
    classDef iac fill:#FDEBD0,stroke:#E67E22,color:#000;
```
