Skip to content

spec.md

Latest commit

 

History

History
792 lines (674 loc) · 23.4 KB

spec.md

File metadata and controls

792 lines (674 loc) · 23.4 KB

React TypeScript Azure AI Foundry Agent Integration - Development Specification

Overview

A modern React.js application with TypeScript that provides a chat interface for connecting to an existing agent in Azure AI Foundry. This is a prototype application designed for development purposes with a focus on modern UI/UX patterns and seamless AI agent integration.

Application Architecture

Overall Architecture

  • Frontend: React.js 18+ with TypeScript (Client-side)
  • Backend: Node.js/Express API service wrapper (Server-side)
  • Agent Integration: Azure AI Foundry agent (Existing)
  • Deployment: Separate hosting for frontend and backend services

Frontend Framework

  • Framework: React.js 18+
  • Language: TypeScript
  • Build Tool: Webpack with TypeScript transpilation
  • Package Manager: npm

Backend Service Wrapper

  • Framework: Node.js with Express.js
  • Language: TypeScript
  • Purpose: Secure proxy for Azure AI Foundry agent communication
  • Hosting: Azure Container Apps or Azure App Service

Core Technology Stack

Runtime Environment

  • Node.js 18+
  • TypeScript 4.9+

Primary Dependencies

{
  "react": "^18.2.0",
  "react-dom": "^18.2.0",
  "react-router-dom": "^6.8.0",
  "typescript": "^4.9.0",
  "@azure/ai-agents": "^1.0.0",
  "@azure/identity": "^3.4.0",
  "@azure/core-auth": "^1.5.0",
  "@azure/core-client": "^1.7.0",
  "axios": "^1.6.0"
}

Development and Build Tools

  • TypeScript Compiler: typescript, ts-node
  • Bundling: webpack, webpack-cli
  • Testing: jest, @testing-library/react
  • Linting: eslint, @typescript-eslint/parser
  • Code Formatting: prettier

UI/UX Libraries

  • CSS Framework: Material-UI or Tailwind CSS
  • Icons: React Icons or Lucide React
  • State Management: React Context API or Zustand
  • Component Library: Modern component library for consistent design

Azure AI Foundry Integration

Authentication & Security

  • Azure Identity: Use @azure/identity for secure authentication
  • Service Principal: Configure service principal for agent access
  • Environment Variables:
    • AZURE_CLIENT_ID
    • AZURE_CLIENT_SECRET
    • AZURE_TENANT_ID
    • AZURE_AI_AGENT_ID
    • AZURE_AI_FOUNDRY_ENDPOINT

Agent Communication Architecture

  • Frontend ↔ Backend: RESTful API + WebSocket for real-time updates
  • Backend ↔ Azure AI Foundry: @azure/ai-agents SDK for secure agent communication
  • Real-time: WebSocket connection between frontend and backend service
  • Message Handling: Structured message format with request/response validation
  • Error Handling: Comprehensive error handling across all communication layers

Backend Service Wrapper Details

  • API Endpoints: RESTful endpoints for chat operations (send message, get history, etc.)
  • WebSocket Server: Real-time bidirectional communication for live chat
  • Authentication Proxy: Handle Azure AD authentication and token management
  • Rate Limiting: Implement rate limiting and request throttling
  • Logging & Monitoring: Comprehensive logging for debugging and monitoring

Functional Requirements

Core Features

  1. User Interface

    • Modern, responsive chat interface
    • Message history with timestamps
    • Typing indicators and status messages
    • Dark/light theme support
    • Mobile-responsive design

  2. Chat Functionality

    • Real-time messaging with Azure AI agent
    • Message threading and conversation history
    • File upload capabilities (if supported by agent)
    • Rich text and markdown support
    • Message search and filtering

  3. Agent Integration

    • Connect to existing Azure AI Foundry agent
    • Handle agent responses and formatting
    • Support for multimodal interactions (text, images)
    • Agent capability discovery and configuration
    • Session management and conversation context

  4. User Experience

    • Loading states and skeleton screens
    • Error boundaries and graceful error handling
    • Offline capability detection
    • Progressive Web App (PWA) features
    • Accessibility compliance (WCAG 2.1)

Technical Requirements

Authentication & Authorization

  • Azure Active Directory integration
  • Token-based authentication for agent access
  • Secure credential management
  • Role-based access control (if needed)

State Management

  • Centralized state for chat messages and user session
  • Persistent storage for conversation history
  • Real-time state synchronization
  • Optimistic UI updates

Performance Optimization

  • Code splitting and lazy loading
  • Message virtualization for large conversation histories
  • Efficient re-rendering with React optimizations
  • Asset optimization and caching strategies

Development Environment

  • Hot module replacement for development
  • Environment-specific configuration
  • Comprehensive TypeScript type definitions
  • Development server with proxy for API calls

Project Structure

Frontend Application (React)

frontend/
├── public/
│   ├── index.html
│   ├── manifest.json
│   └── favicon.ico
├── src/
│   ├── components/
│   │   ├── Chat/
│   │   │   ├── ChatContainer.tsx
│   │   │   ├── MessageList.tsx
│   │   │   ├── MessageInput.tsx
│   │   │   └── TypingIndicator.tsx
│   │   ├── UI/
│   │   │   ├── Button.tsx
│   │   │   ├── Input.tsx
│   │   │   └── Modal.tsx
│   │   └── Layout/
│   │       ├── Header.tsx
│   │       ├── Sidebar.tsx
│   │       └── Footer.tsx
│   ├── services/
│   │   ├── apiClient.ts      # Backend API communication
│   │   ├── websocket.ts      # WebSocket client
│   │   ├── auth.ts          # Frontend authentication
│   │   └── types.ts         # API response types
│   ├── hooks/
│   │   ├── useChat.ts
│   │   ├── useAuth.ts
│   │   └── useWebSocket.ts
│   ├── types/
│   │   ├── chat.ts
│   │   ├── agent.ts
│   │   └── user.ts
│   ├── utils/
│   │   ├── formatters.ts
│   │   ├── constants.ts
│   │   └── helpers.ts
│   ├── styles/
│   │   ├── globals.css
│   │   └── components/
│   ├── App.tsx
│   ├── index.tsx
│   └── setupTests.ts
├── package.json
├── tsconfig.json
├── webpack.config.js
├── jest.config.js
├── .eslintrc.js
├── .prettierrc
├── .env.example
└── README.md

Infrastructure as Code (Bicep)

infra/
├── main.bicep                   # Main infrastructure template
├── main.parameters.dev.json     # Development environment parameters
├── main.parameters.prod.json    # Production environment parameters (future)
├── modules/
│   ├── containerApps.bicep      # Container Apps environment and app
│   ├── staticWebApp.bicep       # Static Web Apps configuration
│   ├── keyVault.bicep          # Key Vault and secrets
│   ├── monitoring.bicep        # Application Insights and Log Analytics
│   ├── identity.bicep          # Managed identities and app registrations
│   └── storage.bicep           # Storage account (optional)
├── scripts/
│   ├── deploy.sh               # Deployment script (Bash)
│   ├── deploy.ps1              # Deployment script (PowerShell)
│   └── cleanup.sh              # Resource cleanup script
├── .env.bicep.example          # Bicep deployment environment variables
└── README.md                   # Infrastructure documentation

Root Project Structure

react-ai-chat-prototype/
├── azure.yaml                  # Azure Developer CLI configuration
├── frontend/                   # React application (as detailed above)
├── backend/                    # Node.js service wrapper (as detailed above)
├── infra/                      # Bicep infrastructure templates (as detailed above)
├── .github/
│   └── workflows/
│       ├── deploy-dev.yml      # GitHub Actions for development deployment
│       └── deploy-prod.yml     # GitHub Actions for production deployment
├── docs/
│   ├── DEVELOPMENT.md          # Development setup guide
│   ├── DEPLOYMENT.md           # Deployment instructions
│   └── API.md                  # API documentation
├── package.json                # Root package.json for workspace commands
├── .gitignore                  # Git ignore file
├── .env.example                # Root environment variables example
└── README.md                   # Project overview and getting started

Backend Service Wrapper (Node.js/Express)

