# azure-samples/azure-openai-rag-workshop architecture

> Architecture diagram of the GitHub repository azure-samples/azure-openai-rag-workshop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure-samples/azure-openai-rag-workshop
- Repository: https://github.com/azure-samples/azure-openai-rag-workshop

## Overview

##### Project Type and Purpose
- This is a Node.js monorepo sample for a Retrieval-Augmented Generation (RAG) chatbot workshop.
- It demonstrates a full-stack AI application: a frontend SPA, a Fastify backend chat API, an ingestion pipeline service, and a trainer service.
- It’s hosted and deployed on Azure: Static Web Apps, Container Apps, Azure Cognitive Search (vector DB), OpenAI, Application Insights, Log Analytics, Container Registry.

##### High-Level Architectural Components
a. Frontend (src/frontend)
- Single-Page App (Vite + TypeScript) served by Azure Static Web Apps.
- Provides chat UI, calls the chat API over HTTP.
b. Chat Backend (src/backend)
- Fastify Node.js service with LangChain & OpenAI SDK.
- Exposes REST endpoints for chat interactions.
- Plugins coordinate Azure OpenAI calls, vector DB lookups via Azure Cognitive Search.
c. Ingestion Service (src/ingestion)
- Fastify Node.js service to ingest and index documents into the vector store.
- Implements file-based ingestion, multipart uploads, and text extraction.
d. Trainer Service (trainer/)
- Containerized service to run training/fine-tuning jobs, orchestrate additional AI pipelines.
- Similar plugin pattern, isolated infra (its own Bicep files).
e. Infrastructure as Code (infra/ and trainer/infra/)
- Bicep modules to provision: Static Web App, Container Apps Environment, Container Registry, Container Apps for each service, Azure Cognitive Search, Cognitive Services, Managed Identities, Application Insights, Log Analytics, RBAC roles.
f. Deployment & CI/CD
- GitHub Actions workflows for packaging, docs, slides, deploying via `azd up`.
- Docker Compose for local orchestration, DevContainer for local development.

##### Relationships & Data Flows
- User browser → Static Web App (serves assets) → Chat API (HTTPS).
- Chat API → Azure Cognitive Search (vector similarity search) → OpenAI (completion).
- Ingestion Service → Azure Cognitive Search (indexes documents).
- Trainer Service → OpenAI (fine-tuning/training endpoints) and/or Cognitive Services.
- All services run in Container Apps and pull images from Azure Container Registry.
- App Insights & Log Analytics gather logs/metrics from Container Apps.

##### Architectural Patterns & Principles
- Monorepo with clear separation of concerns (frontend, backend, ingestion, trainer).
- Plugin architecture in each service for extensibility (src/plugins).
- Infrastructure as code (reusable Bicep modules).
- Container-first design: each service Dockerized; orchestration via Container Apps / Docker Compose.
- CI/CD pipelines for docs, slides, package builds, and deployments.

##### Summary
- Expand to backend integration with vector DB and AI.
- Ingestion and training as side-car microservices.
- Surround with Azure infra and DevOps.
- Reference docs/assets/architecture.excalidraw as a baseline, then augment with your own notation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        GA["GitHub Actions"]:::infra
    end

    %% Azure Resource Group
    subgraph "Azure Resource Group"
        Browser["User Browser"]:::frontend
        SWA["Azure Static Web App"]:::frontend

        subgraph "Container Apps"
            Chat["Fastify Chat API"]:::service
            Ingest["Ingestion Service"]:::service
            Trainer["Trainer Service"]:::service
        end

        subgraph "Data & AI"
            Search["Azure Cognitive Search"]:::data
            OpenAI["Azure OpenAI"]:::ai
            CogServ["Azure Cognitive Services"]:::ai
        end

        subgraph "DevOps & Monitoring"
            ACR["Azure Container Registry"]:::infra
            Insights["Application Insights"]:::infra
            Logs["Log Analytics"]:::infra
        end
    end

    %% User Flow
    Browser -->|HTTPS| SWA
    SWA -->|HTTP REST| Chat
    Chat -->|vector query| Search
    Search -->|results| Chat
    Chat -->|completion| OpenAI
    OpenAI -->|response| Chat
    Chat -->|HTTP response| SWA
    SWA -->|render UI| Browser

    %% Ingestion Flow
    Ingest -->|async index| Search

    %% Trainer Flow
    Trainer -->|fine-tuning| OpenAI
    Trainer -->|AI pipelines| CogServ

    %% Container Image Pulls
    ACR -->|pull image| Chat
    ACR -->|pull image| Ingest
    ACR -->|pull image| Trainer

    %% Monitoring
    Chat -->|logs/metrics| Insights
    Chat -->|logs/metrics| Logs
    Ingest -->|logs/metrics| Insights
    Ingest -->|logs/metrics| Logs
    Trainer -->|logs/metrics| Insights
    Trainer -->|logs/metrics| Logs

    %% CI/CD Deployments
    GA -->|package & deploy| SWA
    GA -->|package & deploy| Chat
    GA -->|package & deploy| Ingest
    GA -->|package & deploy| Trainer
    GA -->|push images| ACR

    %% Click Events
    click GA "https://github.com/azure-samples/azure-openai-rag-workshop/tree/main/.github/workflows"
    click srcfrontend "https://github.com/azure-samples/azure-openai-rag-workshop/tree/main/src/frontend"
    click Chat "https://github.com/azure-samples/azure-openai-rag-workshop/tree/main/src/backend"
    click Ingest "https://github.com/azure-samples/azure-openai-rag-workshop/tree/main/src/ingestion"
    click Trainer "https://github.com/azure-samples/azure-openai-rag-workshop/tree/main/trainer"
    click Infra "https://github.com/azure-samples/azure-openai-rag-workshop/tree/main/infra"
    click TrainerInfra "https://github.com/azure-samples/azure-openai-rag-workshop/tree/main/trainer/infra"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#0062cc,color:#0062cc
    classDef service fill:#d4edda,stroke:#155724,color:#155724
    classDef data fill:#e2d9f3,stroke:#633974,color:#633974
    classDef ai fill:#fff3cd,stroke:#856404,color:#856404
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
