ShieldAPI

AI-Powered Content Moderation API with Usage-Based Billing

A serverless, production-ready content moderation API built with FastAPI, React, AWS services, and Stripe. ShieldAPI provides enterprise-grade content safety detection using AWS Rekognition and Bedrock Claude, with transparent usage-based billing.

🏗️ Architecture

┌─────────────────┐
│   React Frontend │  (Vite + Tailwind + Clerk Auth)
│  (Developer Hub) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  API Gateway    │  (Rate limiting, API key validation)
│   (The Shield)  │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌────────┐ ┌────────────────┐
│ Lambda │ │ Step Functions │  (Rekognition → Bedrock)
│        │ │  (The Brain)   │
└───┬────┘ └────────────────┘
    │
    ▼
┌─────────────┐     ┌──────────┐
│  DynamoDB   │────▶│  Stripe  │
│ (Single-Table) │  │ (Billing)│
└─────────────┘     └──────────┘

Key Components

Frontend (The Hub): React application for developer portal
API Gateway (The Shield): Request throttling and API key validation
Execution Layer (The Brain): Step Functions orchestrating AI models
Billing Engine (The Pulse): Stripe Meters for real-time usage tracking
Data Layer: DynamoDB with single-table design

🚀 Quick Start

Prerequisites

Node.js 18+ and npm
Python 3.11+
AWS CLI configured with credentials
AWS CDK installed globally: npm install -g aws-cdk
Stripe account (for billing)
Clerk account (for authentication)

1. Clone and Configure

# Clone the repository
git clone <your-repo>
cd shield_ai

# Copy environment files
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

# Edit config.yaml with your settings
nano config.yaml

2. Set Up AWS Secrets

Store your sensitive credentials in AWS Secrets Manager:

# Stripe API key
aws secretsmanager create-secret \
  --name shieldapi/stripe/api_key \
  --secret-string "sk_test_YOUR_STRIPE_KEY"

# Clerk secret key
aws secretsmanager create-secret \
  --name shieldapi/clerk/secret_key \
  --secret-string "sk_test_YOUR_CLERK_KEY"

3. Deploy Infrastructure

cd infra

# Install dependencies
pip install -r requirements.txt

# Bootstrap CDK (first time only)
cdk bootstrap

# Deploy all stacks
cdk deploy --all

Note the outputs: API Gateway URL, DynamoDB table name, Usage Plan ID

4. Set Up Stripe Billing

# Create a billing meter for usage tracking
stripe meters create \
  --display-name "Moderation API Usage" \
  --event-name moderation_usage \
  --value-settings '{"event_payload_key": "value"}' \
  --default-aggregation '{"formula": "sum"}'

# Update config.yaml with the meter ID

5. Run Backend Locally

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run FastAPI server
uvicorn app.main:app --reload

API will be available at http://localhost:8000

6. Run Frontend Locally

cd frontend

# Install dependencies
npm install

# Start dev server
npm run dev

Frontend will be available at http://localhost:3000

📋 Configuration

All settings are centralized in config.yaml:

project:
  name: "ShieldAPI"
  stage: "prod"
  region: "us-east-1"

billing:
  provider: "stripe"
  meter_id: "mtr_12345"  # Update after creating Stripe meter

auth:
  provider: "clerk"
  jwt_issuer: "https://clerk.your-app.com"

limits:
  free_tier_monthly: 100
  burst_limit: 5
  rate_limit: 2

🔑 API Usage

1. Onboard and Get API Key

Sign up at the frontend (/dashboard) or call the onboard endpoint:

curl -X POST https://your-api-url/onboard \
  -H "Content-Type: application/json" \
  -d '{
    "clerk_user_id": "user_xyz",
    "email": "dev@example.com",
    "jwt": "eyJ..."
  }'

Response:

{
  "success": true,
  "api_key": "abcd1234...",
  "stripe_customer_id": "cus_xyz"
}

2. Moderate Content

curl -X POST https://your-api-url/moderate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/image.jpg",
    "idempotency_key": "unique-request-id"
  }'

Response:

{
  "success": true,
  "execution_arn": "arn:aws:states:...",
  "status": "PROCESSING"
}

🗄️ Database Schema (DynamoDB)

Single-Table Design:

PK	SK	Attributes
`USER#<id>`	`PROFILE`	`email`, `stripe_customer_id`, `created_at`
`USER#<id>`	`API_KEY#<val>`	`aws_key_id`, `status`
`USAGE#<id>`	`DATE#<iso>`	`total_calls`, `endpoint`
`USER#<id>`	`IDEMPOTENCY#<key>`	`response`, `timestamp`

Global Secondary Indexes:

ApiKeyIndex: Query by api_key
StripeCustomerIndex: Query by stripe_customer_id

🔐 Security Checklist

✅ Secrets in AWS Secrets Manager (never hardcoded)
✅ JWT validation with Clerk
✅ Idempotency keys for duplicate prevention
✅ Stripe webhook signature verification
✅ API key rotation support
✅ DynamoDB encryption at rest
✅ Rate limiting at API Gateway level

🧪 Testing

Test Onboarding

cd backend
python -m pytest tests/test_onboarding.py

Test Moderation Pipeline

