Skip to content

README.md

Latest commit

 

History

History
286 lines (216 loc) · 7.3 KB

README.md

File metadata and controls

286 lines (216 loc) · 7.3 KB

React AI Chat Prototype

A modern React TypeScript application that provides a chat interface for connecting to an existing agent in Azure AI Foundry.

🚀 Quick Start

Prerequisites

  • Node.js 18+
  • Azure subscription with AI Foundry access
  • Azure CLI
  • Azure Developer CLI (azd)

1. Clone and Setup

git clone <repository-url>
cd react-ai-chat-prototype
npm install

2. Configure Environment Variables

Create .env files in both frontend and backend directories:

Backend (.env):

# Required - Your Azure AI Foundry Details
AZURE_AI_FOUNDRY_ENDPOINT=https://kvenkatrajan-testagent-resource.services.ai.azure.com/api/projects/kvenkatrajan-testagent
AZURE_AI_AGENT_ID=asst_r5IijlfcCpFUpvWRLJYsWSuz

# Authentication (for production, use service principal)
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=your-tenant-id

# Or use API key for development
AZURE_AI_API_KEY=your-api-key

# Optional
PORT=8080
NODE_ENV=development
ALLOWED_ORIGINS=http://localhost:3000

Frontend (.env):

VITE_API_BASE_URL=http://localhost:8080/api
VITE_APP_NAME=Azure AI Chat

3. Start Development

# Install all dependencies
npm run install:all

# Start both frontend and backend
npm run dev:all

4. Access the Application

🏗️ Architecture

Frontend (React TypeScript)

  • Framework: React 18 with TypeScript
  • Build Tool: Vite
  • Styling: Tailwind CSS with fallback styles
  • State Management: React hooks (useState, useEffect)
  • UI Components: Custom chat interface with markdown support

Backend (Node.js Express)

  • Framework: Express.js with TypeScript
  • Authentication: Azure Identity SDK
  • Rate Limiting: Express rate limiter
  • Security: Helmet, CORS, input validation
  • Logging: Winston with structured logging

Azure Infrastructure

  • Backend Hosting: Azure Container Apps
  • Frontend Hosting: Azure Static Web Apps
  • Security: Azure Key Vault for secrets
  • Monitoring: Application Insights + Log Analytics
  • Identity: User-assigned managed identity

🔧 Development Commands

Root Level

npm run dev:all          # Start both services
npm run build:all        # Build both applications
npm run test:all         # Run all tests
npm run lint:all         # Lint all code
npm run clean           # Clean build artifacts

Backend

cd backend
npm run dev             # Start with hot reload
npm run build          # Build for production
npm run start          # Start production server
npm run test           # Run tests
npm run lint           # Lint TypeScript

Frontend

cd frontend
npm run dev            # Start development server
npm run build         # Build for production
npm run preview       # Preview production build
npm run lint          # Lint TypeScript

🚀 Deployment

Using Azure Developer CLI (Recommended)

# Initialize azd environment
azd init

# Login to Azure
azd auth login

# Set required environment variables
azd env set AZURE_AI_FOUNDRY_ENDPOINT "https://kvenkatrajan-testagent-resource.services.ai.azure.com/api/projects/kvenkatrajan-testagent"
azd env set AZURE_AI_AGENT_ID "asst_r5IijlfcCpFUpvWRLJYsWSuz"

# Deploy to Azure
azd up

Manual Deployment

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

# Build and deploy backend container
cd backend
az containerapp update \
  --name <backend-container-app-name> \
  --resource-group <resource-group> \
  --image <your-registry>/backend:latest

# Build and deploy frontend
cd frontend
npm run build
az staticwebapp deploy \
  --name <static-web-app-name> \
  --source-location ./build

📡 API Endpoints

Chat API (/api/chat)

  • POST /send - Send a message to the agent
  • GET /conversations/:id - Get conversation history
  • POST /conversations - Create new conversation
  • DELETE /conversations/:id - Delete conversation

Health API (/health)

  • GET / - Comprehensive health check
  • GET /ready - Readiness probe
  • GET /live - Liveness probe

Example API Usage

# Send a message
curl -X POST http://localhost:8080/api/chat/send \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, how are you?"}'

# Health check
curl http://localhost:8080/health

🔒 Security Features

  • CORS: Configured for specific origins
  • Rate Limiting: Prevents API abuse
  • Input Validation: Sanitizes user inputs
  • Secure Headers: Helmet.js security middleware
  • Secret Management: Azure Key Vault integration
  • Managed Identity: Secure Azure service authentication

🎨 UI Features

  • Modern Design: Clean, responsive interface
  • Real-time Chat: Instant message exchange
  • Markdown Support: Rich text formatting in responses
  • Code Highlighting: Syntax highlighting for code blocks
  • Loading States: Visual feedback during operations
  • Error Handling: User-friendly error messages
  • Auto-scroll: Automatic scroll to latest messages

🔧 Configuration

Backend Configuration

All backend configuration is managed through environment variables and can be found in backend/src/utils/config.ts.

Frontend Configuration

Frontend uses Vite environment variables prefixed with VITE_. See frontend/src/vite-env.d.ts for type definitions.

🐛 Troubleshooting

Common Issues

  1. Backend fails to start

    • Check environment variables are set correctly
    • Verify Azure AI Foundry endpoint is accessible
    • Check Azure credentials are valid

  2. Frontend can't connect to backend

    • Ensure backend is running on port 8080
    • Check CORS configuration in backend
    • Verify API base URL in frontend .env

  3. Agent not responding

    • Verify agent ID is correct
    • Check Azure AI Foundry service status
    • Review backend logs for authentication errors

Debugging

# Backend logs
cd backend
npm run dev  # Will show detailed logs

# Frontend development
cd frontend
npm run dev  # Check browser console for errors

# Health check
curl http://localhost:8080/health

🔄 Development Workflow

  1. Code Changes: Make changes to frontend/backend
  2. Local Testing: Test with npm run dev:all
  3. Build Verification: Run npm run build:all
  4. Deployment: Use azd up for full deployment

📈 Monitoring

When deployed to Azure, the application includes:

  • Application Insights: Performance and error tracking
  • Log Analytics: Centralized logging
  • Health Endpoints: For container orchestration
  • Custom Metrics: Chat interaction tracking

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

📄 License

This project is licensed under the MIT License.

🆘 Support

For issues and questions:

  1. Check the troubleshooting section above
  2. Review GitHub issues
  3. Create a new issue with detailed information

Note: This is a prototype application designed for development and demonstration purposes. For production use, additional security, monitoring, and performance optimizations should be implemented.