​

Statistics & Limits Audit

​

Overview

​

Organization Limits (OrganizationLimitsResponse)

​

✅ Fully Implemented

​

✅ Calculated Correctly

​

✅ Enforcement

​

Project Statistics (ProjectStatsResponse)

​

Database Fields (project_stats table)

​

AWS Integration Status

​

✅ Implemented

​

⚠️ Needs Implementation

​

Recommended AWS Lambda Functions

​

1. MQTT Message Counter Lambda

# Pseudo-code
def handler(event, context):
    topic = event['topic']
    device_id = extract_device_id(topic)

    # Get project from device
    project = get_project_by_device(device_id)

    # Increment counter
    if topic.startswith('$aws/things/{device}/shadow'):
        increment_mqtt_inbound(project.id)

​

2. Hourly Stats Updater Lambda

def handler(event, context):
    for project in get_all_projects():
        stats_updater = StatsUpdaterService(db)
        stats_updater.update_project_stats(project)

​

3. Monthly Stats Reset Lambda

def handler(event, context):
    for project in get_all_projects():
        stats_updater = StatsUpdaterService(db)
        stats_updater.reset_monthly_stats(project)

​

Action Items

​

🔴 Critical (Needed for MVP)

1. Implement MQTT message tracking Lambda
   • Create IoT Rule to capture all device messages
   • Lambda function to increment inbound/outbound counters
   • Deploy to CDK stack
2. Add MQTT limit enforcement
   • Check limits before allowing device to publish (IoT Policy?)
   • Check limits before backend publishes to device
   • Return 402 error when limit exceeded
3. Fix storage tracking
   • Query S3 bucket size via CloudWatch
   • Query ECR image sizes
   • Update storage fields in stats

​

🟡 Important (Post-MVP)

4. Add API call tracking middleware
   • FastAPI middleware to count requests
   • Increment current_month_api_calls
   • Enforce API rate limits
5. Add deployment tracking
   • Increment counter when capsule is deployed
   • Track in sessions API
6. Create scheduled Lambda for stats updates
   • Deploy hourly stats updater
   • Deploy monthly reset function

​

🟢 Nice to Have

7. Add CloudWatch dashboards
   • Visualize MQTT message rates
   • Show storage trends
   • Alert on approaching limits
8. Historical data warehouse
   • Archive monthly stats to S3/Redshift
   • Enable trend analysis
   • Billing report generation

​

Testing Checklist

• Create free tier organization
• Verify all limits are set correctly
• Create project and verify device limit enforcement
• Register device up to limit
• Try to register one more device (should fail with 402)
• Send MQTT messages and verify counters increment
• Check that limit enforcement works for MQTT
• Push ECR images up to limit
• Try to push one more (should fail)
• Verify frontend displays all limits correctly
• Check that stats endpoint returns all fields
• Test monthly reset (mock date to next month)

​

CDK Stack Integration

​

Required Environment Variables

# Backend service needs these
ECR_REPOSITORY_URI=<from CDK output>
AWS_REGION=us-west-2
AWS_IOT_ENDPOINT=<account>.iot.us-west-2.amazonaws.com
S3_BUCKET=<from CDK>

​

Required IAM Permissions

• ecr:ListImages - List images in repository
• ecr:DescribeImages - Get image details (size)
• cloudwatch:GetMetricStatistics - Query MQTT metrics
• s3:GetBucketSize - Query bucket size (via CloudWatch)
• iot:ListThings - List devices (for filtering)

• dynamodb:GetItem / dynamodb:UpdateItem - Access project_stats
• Or use RDS Proxy to access PostgreSQL

​

Summary

​

✅ Working

• Organization limits are properly defined
• Limit enforcement for projects, users, devices, ECR images
• Basic stats collection (devices, sessions, logs)
• Frontend displays limits correctly

​

⚠️ Needs Attention

• MQTT message tracking is NOT implemented - counters exist but never increment
• Storage tracking is incomplete - no S3/ECR size queries
• Stats are created but never updated - need scheduled updates
• Monthly reset is not automated - need Lambda trigger

​

🔴 Critical Missing Pieces

1. IoT Rule + Lambda for MQTT tracking
2. MQTT limit enforcement in publish operations
3. Scheduled Lambda for stats updates
4. S3/ECR storage size queries