IntakeIQ Server Infrastructure Documentation

1 Executive Summary

IntakeIQ is an AI-powered dental intake automation platform deployed on Amazon Web Services (AWS). The infrastructure is purpose-built for healthcare workloads, with HIPAA compliance as a first-class architectural requirement rather than an afterthought.

Why AWS

AWS provides the most comprehensive suite of HIPAA-eligible services in the cloud market. Every service used in this stack is covered under the AWS Business Associate Addendum (BAA), which is a legal prerequisite for processing Protected Health Information (PHI).

HIPAA Compliance Posture

Infrastructure at a Glance

2 Architecture Overview

The stack follows a three-tier architecture: load balancer, application, and database. All traffic enters through a single HTTPS endpoint on the Application Load Balancer, flows to a containerized Next.js application on ECS Fargate, and persists in an encrypted PostgreSQL database on RDS.

Data Flow

1. Patient opens intake form in their browser (HTTPS via ALB).
2. ALB terminates TLS and forwards the request to the ECS Fargate container on port 3000.
3. The Next.js application processes the form, encrypts PHI fields using the KMS-backed encryption key, and writes to PostgreSQL via Prisma ORM.
4. Insurance card images are uploaded directly to S3 with KMS server-side encryption.
5. All application events are streamed to CloudWatch Logs with 7-year retention.

3 AWS Services Used

4 Cost Breakdown

Year 1 Breakdown (New AWS Account)

Cost Optimizations Applied

Scaling Cost Projections

5 Network Architecture

VPC Layout

Security Groups

6 Security Model

Defense in Depth

KMS Key Policy

The customer-managed KMS key (alias/intakeiq-phi-key) is used for:

• RDS storage encryption
• S3 object encryption (insurance cards)
• CloudWatch log group encryption
• Application-level PHI field encryption (Encrypt/Decrypt/GenerateDataKey)

Key policy grants kms:* to the root account and kms:Decrypt, kms:Encrypt, kms:GenerateDataKey to the ECS Task Role only.

7 Database

Connection String

Stored in SSM Parameter Store at /intakeiq/DATABASE_URL:

postgresql://intakeiq:<password>@<rds-endpoint>:5432/intakeiq

Storage Auto-Scaling

RDS is configured with MaxAllocatedStorage: 100. When the database reaches 90% of its allocated storage, AWS will automatically increase it in 10 GB increments up to 100 GB, with no downtime. gp3 storage provides 3,000 IOPS baseline regardless of volume size.

8 Container Platform

ECS Fargate Configuration

Docker Multi-Stage Build

The Dockerfile uses a three-stage build process to minimize image size and attack surface:

The final image contains only the Next.js standalone output, static assets, and Prisma client. No dev dependencies, no source code, no build tooling.

Security

• Non-root user: nextjs (UID 1001, GID 1001)
• Alpine Linux base (minimal attack surface)
• Next.js telemetry disabled (NEXT_TELEMETRY_DISABLED=1)

Health Check

# Container-level (ECS Task Definition)
CMD-SHELL wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1
# Interval: 30s | Timeout: 5s | Retries: 3 | Start Period: 60s

# ALB Target Group health check
Path: /
Interval: 30s | Timeout: 5s | Healthy: 2 | Unhealthy: 3

Zero-Downtime Deployments

The ECS Service is configured with:

• MinimumHealthyPercent: 100 — the existing task stays running
• MaximumPercent: 200 — a new task starts alongside the old one

During deployment, ECS launches a new task with the updated image, waits for it to pass health checks, registers it with the ALB target group, then drains and stops the old task. Zero requests are dropped.

9 Storage

S3 Bucket — Insurance Card Uploads

Public Access Block

BlockPublicAcls:       true
BlockPublicPolicy:     true
IgnorePublicAcls:      true
RestrictPublicBuckets: true

TLS-Only Bucket Policy

A bucket policy explicitly denies all S3 operations when aws:SecureTransport is false. This ensures insurance card images are never transmitted in plaintext, even within the AWS network.

Access Control

Only the ECS Task Role has S3 permissions, limited to:

• s3:PutObject, s3:GetObject, s3:DeleteObject on bucket objects
• s3:ListBucket on the bucket itself

No other IAM principal (including the deployment user) has default access to patient insurance cards.

