# azure-samples/rag-postgres-openai-python architecture

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

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

## Overview

##### Overall Project Identification
- Project Type: A full-stack chat application.
- Purpose: To allow users to interact via chat with an AI that interprets queries about PostgreSQL database records. It combines vectorized search with traditional full text, performs query rewriting (e.g., using reciprocal rank fusion), and leverages both OpenAI and Azure OpenAI models.
- Deployment Target: Azure Container Apps, Azure PostgreSQL Flexible Server, Azure OpenAI, with comprehensive CI/CD using GitHub Actions.

##### Main Components
a. Frontend Component:
- Built with React and FluentUI (notice folders under src/frontend).
- Includes static assets, API integration (see API layers in src/frontend/src/api), and client-side routing.
- Depicts hot reloading and build system (Vite, npm scripts).

b. Backend Component:
- Written in Python using FastAPI (located in src/backend/fastapi_app).
- Contains API endpoints (routes inside src/backend/fastapi_app/routes) handling both API calls and static file serving.
- Implements functionality for embeddings, vector search using pgvector, query rewriting, and integration with PostgreSQL.
- Also manages database seeding and configuration (scripts like setup_postgres_database.py).

c. Database Component:
- PostgreSQL database with pgvector extension for vector search.
- Represents both vector and full text search capabilities.
- Includes configuration and setup scripts (SQL setup files and seed data under src/backend/fastapi_app/seed_data.json).

d. Infrastructure & Deployment:
- Azure-specific deployments using Bicep files (in the infra directory).
- Resources for container apps, PostgreSQL, AI services, monitoring (App Insights, Log Analytics), and security (managed identities).
- GitHub Actions workflows for continuous integration and deployment (files under .github/workflows).
- Docker and Dev Container configurations (.devcontainer folder) that enable reproducible development environments.
- Scripts to assist with environment setup (scripts folder) and load testing (locustfile.py).

e. Evaluation and Testing:
- Testing infrastructure defined under tests/ (unit tests, E2E tests, snapshot tests).
- Evaluation scripts (in the evals folder) that automate model quality and safety assessments.

##### Relationships and Interactions
- Backend’s interaction with PostgreSQL for data retrieval and embedding updates.
- Integration flows where the backend calls external APIs (e.g., OpenAI or Azure OpenAI endpoints) for processing.
- Communication between the deployed containers (using Docker or Azure Container Apps) and the Azure infrastructure (e.g., managed identity authentication between services).
- GitHub Actions and deployment pipelines (CI/CD) that automatically build, test, and deploy the application.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly distinguish between the client (React frontend) and the server (FastAPI backend).
- Microservices/Modular Architecture: Even though this isn’t a distributed set of microservices, note the modular organization (separate directories for API routing, embeddings, prompt management, and utilities).
- DevOps and Infrastructure as Code: Emphasize the usage of Bicep for resource provisioning in Azure and GitHub Actions for continuous testing and security scans.
- Cloud-Native Design: Highlight the integration with Azure services for databases, AI models, monitoring, and identity management.

