310 lines
13 KiB
Markdown
310 lines
13 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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 | — | — | ✅ |
|