backend/
├── src/
│   ├── controllers/
│   │   ├── chatController.ts    # Chat API endpoints
│   │   ├── authController.ts    # Authentication endpoints
│   │   └── healthController.ts  # Health check endpoints
│   ├── services/
│   │   ├── azureAgentService.ts # Azure AI Foundry integration
│   │   ├── authService.ts       # Azure AD authentication
│   │   ├── websocketService.ts  # WebSocket server logic
│   │   └── loggingService.ts    # Logging and monitoring
│   ├── middleware/
│   │   ├── auth.ts             # Authentication middleware
│   │   ├── rateLimiter.ts      # Rate limiting
│   │   ├── errorHandler.ts     # Error handling
│   │   └── validation.ts       # Request validation
│   ├── routes/
│   │   ├── chat.ts             # Chat routes
│   │   ├── auth.ts             # Auth routes
│   │   └── health.ts           # Health routes
│   ├── types/
│   │   ├── agent.ts            # Azure AI agent types
│   │   ├── api.ts              # API request/response types
│   │   └── auth.ts             # Authentication types
│   ├── utils/
│   │   ├── config.ts           # Configuration management
│   │   ├── logger.ts           # Logging utilities
│   │   └── validators.ts       # Input validation
│   ├── app.ts                  # Express app setup
│   └── server.ts               # Server entry point
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── package.json
├── tsconfig.json
├── jest.config.js
├── Dockerfile
├── .env.example
└── README.md

Azure Resources (Development Environment)

Required Azure Services

Core AI Services

  1. Azure AI Foundry (Premium)
    • Existing agent hosting and management
    • Agent runtime and conversation handling
    • Model orchestration and prompt management

Frontend Hosting

  1. Azure Static Web Apps (Free Tier)
    • React frontend application hosting
    • Built-in CI/CD with GitHub integration
    • Custom domain support
    • Automatic HTTPS

Backend Service Hosting

  1. Azure Container Apps (Consumption Plan)
    • Backend service wrapper hosting
    • Auto-scaling based on demand
    • Container-based deployment
    • Built-in load balancing
    • Alternative: Azure App Service (Basic B1) for simpler deployment

Security & Authentication

  1. Azure Active Directory (Entra ID) (Free Tier)

    • User authentication and authorization
    • Service principal management for backend
    • Token validation and security
    • API app registrations

  2. Azure Key Vault (Standard)

    • Secure storage for Azure AI Foundry credentials
    • Connection strings and secrets management
    • Certificate management
    • Backend service authentication keys

Monitoring & Observability

  1. Azure Monitor + Application Insights (Basic)
    • Frontend and backend performance monitoring
    • Error tracking and debugging
    • User interaction analytics
    • Custom telemetry and logging
    • API request/response monitoring

Optional Development Services

  1. Azure Storage Account (Standard)

    • File upload and storage (if needed)
    • Static asset hosting
    • Blob storage for conversation logs

  2. Azure CDN (Standard)

    • Global content delivery
    • Asset optimization and caching
    • Improved loading performance

Development Configuration

Environment Variables

Frontend Environment Variables (.env)

# Backend API Configuration
REACT_APP_API_BASE_URL=http://localhost:8080/api
REACT_APP_WS_URL=ws://localhost:8080

# Azure Authentication (Public - Client-side)
REACT_APP_AZURE_CLIENT_ID=your-frontend-client-id
REACT_APP_AZURE_TENANT_ID=your-tenant-id

# Development Settings
REACT_APP_ENVIRONMENT=development
REACT_APP_LOG_LEVEL=debug

Backend Environment Variables (.env)

# Server Configuration
PORT=8080
NODE_ENV=development

# Azure AI Foundry Configuration (Secure - Server-side only)
AZURE_AI_FOUNDRY_ENDPOINT=https://your-foundry-endpoint.azure.com
AZURE_AI_AGENT_ID=your-agent-id

# Azure Authentication (Service Principal)
AZURE_CLIENT_ID=your-backend-service-principal-id
AZURE_CLIENT_SECRET=your-backend-service-principal-secret
AZURE_TENANT_ID=your-tenant-id

# Azure Key Vault
AZURE_KEY_VAULT_URL=https://your-keyvault.vault.azure.net/

# CORS Configuration
ALLOWED_ORIGINS=http://localhost:3000,https://your-frontend-domain.com

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

# Logging
LOG_LEVEL=debug
APPLICATION_INSIGHTS_CONNECTION_STRING=your-app-insights-connection-string