# Start a moderation request
curl -X POST http://localhost:8000/moderate \
  -H "x-api-key: test-key" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/test.jpg"}'

📊 Monitoring & Debugging

View CloudWatch Logs

# API Gateway logs
aws logs tail /aws/apigateway/ShieldAPI --follow

# Lambda logs
aws logs tail /aws/lambda/OnboardFunction --follow

# Step Functions execution history
aws stepfunctions list-executions \
  --state-machine-arn <your-state-machine-arn>

View DynamoDB Items

aws dynamodb scan --table-name shieldapi-users

Check Stripe Events

stripe events list --limit 10

🚢 Deployment to Production

Frontend Deployment (S3 + CloudFront)

cd frontend

# Build production bundle
npm run build

# Deploy to S3
aws s3 sync dist/ s3://shieldapi-frontend-prod --delete

# Invalidate CloudFront cache
aws cloudfront create-invalidation \
  --distribution-id <your-distribution-id> \
  --paths "/*"

Infrastructure Updates

cd infra

# Preview changes
cdk diff

# Deploy updates
cdk deploy --all

🔄 Step Functions Pipeline

Moderation State Machine:

┌──────────────────┐
│  Rekognition     │ (Detect moderation labels)
│  Detection       │
└────────┬─────────┘
         │
         ▼
    ┌────────┐
    │ Choice │ (High confidence violation?)
    └───┬────┘
        │
   ┌────┴─────┐
   │          │
   ▼          ▼
┌──────┐  ┌─────────┐
│ Flag │  │ Bedrock │ (Contextual analysis)
│      │  │ Claude  │
└──────┘  └────┬────┘
               │
               ▼
         ┌──────────┐
         │ Format   │
         │ Response │
         └──────────┘

💰 Pricing Model

Free Tier: 100 requests/month (tracked via Stripe Meters)

Usage-Based:

Requests 1-100: Free
Requests 101-1,000: $0.01 each
Requests 1,000+: $0.005 each

Billing is handled automatically through Stripe with real-time metering.

📚 Project Structure

shield_ai/
├── config.yaml                 # Central configuration
├── .github/
│   └── copilot-instructions.md # Project guidelines
├── infra/                      # AWS CDK infrastructure
│   ├── app.py
│   ├── stacks/
│   │   ├── api_stack.py
│   │   ├── database_stack.py
│   │   └── pipeline_stack.py
│   └── utils/
│       └── config_loader.py
├── backend/                    # FastAPI application
│   ├── app/
│   │   ├── main.py
│   │   ├── config.py
│   │   └── services/
│   │       ├── auth.py
│   │       ├── billing.py
│   │       ├── database.py
│   │       └── stepfunctions.py
│   └── lambdas/
│       ├── onboard/
│       ├── moderate/
│       └── webhook/
└── frontend/                   # React application
    ├── src/
    │   ├── pages/
    │   │   ├── Landing.jsx
    │   │   └── Dashboard.jsx
    │   └── components/
    │       ├── ApiKeyManager.jsx
    │       ├── UsageChart.jsx
    │       └── BillingPortal.jsx
    └── package.json

🛠️ Troubleshooting

Issue: CDK Deploy Fails

Solution: Ensure AWS credentials are configured and you've run cdk bootstrap

aws configure
cdk bootstrap aws://ACCOUNT-ID/REGION

Issue: API Key Not Working

Solution: Check API key is associated with usage plan:

aws apigateway get-usage-plan-keys --usage-plan-id <plan-id>

Issue: Stripe Billing Not Recording

Solution: Verify webhook endpoint is receiving events:

stripe listen --forward-to localhost:8000/webhook

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License

MIT License - see LICENSE file for details

🔗 Resources

📧 Support

For issues or questions:

Open an issue on GitHub
Email: support@shieldapi.com

Built with ❤️ using FastAPI, React, and AWS

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github		.github
backend		backend
docs		docs
frontend		frontend
infra		infra
.gitignore		.gitignore
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
config.yaml		config.yaml
logs.sh		logs.sh
start.sh		start.sh
stop.sh		stop.sh

Folders and files

Latest commit

History

Repository files navigation

ShieldAPI

🏗️ Architecture

Key Components

🚀 Quick Start

Prerequisites

1. Clone and Configure

2. Set Up AWS Secrets

3. Deploy Infrastructure

4. Set Up Stripe Billing

5. Run Backend Locally

6. Run Frontend Locally

📋 Configuration

🔑 API Usage

1. Onboard and Get API Key

2. Moderate Content

🗄️ Database Schema (DynamoDB)

🔐 Security Checklist

🧪 Testing

Test Onboarding

Test Moderation Pipeline

📊 Monitoring & Debugging

View CloudWatch Logs

View DynamoDB Items

Check Stripe Events

🚢 Deployment to Production

Frontend Deployment (S3 + CloudFront)

Infrastructure Updates

🔄 Step Functions Pipeline

💰 Pricing Model

📚 Project Structure

🛠️ Troubleshooting

Issue: CDK Deploy Fails

Issue: API Key Not Working

Issue: Stripe Billing Not Recording

🤝 Contributing

📄 License

🔗 Resources

📧 Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages