Lab 1: Architecture Deep Dive¶

This page provides detailed architectural information for the Direct Coveo Integration pattern used in Lab 1.

🏗️ System Architecture¶

High-Level Overview¶

Component Details¶

Frontend Layer¶

• React Search UI: Single-page application hosted on AWS App Runner
• Authentication: Cognito-based user authentication with JWT tokens
• Responsive Design: Works on desktop and mobile devices
• Real-time Updates: Dynamic result rendering without page refresh

API Gateway Layer¶

• HTTP API: RESTful endpoints for all search operations
• CORS Configuration: Enables cross-origin requests from UI
• JWT Authorizer: Validates Cognito tokens
• Request Routing: Directs requests to appropriate Lambda functions

Lambda Functions¶

Each Lambda function handles a specific Coveo API integration:

Overall Request Flow¶

This diagram shows the end-to-end flow for Pattern 1 (Direct API Integration):

🔄 Request Flow Sequences¶

Answer Request Flow¶

Key Steps:

1. User enters question
2. Answer Proxy calls Coveo Answer API
3. Coveo generates AI response with sources
4. Citations formatted and returned
5. UI displays answer with clickable sources

Passages Request Flow¶

Key Steps:

1. User enters query
2. Passages Proxy calls Coveo Passages API
3. Coveo performs semantic search
4. Relevant text excerpts extracted
5. UI displays passages with highlighting

Search Request Flow¶

Key Steps:

1. User enters query in search bar
2. UI validates and sends to API Gateway
3. API Gateway authenticates JWT token
4. Search Proxy Lambda builds Coveo API request
5. Coveo processes query with ML ranking
6. Results returned with facets and metadata
7. UI renders results in three sections

🔧 Technical Implementation¶

Lambda Function Structure¶

Each proxy Lambda follows a consistent pattern:

import json
import requests
import os

def lambda_handler(event, context):
    """
    Proxy Lambda function for Coveo API integration
    """
    # 1. Extract request parameters
    body = json.loads(event['body'])
    query = body.get('query', '')

    # 2. Build Coveo API request
    coveo_request = {
        'q': query,
        'organizationId': os.environ['COVEO_ORG_ID'],
        'searchHub': 'workshop',
        'numberOfResults': 20,
        'fieldsToInclude': ['title', 'uri', 'excerpt']
    }

    # 3. Call Coveo API
    headers = {
        'Authorization': f'Bearer {os.environ["COVEO_API_KEY"]}',
        'Content-Type': 'application/json'
    }

    response = requests.post(
        'https://platform.cloud.coveo.com/rest/search/v2/',
        json=coveo_request,
        headers=headers
    )

    # 4. Format and return response
    return {
        'statusCode': 200,
        'headers': {
            'Content-Type': 'application/json',
            'Access-Control-Allow-Origin': '*'
        },
        'body': json.dumps(response.json())
    }

Environment Configuration¶

Each Lambda function uses these environment variables:

Error Handling¶

All Lambda functions implement consistent error handling:

try:
    # Coveo API call
    response = requests.post(coveo_url, json=request_body, headers=headers)
    response.raise_for_status()

    return {
        'statusCode': 200,
        'body': json.dumps(response.json())
    }

except requests.exceptions.RequestException as e:
    return {
        'statusCode': 500,
        'body': json.dumps({
            'error': 'Coveo API error',
            'message': str(e)
        })
    }
except Exception as e:
    return {
        'statusCode': 500,
        'body': json.dumps({
            'error': 'Internal server error',
            'message': str(e)
        })
    }

📊 Performance Characteristics¶

Response Times (Typical)¶

Scalability¶

• Lambda Concurrency: Auto-scales to handle traffic spikes
• API Gateway: Handles thousands of requests per second
• Coveo Platform: Enterprise-grade scalability and availability
• Serverless Design: Scales as the load increases, minimal costs
• Seperation of Concern: Front end decoupled from backend

Cost Optimization¶

• Lambda: Pay per request and execution time (~$0.20 per million requests)
• API Gateway: Pay per API call (~$1.00 per million requests)
• App Runner: Pay for running time and requests (~$0.064 per vCPU-hour)
• Coveo: Usage-based pricing for API calls

🔒 Security Implementation¶

Authentication & Authorization¶

Security Layers:

1. Cognito User Pools: Secure user authentication
2. JWT Tokens: Stateless session management
3. API Gateway Authorization: Request validation and routing
4. Lambda IAM Roles: Least privilege access

Data Protection¶

• HTTPS Everywhere: All communications encrypted in transit
• API Key Management: Secure storage in Lambda environment variables
• CORS Configuration: Controlled cross-origin access
• No PII Storage: User data not persisted

Monitoring & Logging¶

• CloudWatch Logs: All Lambda function logs
• X-Ray Tracing: Request flow visualization
• CloudWatch Metrics: Performance and error monitoring
• Coveo Analytics: Search usage and performance tracking

🎯 Benefits of This Architecture¶

Advantages¶

Trade-offs¶

📚 Additional Resources¶

Coveo Documentation¶

• Coveo Search API
• Coveo Passages API
• Coveo Answer API

AWS Services Documentation¶

• AWS Lambda
• Amazon API Gateway
• Amazon Cognito
• AWS App Runner