TypeScript Configuration

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["dom", "dom.iterable", "ES6"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Infrastructure as Code (Bicep Templates)

Main Infrastructure Template (infra/main.bicep)

@description('Environment name (dev, staging, prod)')
param environmentName string = 'dev'

@description('Application name')
param appName string = 'react-ai-chat'

@description('Primary location for resources')
param location string = resourceGroup().location

@description('Azure AI Foundry endpoint')
param aiFoundryEndpoint string

@description('Azure AI Agent ID')
param aiAgentId string

// Variables
var resourceToken = toLower(uniqueString(subscription().id, resourceGroup().id, location))
var tags = {
  'azd-service-name': appName
  environment: environmentName
  project: 'react-ai-chat-prototype'
}

// Modules
module containerApps 'modules/containerApps.bicep' = {
  name: 'containerApps'
  params: {
    environmentName: environmentName
    appName: appName
    location: location
    resourceToken: resourceToken
    tags: tags
  }
}

module staticWebApp 'modules/staticWebApp.bicep' = {
  name: 'staticWebApp'
  params: {
    environmentName: environmentName
    appName: appName
    location: location
    resourceToken: resourceToken
    tags: tags
    backendUrl: containerApps.outputs.backendUrl
  }
}

module keyVault 'modules/keyVault.bicep' = {
  name: 'keyVault'
  params: {
    environmentName: environmentName
    appName: appName
    location: location
    resourceToken: resourceToken
    tags: tags
    principalId: containerApps.outputs.principalId
    aiFoundryEndpoint: aiFoundryEndpoint
    aiAgentId: aiAgentId
  }
}

module monitoring 'modules/monitoring.bicep' = {
  name: 'monitoring'
  params: {
    environmentName: environmentName
    appName: appName
    location: location
    resourceToken: resourceToken
    tags: tags
  }
}

// Outputs
output AZURE_CONTAINER_APPS_ENVIRONMENT_ID string = containerApps.outputs.environmentId
output BACKEND_URL string = containerApps.outputs.backendUrl
output FRONTEND_URL string = staticWebApp.outputs.defaultHostname
output KEY_VAULT_NAME string = keyVault.outputs.keyVaultName
output APPLICATION_INSIGHTS_CONNECTION_STRING string = monitoring.outputs.applicationInsightsConnectionString

Azure Developer CLI Configuration (azure.yaml)

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json

name: react-ai-chat-prototype
metadata:
  template: react-ai-chat-prototype@0.0.1-beta

services:
  backend:
    project: ./backend
    language: ts
    host: containerapp
    docker:
      path: ./backend/Dockerfile
      context: ./backend
  
  frontend:
    project: ./frontend
    language: ts
    host: staticwebapp
    dist: build

hooks:
  preprovision:
    shell: sh
    run: |
      echo "Preparing infrastructure provisioning..."
      # Validate required environment variables
      if [ -z "$AZURE_AI_FOUNDRY_ENDPOINT" ]; then
        echo "Error: AZURE_AI_FOUNDRY_ENDPOINT is required"
        exit 1
      fi
      if [ -z "$AZURE_AI_AGENT_ID" ]; then
        echo "Error: AZURE_AI_AGENT_ID is required"
        exit 1
      fi

  postprovision:
    shell: sh
    run: |
      echo "Infrastructure provisioning completed"
      echo "Setting up application configuration..."
      # Additional setup tasks can be added here

  prepackage:
    shell: sh
    run: |
      echo "Building application packages..."
      npm run build:all

Development Parameters (infra/main.parameters.dev.json)

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentName": {
      "value": "dev"
    },
    "appName": {
      "value": "react-ai-chat"
    },
    "location": {
      "value": "East US 2"
    },
    "aiFoundryEndpoint": {
      "value": "${AZURE_AI_FOUNDRY_ENDPOINT}"
    },
    "aiAgentId": {
      "value": "${AZURE_AI_AGENT_ID}"
    }
  }
}

Security Considerations

Authentication Flow

  1. User authenticates with Azure AD
  2. Application receives access token
  3. Token used to authenticate with Azure AI Foundry
  4. Secure agent communication established

Data Protection

  • All API communications use HTTPS
  • Tokens stored securely in browser storage
  • No sensitive data in client-side code
  • CORS properly configured for security

Privacy & Compliance

  • Conversation data handling policies
  • User consent for data processing
  • Data retention and deletion capabilities
  • Audit logging for compliance

Testing Strategy

Unit Testing

  • Component testing with React Testing Library
  • Service layer testing with Jest
  • Mock Azure SDK for isolated testing
  • Type safety validation with TypeScript

