AI Digital Twin on AWS

An AI-powered digital twin application deployed on AWS, featuring a conversational interface powered by Amazon Bedrock and a modern Next.js frontend.

🎯 Overview

This project creates a personalized AI digital twin that can answer questions and engage in conversations based on custom training data. The application is fully deployed on AWS infrastructure using Infrastructure as Code (Terraform) with automated CI/CD via GitHub Actions.

🏗️ Architecture

The application uses a serverless architecture on AWS:

• Frontend: Next.js static site hosted on S3 and served via CloudFront CDN
• Backend: Python FastAPI application running on AWS Lambda
• AI Model: Amazon Bedrock (Nova Micro) for conversational AI
• Memory: S3 bucket for persistent conversation history
• API: API Gateway for HTTP endpoints
• Infrastructure: Terraform for infrastructure management
• CI/CD: GitHub Actions for automated deployment

✨ Features

• 💬 Real-time chat interface with conversational AI
• 🎨 Modern, responsive UI built with Next.js and Tailwind CSS
• 🧠 Persistent conversation memory using S3
• 🔄 Session management for multi-turn conversations
• 🚀 Fully automated deployment pipeline
• 🌐 CloudFront CDN for global low-latency access
• 🔒 Secure API communication
• 📊 Multiple environment support (dev, test, prod)

🛠️ Tech Stack

Frontend

• Next.js 15 - React framework with static export
• TypeScript - Type-safe development
• Tailwind CSS - Utility-first styling
• Lucide React - Icon library

Backend

• Python 3.12 - Runtime
• FastAPI - Modern web framework
• LangChain - LLM orchestration
• Amazon Bedrock - AI foundation models
• uv - Fast Python package manager
• Mangum - ASGI adapter for AWS Lambda

Infrastructure

• Terraform - Infrastructure as Code
• AWS S3 - Static hosting & storage
• AWS CloudFront - CDN
• AWS Lambda - Serverless compute
• AWS API Gateway - HTTP API
• AWS Bedrock - AI services
• GitHub Actions - CI/CD

📋 Prerequisites

• AWS Account with appropriate permissions
• GitHub account
• AWS CLI configured
• Terraform >= 1.0
• Node.js >= 20
• Python >= 3.12
• uv (Python package manager)

🚀 Quick Start

1. Clone the Repository

git clone <your-repo-url>
cd twin

2. Set Up AWS Credentials

Configure AWS credentials for GitHub Actions:

1. Create an OIDC provider in AWS for GitHub Actions
2. Create an IAM role with necessary permissions
3. Add these secrets to your GitHub repository:
   • AWS_ROLE_ARN
   • AWS_ACCOUNT_ID
   • DEFAULT_AWS_REGION

3. Initialize Backend State (One-time)

cd terraform
terraform init
terraform apply -target="aws_s3_bucket.terraform_state" \
  -target="aws_s3_bucket_versioning.terraform_state" \
  -target="aws_dynamodb_table.terraform_locks"

4. Deploy

Push to the main branch to trigger automatic deployment:

git push origin main

Or manually trigger deployment via GitHub Actions workflow.

📁 Project Structure

twin/
├── backend/              # Python FastAPI backend
│   ├── api.py           # Main API application
│   ├── agent.py         # LangChain agent logic
│   ├── deploy.py        # Lambda packaging script
│   ├── data/            # Training data (not in git)
│   └── pyproject.toml   # Python dependencies
├── frontend/            # Next.js frontend
│   ├── app/            # App router pages
│   ├── components/     # React components
│   └── public/         # Static assets
├── terraform/           # Infrastructure as Code
│   ├── main.tf         # Main infrastructure
│   ├── outputs.tf      # Terraform outputs
│   ├── variables.tf    # Input variables
│   └── prod.tfvars     # Production configuration
├── scripts/            # Deployment scripts
│   ├── deploy.sh       # Main deployment script
│   └── destroy.sh      # Teardown script
└── .github/
    └── workflows/      # CI/CD pipelines
        ├── deploy.yml  # Deployment workflow
        └── destroy.yml # Destruction workflow

🔧 Configuration

Environment Variables

The backend uses these environment variables (set by Terraform):

• S3_MEMORY_BUCKET - S3 bucket for conversation memory
• BEDROCK_MODEL_ID - Bedrock model identifier
• MEMORY_DIR - Local directory for development

Terraform Variables

Key variables in terraform/variables.tf:

• project_name - Resource name prefix
• environment - Deployment environment (dev/test/prod)
• bedrock_model_id - AI model to use
• use_custom_domain - Enable custom domain (prod only)
• root_domain - Your custom domain name

🌍 Multiple Environments

The project supports three environments using Terraform workspaces:

• dev - Development environment
• test - Testing environment
• prod - Production with optional custom domain

Each environment maintains separate infrastructure and state.

📦 Deployment Process

The automated deployment pipeline:

1. Builds Lambda deployment package
2. Initializes Terraform with remote S3 backend
3. Applies infrastructure changes
4. Builds Next.js frontend with API URL
5. Syncs frontend to S3
6. Invalidates CloudFront cache for immediate updates

🧹 Cleanup

To destroy all resources in an environment:

./scripts/destroy.sh <environment>

Or use the GitHub Actions destroy workflow.

🔐 Security Considerations

• Personal training data in backend/data/ is excluded from version control
• Conversation memory is stored in private S3 buckets
• API Gateway provides secure endpoint exposure
• CloudFront serves content over HTTPS
• OIDC for GitHub Actions eliminates long-lived credentials

📝 License

This project is part of an AI in Production course.

🤝 Contributing

This is a learning project. Feel free to fork and adapt for your own use!

🐛 Troubleshooting

Changes not visible after deployment

If updates don't appear after deployment, CloudFront cache may need invalidation:

cd terraform
DIST_ID=$(terraform output -raw cloudfront_distribution_id)
aws cloudfront create-invalidation --distribution-id $DIST_ID --paths "/*"

The deployment script now handles this automatically.

Lambda deployment package issues

Rebuild the package manually:

cd backend
uv run deploy.py

---

Built with ❤️ as part of AI in Production course