- Drill down into individual components (frontend and backend) and then further into how backend services interact with the database and external services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U["User Browser"]:::external

    subgraph "Frontend Layer"
        F0["Frontend Component (React & FluentUI)"]:::frontend
        F1["API Integration (index.ts, models.ts)"]:::frontend
        F1 --> F0
    end

    subgraph "Backend Layer"
        B["Backend Component (FastAPI)"]:::backend
        B1["API Routes"]:::backend
        B2["Embeddings"]:::backend
        B3["OpenAI Clients"]:::backend
        B4["Query Rewriter"]:::backend
        B5["RAG Advanced"]:::backend
        B6["RAG Base"]:::backend
        B7["RAG Simple"]:::backend
        B1 --> B
        B2 --> B
        B3 --> B
        B4 --> B
        B5 --> B
        B6 --> B
        B7 --> B
    end

    subgraph "Database"
        D0["PostgreSQL (pgvector)"]:::database
        D1["Seed Data"]:::database
        D2["Setup Database (Python)"]:::database
        D3["Setup Database (Shell)"]:::database
        D1 --> D0
        D2 --> D0
        D3 --> D0
    end

    subgraph "Infrastructure & Deployment"
        I1["Azure Infrastructure (Bicep)"]:::infrastructure
        I2["GitHub Actions (CI/CD)"]:::infrastructure
        I3["Docker/Dev Containers"]:::infrastructure
        I2 --> I1
    end

    subgraph "Evaluation & Testing"
        E1["Testing Infrastructure"]:::testing
        E2["Evaluation Scripts"]:::testing
        E1 --> E2
    end

    X["OpenAI/Azure OpenAI"]:::external

    %% Cross-group Connections
    U -->|"Uses"| F0
    F0 -->|"REST_API"| B
    B -->|"Query_Search"| D0
    B -->|"AI_Call"| X
    I1 -->|"Deploys"| B
    I1 -->|"Deploys"| F0
    I2 -->|"Runs_Tests"| E1
    I2 -->|"Runs_Evals"| E2
    I3 ---|"Dev_Environment"| F0
    I3 ---|"Dev_Environment"| B

    %% Click Events
    click F0 "https://github.com/azure-samples/rag-postgres-openai-python/tree/main/src/frontend"
    click F1 "https://github.com/azure-samples/rag-postgres-openai-python/tree/main/src/frontend/src/api"
    click B "https://github.com/azure-samples/rag-postgres-openai-python/tree/main/src/backend/fastapi_app"
    click B1 "https://github.com/azure-samples/rag-postgres-openai-python/tree/main/src/backend/fastapi_app/routes"
    click B2 "https://github.com/azure-samples/rag-postgres-openai-python/blob/main/src/backend/fastapi_app/embeddings.py"
    click B3 "https://github.com/azure-samples/rag-postgres-openai-python/blob/main/src/backend/fastapi_app/openai_clients.py"
    click B4 "https://github.com/azure-samples/rag-postgres-openai-python/blob/main/src/backend/fastapi_app/query_rewriter.py"
    click B5 "https://github.com/azure-samples/rag-postgres-openai-python/blob/main/src/backend/fastapi_app/rag_advanced.py"
    click B6 "https://github.com/azure-samples/rag-postgres-openai-python/blob/main/src/backend/fastapi_app/rag_base.py"
    click B7 "https://github.com/azure-samples/rag-postgres-openai-python/blob/main/src/backend/fastapi_app/rag_simple.py"
    click D1 "https://github.com/azure-samples/rag-postgres-openai-python/blob/main/src/backend/fastapi_app/seed_data.json"
    click D2 "https://github.com/azure-samples/rag-postgres-openai-python/blob/main/src/backend/fastapi_app/setup_postgres_database.py"
    click D3 "https://github.com/azure-samples/rag-postgres-openai-python/blob/main/scripts/setup_postgres_database.sh"
    click I1 "https://github.com/azure-samples/rag-postgres-openai-python/tree/main/infra"
    click I2 "https://github.com/azure-samples/rag-postgres-openai-python/tree/main/.github/workflows"
    click I3 "https://github.com/azure-samples/rag-postgres-openai-python/blob/main/.devcontainer"
    click E1 "https://github.com/azure-samples/rag-postgres-openai-python/tree/main/tests"
    click E2 "https://github.com/azure-samples/rag-postgres-openai-python/tree/main/evals"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef backend fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px;
    classDef database fill:#FFF3E0,stroke:#E65100,stroke-width:2px;
    classDef infrastructure fill:#F3E5F5,stroke:#4A148C,stroke-width:2px;
    classDef testing fill:#E1F5FE,stroke:#01579B,stroke-width:2px;
    classDef external fill:#FFEBEE,stroke:#B71C1C,stroke-width:2px;
```
