ShieldAI
Multi-layered consumer identity protection against predatory AI-driven scams.
ShieldAI combines three detection engines — voice cloning detection, dark web monitoring, and real-time spam classification — to give consumers proactive defense against modern identity fraud.
The Pitch
Scammers are weaponizing AI at scale: voice clones that sound exactly like your family, hyper-personalized phishing messages that bypass filters, and synthetic identities that exploit stolen data within hours of a breach. Legacy credit monitoring is reactive — it tells you after the damage is done.
ShieldAI flips the model. We detect the scam as it happens:
- VoicePrint analyzes inbound calls in real time to flag synthetic AI-generated voices before you're socially engineered.
- DarkWatch continuously monitors dark web forums, breach databases, and data broker caches — notifying you the moment your credentials, phone, or SSN surface.
- SpamShield intercepts and classifies spam calls and SMS at the network level, blocking threats before they reach your phone.
Backed by ML models (ECAPA-TDNN, BERT) and a real-time alert pipeline, ShieldAI gives consumers enterprise-grade threat detection for their personal life.
Architecture Overview
┌─────────────────────────────────────────────────────────┐
│ Clients │
│ Mobile (Expo/RN) │ Web (SolidJS) │ Browser Extension │
└──────────┬──────────────────────────────┬───────────────┘
│ REST + WebSocket │
▼ ▼
┌──────────────────────┐ ┌──────────────────────────────┐
│ API Gateway │ │ WebSocket Alert Server │
│ (Fastify 5) │ │ (Real-time push) │
└──────┬───────┬───────┘ └──────────────────────────────┘
│ │
▼ ▼
┌──────────┐ ┌─────────────────────────────────────────────┐
│ Auth │ │ Microservices │
│(NextAuth)│ │ VoicePrint │ DarkWatch │ SpamShield │
└──────────┘ │ HomeTitle │ RemoveBrokers │
└──────────┬──────────┬───────────────────────┘
│ │
┌────────▼──────────▼────────┐
│ Background Workers │
│ (BullMQ + Redis) │
└────────┬───────────────────┘
│
┌────────▼────────┐
│ PostgreSQL │
│ + Redis │
└─────────────────┘
Features & Implementation Status
| Feature | Service | Status | Notes |
|---|---|---|---|
| Voice enrollment & profile management | VoicePrint | ✅ Done | Register family voice profiles |
| Audio preprocessing (VAD, noise reduction) | VoicePrint | ✅ Done | WebRTC VAD + RNNoise |
| Synthetic voice detection (ECAPA-TDNN) | VoicePrint | ✅ Done | FAISS vector index for matching |
| Real-time streaming audio analysis | VoicePrint | ✅ Done | WebSocket-based |
| Batch audio analysis | VoicePrint | ✅ Done | Configurable confidence thresholds per tier |
| HIBP breach checking | DarkWatch | ✅ Done | Email + password breach lookup |
| Dark web multi-source scanning | DarkWatch | ✅ Done | HIBP, SecurityTrails, Censys, Shodan, forums |
| Watch list management | DarkWatch | ✅ Done | Emails, phones, SSN (hashed) |
| Scheduled + real-time scanning | DarkWatch | ✅ Done | Tier-based frequency |
| Fuzzy matching engine | DarkWatch | ✅ Done | Levenshtein + exact matching |
| Severity-scored alert pipeline | DarkWatch | ✅ Done | Dedup pipeline |
| PDF report generation | DarkWatch | ✅ Done | Handlebars + PDFKit |
| Number reputation (Hiya/Truecaller) | SpamShield | ✅ Done | Circuit breaker pattern |
| SMS classification (BERT) | SpamShield | ✅ Done | ML-based spam detection |
| Call analysis rule engine | SpamShield | ✅ Done | Multi-layer scoring |
| Real-time carrier interception | SpamShield | ⏳ In Progress | Twilio/Plivo integration |
| Real-time WebSocket alerts | SpamShield | ✅ Done | Alert broadcasting |
| User feedback loop (FP/FN) | SpamShield | ✅ Done | Metadata validation |
| Phone validation (E.164) | SpamShield | ✅ Done | Normalization |
| Audit logging | SpamShield | ✅ Done | All decisions logged |
| SpamShield rate limiting | SpamShield | ⏳ In Progress | Per-endpoint + global |
| SpamShield route optimization | SpamShield | ⏳ In Progress | Route consolidation |
| Feature flags | All | ✅ Done | Env-variable toggles |
| Property record matching | HomeTitle | ✅ Done | Fuzzy string matching |
| Change detection (ownership, liens) | HomeTitle | ✅ Done | County deed scanning |
| Watchlist management | HomeTitle | ✅ Done | |
| Scheduled county deed scanning | HomeTitle | ✅ Done | |
| Alert pipeline | HomeTitle | ✅ Done | Severity classification |
| Data broker removal requests | RemoveBrokers | ✅ Done | |
| Broker API integration | RemoveBrokers | ✅ Done | With caching |
| User auth (JWT, RBAC) | Shared | ✅ Done | NextAuth.js |
| Family group management | Shared | ✅ Done | |
| Stripe subscriptions & billing | Shared | ✅ Done | Tier-based feature gating |
| Email (Resend) | Shared | ✅ Done | Transactional + marketing |
| Push notifications (FCM/APNs) | Shared | ✅ Done | Android + iOS |
| SMS (Twilio) | Shared | ✅ Done | |
| Mixpanel analytics (30+ events) | Shared | ✅ Done | KPI tracking |
| Datadog APM + Sentry | Shared | ✅ Done | Full observability |
| Cross-service event correlation | Shared | ✅ Done | Alert correlation engine |
| Browser extension (MV3) | Extension | ✅ Done | Phishing detection |
| Mobile app (Expo RN) | Mobile | ✅ Done | iOS + Android |
| Shared UI component library | Shared UI | ✅ Done | SolidJS |
| CI/CD pipelines | DevOps | ✅ Done | GitHub Actions |
| Terraform infrastructure | DevOps | ✅ Done | AWS ECS, RDS, ElastiCache |
| Load testing (k6) | DevOps | ✅ Done | VoicePrint + DarkWatch |
| Docker + Compose | DevOps | ✅ Done | Dev + prod configs |
| Integration tests | QA | ⏳ In Progress | Coverage expanding |
| Rate limit tests | QA | ⏳ In Progress |
Tech Stack
| Layer | Technology |
|---|---|
| Language | TypeScript (Node.js ≥20) |
| API | Fastify 5 (CORS, Helmet, rate-limit, Swagger, multipart) |
| Frontend | SolidJS + Vite |
| Mobile | React Native / Expo SDK 51 |
| Extension | Chrome Manifest V3 |
| Databases | PostgreSQL 15/16 (Prisma ORM) + Turso/SQLite (Drizzle) |
| Cache / Queue | Redis + BullMQ |
| Auth | NextAuth.js + JWT |
| Billing | Stripe |
| Resend | |
| Push | Firebase Cloud Messaging + APNs |
| SMS | Twilio |
| Analytics | Mixpanel / Segment |
| Monitoring | Datadog APM + Sentry |
| ML Models | ECAPA-TDNN (voice), BERT (SMS), FAISS (vector index) |
| Infrastructure | Terraform (AWS ECS Fargate, RDS, ElastiCache, S3, ALB) |
| CI/CD | GitHub Actions |
| Monorepo | pnpm workspaces + Turborepo |
| Testing | Vitest, Jest, k6 |
Getting Started
Prerequisites
- Node.js >= 20.0.0
- pnpm >= 9.0.0
- Docker & Docker Compose
Setup
# Install all dependencies
pnpm install
# Start local infrastructure (Postgres, Redis, Mailhog)
docker compose up -d
# Copy environment variables
cp .env.example .env
# Run database migrations
pnpm db:migrate
# Start all development servers
pnpm dev
This launches the API server, all microservices, and the web frontend concurrently via Turborepo.
Building
# Build all packages and services
pnpm build
# Build individual Docker images
docker build -f packages/api/Dockerfile -t shieldai-api .
docker build -f services/spamshield/Dockerfile -t shieldai-spamshield .
docker build -f services/darkwatch/Dockerfile -t shieldai-darkwatch .
docker build -f services/voiceprint/Dockerfile -t shieldai-voiceprint .
Testing
# Run all tests
pnpm test
# With coverage
pnpm test:coverage
# Individual service tests
pnpm test --filter @shieldai/spamshield
pnpm test --filter @shieldai/darkwatch
pnpm test --filter @shieldai/voiceprint
pnpm test --filter @shieldai/hometitle
# Integration & E2E
cd packages/integration-tests && pnpm test
cd packages/integration-tests && pnpm test:e2e
# Load tests (requires k6)
cd scripts/load-test && ./run-all.sh
Production
Docker Compose
docker compose -f docker-compose.prod.yml up -d
CI/CD Pipeline (GitHub Actions)
| Event | Deploy To |
|---|---|
Push to main |
Staging |
| GitHub Release created | Production |
Pipeline stages: lint → typecheck → test → Docker build → push to GHCR → Terraform apply → ECS deploy → health check → auto-rollback on failure.
Infrastructure
All infrastructure lives in infra/ and is managed with Terraform:
- Compute: AWS ECS Fargate (API + services + workers)
- Database: RDS PostgreSQL 15/16
- Cache: ElastiCache Redis
- Storage: S3 (reports, audio samples)
- Networking: VPC, ALB, security groups
- Observability: CloudWatch + Datadog
- Secrets: AWS Secrets Manager
See infra/README.md and infra/ROLLBACK.md for detailed operational runbooks.
Project Structure
shieldai/
├── packages/ # Shared libraries (20 packages)
│ ├── api/ # Fastify API server
│ ├── core/ # Core shared logic
│ ├── db/ # Prisma schemas (v6)
│ ├── shared-db/ # Prisma schemas (v5)
│ ├── shared-auth/ # NextAuth.js
│ ├── shared-billing/ # Stripe subscriptions
│ ├── shared-notifications/ # Email, Push, SMS
│ ├── shared-analytics/ # Mixpanel/Segment
│ ├── shared-ui/ # SolidJS components
│ ├── shared-utils/ # Utilities
│ ├── types/ # Shared TypeScript types
│ ├── mobile/ # React Native / Expo app
│ ├── extension/ # Browser extension (MV3)
│ ├── jobs/ # BullMQ workers
│ ├── monitoring/ # Datadog + Sentry
│ ├── report/ # PDF generation
│ ├── correlation/ # Event correlation
│ ├── mobile-api-client/ # RN API client
│ └── integration-tests/ # E2E tests
├── services/ # Microservices (5)
│ ├── voiceprint/ # Voice cloning detection
│ ├── darkwatch/ # Dark web monitoring
│ ├── spamshield/ # Spam call/SMS blocking
│ ├── hometitle/ # Home title fraud
│ └── removebrokers/ # Data broker removal
├── infra/ # Terraform (AWS)
├── docs/ # Documentation
├── plans/ # Product & technical plans
├── scripts/ # Utility scripts
├── load-tests/ # k6 load test scripts
├── assets/ # Ad creative assets
└── server/ # Legacy WebSocket server
Documentation
| Document | Location |
|---|---|
| Product Plan | plans/SHIELDAI-product-plan.md |
| Technical Architecture | plans/SHIELDAI-technical-architecture.md |
| Infrastructure | infra/README.md |
| Rollback Runbook | infra/ROLLBACK.md |
| Stripe Integration | docs/STRIPE_INTEGRATION.md |
| Push Notifications | docs/PUSH_NOTIFICATIONS_SETUP.md |
| Mobile Push Integration | docs/MOBILE_PUSH_INTEGRATION.md |
| Mixpanel Analytics | docs/MIXPANEL_ANALYTICS.md |
| Code Review Workflow | shieldai-workflow.md |
Subscription Tiers
| Feature | Basic (Free) | Plus ($9.99/mo) | Premium ($24.99/mo) |
|---|---|---|---|
| Dark web scans | Limited | Unlimited | Unlimited |
| Spam detection | Basic | AI-powered | AI-powered |
| Voice cloning detection | — | Family | Family |
| SSN monitoring | — | — | ✅ |
| Home title protection | — | — | ✅ |
| Real-time blocking | — | — | ✅ |
| 24/7 support | — | — | ✅ |