10 Logging & Monitoring

CloudWatch Logs

How to Tail Logs

# Live tail (last 30 minutes)
aws logs tail /ecs/intakeiq --since 30m --region us-east-1

# Follow mode (real-time streaming)
aws logs tail /ecs/intakeiq --follow --region us-east-1

# Search for errors
aws logs filter-log-events \
  --log-group-name /ecs/intakeiq \
  --filter-pattern "ERROR" \
  --start-time $(date -d '1 hour ago' +%s000) \
  --region us-east-1

Cost Monitoring

AWS Budgets should be configured to alert before spending exceeds expectations:

RDS Monitoring

• Performance Insights — enabled with 7-day free retention. View query performance, wait events, and top SQL.
• Enhanced Monitoring — 60-second granularity OS metrics (CPU, memory, disk I/O, network).

11 Deployment Guide

Prerequisites

• AWS account with credit card on file
• AWS CLI installed and configured (brew install awscli && aws configure)
• Docker Desktop installed and running
• Domain name ready (e.g., app.intakeiq.com)

Step-by-Step Deployment

# Change provider from sqlite to postgresql
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

cd app && npm install

chmod +x deployment/deploy.sh
cd deployment
./deploy.sh

# Get the ALB DNS name
aws cloudformation describe-stacks --stack-name intakeiq-stack \
  --query 'Stacks[0].Outputs[?OutputKey==`ALBDNSName`].OutputValue' \
  --output text

# Generate real secrets
openssl rand -base64 32   # NEXTAUTH_SECRET
openssl rand -hex 32      # PHI_ENCRYPTION_KEY

aws ecs update-service \
  --cluster intakeiq-cluster \
  --service intakeiq-service \
  --force-new-deployment \
  --region us-east-1

# Enable ECS Exec (one-time)
aws ecs update-service \
  --cluster intakeiq-cluster \
  --service intakeiq-service \
  --enable-execute-command \
  --region us-east-1

# Get the running task ID
TASK_ID=$(aws ecs list-tasks \
  --cluster intakeiq-cluster \
  --service-name intakeiq-service \
  --query 'taskArns[0]' \
  --output text \
  --region us-east-1)

# SSH into the container
aws ecs execute-command \
  --cluster intakeiq-cluster \
  --task $TASK_ID \
  --container intakeiq \
  --interactive \
  --command "/bin/sh" \
  --region us-east-1

# Inside the container:
npx prisma migrate deploy

12 Operations Runbook

Deploy an Application Update

# 1. Authenticate with ECR
AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
ECR_URI="${AWS_ACCOUNT_ID}.dkr.ecr.us-east-1.amazonaws.com/intakeiq"

aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  ${AWS_ACCOUNT_ID}.dkr.ecr.us-east-1.amazonaws.com

# 2. Build and push
docker build -t intakeiq ../app
docker tag intakeiq:latest ${ECR_URI}:latest
docker push ${ECR_URI}:latest

# 3. Force new deployment (zero-downtime)
aws ecs update-service \
  --cluster intakeiq-cluster \
  --service intakeiq-service \
  --force-new-deployment \
  --region us-east-1

SSH into Running Container (ECS Exec)

TASK_ID=$(aws ecs list-tasks \
  --cluster intakeiq-cluster \
  --service-name intakeiq-service \
  --query 'taskArns[0]' --output text --region us-east-1)

aws ecs execute-command \
  --cluster intakeiq-cluster \
  --task $TASK_ID \
  --container intakeiq \
  --interactive \
  --command "/bin/sh" \
  --region us-east-1

Run Database Migrations

# SSH into the container first (see above), then:
npx prisma migrate deploy

Restart the Service

aws ecs update-service \
  --cluster intakeiq-cluster \
  --service intakeiq-service \
  --force-new-deployment \
  --region us-east-1

Check Service Status

# Service overview
aws ecs describe-services \
  --cluster intakeiq-cluster \
  --services intakeiq-service \
  --query 'services[0].{Status:status,Running:runningCount,Desired:desiredCount,Deployments:deployments[*].{Status:status,Running:runningCount,Desired:desiredCount}}' \
  --region us-east-1

# Recent logs
aws logs tail /ecs/intakeiq --since 30m --region us-east-1

