AWS Looksmax

AWS Looksmax is a live facial scoring leaderboard built for cloud workshops. Participants upload a selfie, Amazon Rekognition analyzes their face, and a custom algorithm scores them across 6 metrics in real time. Results appear instantly on a shared wall for everyone to see.

---

How it works

Two stacks run together: a host stack deployed once by the organizer, and a participant stack each attendee deploys themselves.

Participant side

1. Participant deploys participant_template/ - creates a personal S3 bucket and Lambda
2. Participant uploads their photo to their S3 bucket
3. Lambda calls Rekognition to extract facial landmarks, emotions, age, and smile confidence
4. Results are published to the host's shared SNS topic

Host side

1. ReceiverFunction picks up the SNS message and runs the looksmax algorithm:

   • Corrects landmarks for head roll
   • Scores 6 facial metrics:

   Metric	Weight
   Canthal Tilt	20%
   Jawline Definition	20%
   Facial Symmetry	20%
   Eye Symmetry	15%
   Interocular Distance	15%
   Face Ratio	10%

   • Assigns a tier: Godtier (90+) / Chad (75+) / Decent (60+) / Average (45+) / Struggle (0+)
   • Writes the result to DynamoDB

2. ResultsFunction serves the leaderboard over HTTP:

   • GET /results - all entries sorted by score
   • DELETE /results/{id} - remove an entry

3. frontend/wall.html is the live leaderboard - open it in a browser, it polls every 3 seconds and shows ranked cards with photo, score, tier, metric bars, emotion, and age. The host can delete any card in real time.

---

Setup

Prerequisites

• AWS CLI configured with credentials
• AWS SAM CLI

1. Deploy the host stack

sam build && sam deploy

Copy the ApiEndpoint from the stack outputs. Open frontend/wall.html and set it as API_ENDPOINT near the top of the script, then open the file in a browser.

2. Deploy a participant stack

Edit participant_template/functions/upload_and_analyze/app.py and fill in:

NAME      = "your_name"
TOPIC_ARN = "arn:aws:sns:eu-west-3:<host-account-id>:looksmax-submit"

The host's SubmitTopicArn stack output has the exact ARN.

cd participant_template
sam build && sam deploy

Then upload a photo:

aws s3 cp your_photo.jpg s3://participant-photos-<account-id>-eu-west-3/

---

Host utilities

make build             # Build the host stack
make deploy            # Build and deploy the host stack
make participant-deploy # Build and deploy the participant stack
make logs-receiver     # Stream receiver Lambda logs
make logs-upload       # Stream upload Lambda logs
make flush             # Wipe all DynamoDB entries
make clean             # Remove local .aws-sam artifacts

One-time migration

If you have existing DynamoDB records with expired presigned URLs (missing photo_bucket/photo_key):

python scripts/migrate_photo_refs.py --dry-run  # preview
python scripts/migrate_photo_refs.py             # apply