Integration Testing

  • End-to-end chat flow testing
  • Azure agent integration testing
  • Authentication flow validation
  • Error scenario handling

Performance Testing

  • Message rendering performance
  • Network request optimization
  • Memory usage monitoring
  • Load testing for conversation history

Deployment & DevOps

Development Workflow

  1. Local development with hot reload
  2. Git-based version control
  3. Pull request reviews and testing
  4. Automated deployment to Azure Static Web Apps

CI/CD Pipeline

  • Automated testing on pull requests
  • TypeScript compilation verification
  • Security scanning and dependency checks
  • Automated deployment to staging and production

Monitoring & Observability

  • Application Insights integration
  • Custom telemetry for chat interactions
  • Error tracking and alerting
  • Performance monitoring and optimization

Getting Started

Prerequisites

  • Node.js 18+ installed
  • Azure subscription with AI Foundry access
  • Existing Azure AI agent configured
  • Azure CLI for resource management
  • Azure Developer CLI (azd) for infrastructure deployment
  • Docker Desktop (for container development)
  • Git for version control

Installation Steps

Backend Service Setup

  1. Clone the repository
  2. Navigate to backend directory: cd backend
  3. Install dependencies: npm install
  4. Configure backend environment variables (.env)
  5. Set up Azure service principal and Key Vault access
  6. Start backend development server: npm run dev
  7. Verify backend health endpoint: http://localhost:8080/health

Frontend Application Setup

  1. Navigate to frontend directory: cd frontend
  2. Install dependencies: npm install
  3. Configure frontend environment variables (.env)
  4. Start frontend development server: npm start
  5. Access application: http://localhost:3000
  6. Test end-to-end chat functionality

Development Commands

Backend Commands

# Start backend development server
npm run dev

# Build backend for production
npm run build

# Run backend tests
npm test

# Run backend linting
npm run lint

# Type checking
npm run type-check

# Start production backend
npm start

Frontend Commands

# Start frontend development server
npm start

# Build frontend for production
npm run build

# Run frontend tests
npm test

# Run frontend linting
npm run lint

# Type checking
npm run type-check

Development Workflow

# Start both services concurrently (from project root)
npm run dev:all

# Build both services
npm run build:all

# Run all tests
npm run test:all

Infrastructure Management Commands

# Deploy to development environment using Azure Developer CLI
azd init                              # Initialize azd environment
azd auth login                        # Login to Azure
azd provision --environment dev      # Provision Azure resources
azd deploy --environment dev         # Deploy applications
azd down --environment dev           # Clean up resources

# Deploy using custom scripts
./infra/scripts/deploy.sh dev         # Bash deployment script
./infra/scripts/deploy.ps1 -Environment dev  # PowerShell deployment script

# Manual Bicep deployment
az deployment group create \
  --resource-group rg-react-ai-chat-dev \
  --template-file infra/main.bicep \
  --parameters @infra/main.parameters.dev.json

# Validate Bicep templates
az deployment group validate \
  --resource-group rg-react-ai-chat-dev \
  --template-file infra/main.bicep \
  --parameters @infra/main.parameters.dev.json

# Environment setup
export AZURE_AI_FOUNDRY_ENDPOINT="https://your-foundry-endpoint.azure.com"
export AZURE_AI_AGENT_ID="your-agent-id"
export AZURE_SUBSCRIPTION_ID="your-subscription-id"

Best Practices

Code Quality

  • Consistent TypeScript usage
  • Component composition patterns
  • Custom hooks for reusable logic
  • Proper error boundaries
  • Comprehensive testing coverage

Performance

  • Efficient state management
  • Memoization for expensive operations
  • Lazy loading and code splitting
  • Optimized bundle size
  • Efficient re-rendering strategies

User Experience

  • Responsive design principles
  • Accessibility best practices
  • Progressive enhancement
  • Offline-first considerations
  • Smooth animations and transitions

Future Enhancements

Potential Features

  • Multi-agent support
  • Voice input/output integration
  • Advanced message formatting
  • Conversation export capabilities
  • Plugin system for extensibility

Scalability Considerations

  • Horizontal scaling strategies
  • Caching implementations
  • Database integration for persistence
  • Load balancing for high traffic
  • Microservices architecture migration

This specification provides a comprehensive foundation for building a modern React TypeScript application that seamlessly integrates with Azure AI Foundry agents while maintaining high development standards and user experience quality.