# CloudFormation stack outputs
aws cloudformation describe-stacks \
  --stack-name intakeiq-stack \
  --query 'Stacks[0].Outputs' \
  --region us-east-1

Update an SSM Secret

aws ssm put-parameter \
  --name "/intakeiq/NEXTAUTH_SECRET" \
  --value "your-new-secret-value" \
  --type String \
  --overwrite \
  --region us-east-1

# Restart to pick up new value
aws ecs update-service \
  --cluster intakeiq-cluster \
  --service intakeiq-service \
  --force-new-deployment \
  --region us-east-1

13 Disaster Recovery

Recovery Scenarios

Scenario: Database corruption or accidental deletion

# List available snapshots
aws rds describe-db-snapshots \
  --db-instance-identifier intakeiq-db \
  --query 'DBSnapshots[*].{ID:DBSnapshotIdentifier,Time:SnapshotCreateTime,Status:Status}' \
  --region us-east-1

# Restore from a snapshot (creates a new RDS instance)
aws rds restore-db-instance-from-db-snapshot \
  --db-instance-identifier intakeiq-db-restored \
  --db-snapshot-identifier <snapshot-id> \
  --region us-east-1

Scenario: Complete infrastructure loss

1. Check out the CloudFormation template from Git
2. Re-run the deploy script (deployment/deploy.sh)
3. Restore the RDS database from the most recent snapshot
4. Update SSM parameters with the correct secrets
5. Point the domain CNAME to the new ALB

14 Scaling Guide

When and How to Scale

Scaling ECS Tasks (Quick)

aws ecs update-service \
  --cluster intakeiq-cluster \
  --service intakeiq-service \
  --desired-count 2 \
  --region us-east-1

Scaling RDS (Quick)

# Modify instance class (causes ~5 min downtime during maintenance window)
aws rds modify-db-instance \
  --db-instance-identifier intakeiq-db \
  --db-instance-class db.t4g.small \
  --apply-immediately \
  --region us-east-1

15 Troubleshooting

CloudFormation stack creation failed

# Find the first failure event
aws cloudformation describe-stack-events \
  --stack-name intakeiq-stack \
  --region us-east-1 \
  --query 'StackEvents[?ResourceStatus==`CREATE_FAILED`].{Resource:LogicalResourceId,Reason:ResourceStatusReason}'

Common causes: insufficient IAM permissions, invalid DB password (too short), region limits, or service quotas.

ECS tasks keep restarting

# Check recent application logs
aws logs tail /ecs/intakeiq --since 30m --region us-east-1

# Check stopped task exit reason
aws ecs describe-tasks \
  --cluster intakeiq-cluster \
  --tasks $(aws ecs list-tasks --cluster intakeiq-cluster --desired-status STOPPED --query 'taskArns[0]' --output text --region us-east-1) \
  --region us-east-1 \
  --query 'tasks[0].{StopCode:stopCode,StoppedReason:stoppedReason,ExitCode:containers[0].exitCode}'

Common causes: missing/invalid DATABASE_URL, Prisma migration not run, secrets still set to CHANGE_ME_AFTER_DEPLOY, container health check failing.

SSL certificate stuck in "Pending validation"

Fix: Verify the CNAME record in your DNS provider matches exactly what ACM shows (including the trailing dot, if your provider requires it). DNS propagation can take up to 30 minutes. Use dig to verify:

dig CNAME _acme-challenge.app.intakeiq.com

Cannot connect to the database

By design, RDS is in private subnets with no public access. You cannot connect from your laptop. To access the database, use ECS Exec to shell into the running container, then use psql or Prisma from inside.

Application returns 502 Bad Gateway

Common causes:

• ECS task hasn't finished starting (wait 60s for the start period)
• Application crashed — check CloudWatch logs
• Health check path (/) is returning non-200 status
• Security group misconfigured — verify ECS SG allows port 3000 from ALB SG

Out of memory errors

The container has 512 MB RAM. If the application needs more:

# Update the task definition to 1 GB
# Edit cloudformation.yml: change Memory from '512' to '1024'
# Then redeploy the CloudFormation stack
aws cloudformation update-stack \
  --stack-name intakeiq-stack \
  --template-body file://cloudformation.yml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameters ... \
  --region us-east-1

Quick Diagnostic Checklist