NovaCorp Support Intelligence Platform

Project Overview

This project demonstrates how to build a real-time AI-powered customer support monitoring platform on AWS using a fully serverless and automated architecture. The system analyzes customer messages in real time, detects sentiment using Amazon Comprehend, stores interactions in Amazon DynamoDB, and triggers alerts through Amazon SNS when negative sentiment is detected.

The infrastructure is defined using Terraform, while deployment and automation are handled through GitHub Actions using secure OIDC authentication. The frontend is hosted on Amazon S3 and delivered globally via Amazon CloudFront.

Together, these components create a scalable and automated cloud-native platform that demonstrates modern DevOps, serverless architecture, and AI integration on AWS.

Services used

Implementatation

1. Prerequisites

# Install terraform: run this as admin in powershell
choco install terraform -y

# Verify installation
terraform -version

# Configure AWS
 aws configure
# Enter your Access Key, Secret, region (us-east-1), output format (json)

2. Bootstrap Terraform state storage

# Create S3 bucket for terraform state to store state in the backend
# Create bucket
aws s3 mb s3://novacorp-terraform-state --region us-east-1

# Enable versioning
aws s3api put-bucket-versioning --bucket novacorp-terraform-state --versioning-configuration Status=Enabled

# Create DynamoDB lock table
aws dynamodb create-table --table-name novacorp-terraform-lock --attribute-definitions
 AttributeName=LockID,AttributeType=S --key-schema AttributeName=LockID,KeyType=HASH --billing-mode
 PAY_PER_REQUEST --region us-east-1

3. Configure variables

# Copy the content of terraform.tvars.example to terraform.tfvars 
cd terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your email, phone or Slack webhook
# Note: This is where you set your notification channel.

# Create a Slack APP Webhook and insert your webhook Url in the  terraform.tfvars file
https://api.slack.com/apps

4. Deploy infrastructure with Terraform

terraform init
terraform plan    # Review what will be created
terraform apply   # Deploy everything

5. Deploy the frontend

# After terraform apply, get the S3 bucket name
terraform output -raw frontend_bucket_name

# Upload your support portal files
aws s3 sync ./frontend/ s3://[REPLACE WITH YOUR BUCkET NMAE]

# Get your live URL and test it in a browser.
terraform output support_portal_url

Note: For replication make sure you replace your cloud front url wherever it is needed

6. Connect the The API Gateway WebSocket

# Get your web socket url
terraform output websocket_endpoint
# Get your rest Api url
terraform output rest_api_endpoint
# These endpoints are created using Amazon API Gateway.
# Redeploy the frontend so the changes reach the S3 bucket:
aws s3 sync ./frontend s3://[REPLACE WITH YOUR BUCkET NMAE]

7. Test the Real-Time Sentiment Pipeline

# Go to your website and send a chat message
send ... I am very angry, my order never arrived and this is terrible!

# Go to your slack to confrim alert

# confirm DynamoDb is storing your data

# Confirm Sentiment Update on supervisor Dashboard

8. Set up GitHub Actions

# Copy and set up your workflow files. # deploy.yml / # destroy.yml
# Verify your IAM role already has the OIDC trust policy
aws iam get-role \
  --role-name <YOUR_GITHUB_ACTIONS_ROLE_NAME> \
  --query "Role.AssumeRolePolicyDocument"

# Add only ONE secret in GitHub: Your Slack webhook URL 

# Secret                   # Value
SLACK_WEBHOOK_URL          Your Slack webhook URL 

# Note : This project uses OIDC authentication, meaning GitHub can securely deploy infrastructure without storing AWS access keys.

# Create the GitHub OIDC provider

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com \
  --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1

9. Push and Test the CI/CD Pipeline

# Push 
git add .github/
git commit -m "Add GitHub Actions CI/CD with OIDC auth"
git push origin main

Teardown If you don't want to keep it running

terraform destroy   # Removes ALL AWS resources

Troubleshooting(IMPORTANT)

# While setting up the project, you may encounter some of the following issues. Below are common problems and how to resolve them.

1. OIDC Provider Not Found

If GitHub Actions cannot assume the IAM role, the OIDC provider may not exist.

Fix

Create the OIDC provider in AWS:

token.actions.githubusercontent.com

Then ensure the IAM role trust policy allows your GitHub repository.

2. GitHub Actions Role Missing S3 Permissions

If the CI/CD pipeline fails during frontend deployment, the GitHub Actions role may lack S3 permissions.

Fix

Ensure the IAM policy includes:

s3:PutObject
s3:DeleteObject
s3:ListBucket

for the frontend bucket.

3. Duplicate Terraform Backend Block

Terraform only allows one backend block.

Fix

Ensure only one backend configuration exists:

terraform {
  backend "s3" {}
}

Remove duplicate backend declarations.

4. State Lock Conflict Between Plan and Apply Jobs

If two workflows attempt to access Terraform state simultaneously, you may see a lock error.

Fix

Ensure your backend uses DynamoDB state locking and avoid running multiple Terraform jobs simultaneously.

5. Terraform Plan Timing Out

Large plans in CI/CD may time out.

Fix

Increase the GitHub Actions job timeout or optimize Terraform resources to reduce planning time.

6. Cannot Pass -var with Saved Plan

If you generate a saved plan (tfplan), you cannot pass new variables during terraform apply.

Fix

Use:

terraform apply tfplan

instead of passing variables again.

7. Shared Lambda Layer ZIP Not Found

If Terraform fails to deploy Lambda layers:

Error: file not found

Fix

Ensure the .build directory and ZIP packages exist before running Terraform.

Example:

terraform/.build/shared_layer.zip
8. S3 State Bucket or DynamoDB Lock Table Already Exist

If these were manually created earlier, Terraform may fail.

Fix

Either:

import them into Terraform state, or

remove them from Terraform configuration.

9. SNS Subscriptions Failing with Empty Endpoints

SNS subscriptions require valid endpoints.

Fix

Provide valid values for:

alert_email
alert_phone
slack_webhook_url

or disable unused subscriptions.

10. OIDC Not Authorised for workflow_dispatch

If manual GitHub workflows cannot assume the role, the IAM trust policy may restrict events.

Fix

Ensure the trust policy allows your repository:

repo:<your-org>/<repo-name>:*

Replicating This Project

If you would like to replicate this project, feel free to use the code in this repository. However, before deploying, make sure to carefully review and update the configuration values specific to your environment.

Important items you may need to change include:

AWS account IDs

IAM role names

GitHub repository references in IAM trust policies

Slack webhook URL used for notifications

Domain or CloudFront distribution settings

Terraform variables for environment configuration

Always review the Terraform files and GitHub Actions workflows before running deployment commands to ensure they match your own AWS account and project setup.

Final Note

This project was built as a learning exercise to explore serverless architecture, infrastructure automation, and AI-driven analytics on AWS. Contributions, feedback, and improvements are always welcome.