How azure-samples/rag-postgres-openai-python works
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.