Overview

This directory contains comprehensive technical documentation for architects, developers, and system administrators working with the Azure AI Travel Agents system.

Documentation Overview

Architecture & Design

• Technical Architecture - Complete system architecture, components, and design patterns
• Data Flow & Sequence Diagrams - Visual representations of request flows and component interactions

Implementation Guides

• MCP Server Implementation - Detailed guide for Model Context Protocol servers across multiple languages
• API Documentation - Complete REST API reference with examples and integration patterns
• Development Guide - Comprehensive developer onboarding and contribution guide

Operations & Deployment

• Deployment Architecture - Infrastructure, deployment strategies, and production configurations

System Architecture Overview

The Azure AI Travel Agents system is built on a microservices architecture using:

• Frontend: Angular UI with real-time streaming
• API Server: Express.js with LlamaIndex.TS orchestration
• MCP Servers: 7 specialized services in TypeScript, C#, Java, and Python
• AI Services: Azure OpenAI and custom model inference
• Monitoring: OpenTelemetry with Aspire Dashboard
• Deployment: Docker containers on Azure Container Apps

┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐
│ Angular UI  │───▶│ Express API │───▶│ LlamaIndex.TS       │
│             │    │             │    │ Orchestrator        │
└─────────────┘    └─────────────┘    └──────────┬──────────┘
                                                  │
                           ┌──────────────────────┼──────────────────────┐
                           │                      │                      │
                    ┌──────▼──────┐    ┌─────────▼────────┐    ┌────────▼────────┐
                    │ Customer    │    │ Destination      │    │ Itinerary       │
                    │ Query       │    │ Recommendation   │    │ Planning        │
                    │ (C#/.NET)   │    │ (Java)           │    │ (Python)        │
                    └─────────────┘    └──────────────────┘    └─────────────────┘

Quick Start for Different Roles

For Architects

1. Start with Technical Architecture for system overview
2. Review Deployment Architecture for infrastructure planning
3. Examine Flow Diagrams for interaction patterns

For Developers

1. Follow Development Guide for environment setup
2. Study MCP Server Implementation for service development
3. Reference API Documentation for integration

For DevOps/Operations

1. Review Deployment Architecture for deployment strategies
2. Check monitoring sections in Technical Architecture
3. Follow production deployment guides

Key Technologies

System Capabilities

• Multi-Agent Orchestration: Coordinated AI agents for complex travel planning
• Real-time Streaming: Server-Sent Events for live response updates
• Polyglot Architecture: MCP servers in multiple programming languages
• Scalable Deployment: Azure Container Apps with auto-scaling
• Comprehensive Monitoring: Distributed tracing and metrics collection
• Extensible Design: Easy addition of new AI tools and capabilities

Documentation Features

Each documentation file includes:

• Detailed Code Examples: Copy-paste ready implementations
• Architecture Diagrams: Visual system representations
• Configuration Templates: Ready-to-use configurations
• Troubleshooting Guides: Common issues and solutions
• Performance Guidelines: Optimization best practices
• Security Considerations: Production-ready security patterns

Document Structure

Technical Architecture

• System overview and design principles
• Component specifications and interactions
• Data models and API contracts
• Development and extension guides

Flow Diagrams

• Request/response flow patterns
• Agent interaction sequences
• Error handling and recovery flows
• Real-time communication patterns

MCP Servers

• Protocol specifications and implementations
• Server-specific guides for each language
• Tool development and integration patterns
• Performance and scaling considerations

API Documentation

• Complete endpoint reference
• Request/response schemas
• Authentication and security
• Client libraries and SDKs

Deployment Architecture

• Infrastructure as Code templates
• Environment-specific configurations
• Monitoring and observability setup
• Production deployment strategies

Development Guide

• Environment setup and tooling
• Coding standards and conventions
• Testing strategies and frameworks
• Contributing guidelines and workflows

Use Cases

This documentation supports:

• System Architecture Planning: Understanding component relationships and data flows
• Development Onboarding: Getting new developers productive quickly
• Production Deployment: Reliable, scalable infrastructure deployment
• System Extension: Adding new features and capabilities
• Troubleshooting: Diagnosing and resolving system issues
• Performance Optimization: Improving system performance and efficiency

Getting Help

• For Architecture Questions: Review Technical Architecture
• For Development Issues: Check Development Guide
• For Deployment Problems: See Deployment Architecture
• For API Integration: Reference API Documentation
• For MCP Development: Study MCP Server Implementation

Documentation Updates

This documentation is maintained alongside the codebase. When contributing:

1. Update relevant documentation with code changes
2. Add examples for new features
3. Update diagrams for architectural changes
4. Maintain consistency across all documents

This documentation reflects the current state of the Azure AI Travel Agents system and is updated regularly to maintain accuracy and completeness. If you notice any discrepancies or have suggestions for improvement, please submit an issue or pull request on GitHub.