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
Email	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	—	—	✅