ShieldAI/plans/SHIELDAI-technical-architecture.md

ShieldAI Technical Architecture & Implementation Plan

1. System Overview

ShieldAI is a multi-service SaaS platform with three core engines:

1. VoicePrint — voice cloning detection and synthetic voice analysis
2. DarkWatch — dark web exposure monitoring and alerting
3. SpamShield — real-time spam call/text classification and blocking

All three engines share a common platform layer (auth, billing, user management, notification system, API gateway).

---

2. High-Level Architecture

┌──────────────────────────────────────────────────────────┐
│                    Client Apps                            │
│  (Web Dashboard · Mobile App · CLI · Browser Extension)  │
└──────────────────────┬───────────────────────────────────┘
                       │ HTTPS / WSS
┌──────────────────────▼───────────────────────────────────┐
│                   API Gateway                             │
│         (Rate limiting · Auth · Routing · Logging)        │
└──┬──────────────┬──────────────┬──────────────┬──────────┘
   │              │              │              │
┌──▼─────┐  ┌────▼─────┐  ┌────▼─────┐  ┌────▼──────────┐
│Users/  │  │ VoicePrint│  │DarkWatch │  │ SpamShield    │
│Billing │  │  Service  │  │  Service │  │   Service     │
└────────┘  └───────────┘  └──────────┘  └───────────────┘
   │              │              │              │
┌──▼──────────────▼──────────────▼──────────────▼──────────┐
│                  Shared Infrastructure                    │
│  (Message Queue · Cache · Object Store · ML Pipeline)    │
└──────────────────────────────────────────────────────────┘

Tech Stack

Layer	Technology	Rationale
Language	TypeScript (Node.js)	Team velocity, shared codebase, strong ecosystem
Framework	Fastify (API), Next.js (dashboard)	Performance, SSR, mature
Database	PostgreSQL + Prisma	Relational data, type safety, migrations
Cache	Redis	Session, rate limits, real-time alert dedup
Queue	BullMQ (Redis-backed)	Dark web scan jobs, voice analysis jobs
Object Store	S3 / MinIO	Audio samples, reports, scan results
ML Runtime	Python microservice (FastAPI)	Voice analysis models, spam classification
Container	Docker + Docker Compose (dev), K8s (prod)	Portability, scaling
Infra	Terraform + AWS (ECS/Fargate or EKS)	Cloud-native, auto-scaling
CI/CD	GitHub Actions	Automated build, test, deploy

---

3. VoicePrint Service — Voice Cloning Detection

3.1 Architecture

┌──────────────┐     ┌──────────────┐     ┌─────────────────┐
│  Audio In    │────▶│ Preprocessor │────▶│ ML Classifier   │
│  (upload/   │     │ (VAD, NR,   │     │ (Synthetic vs   │
│   live call)│     │  normalization)│   │  Natural voice) │
└──────────────┘     └──────────────┘     └────────┬────────┘
                                                    │
┌──────────────┐     ┌──────────────┐     ┌────────▼────────┐
│  Alert/     │◀────│  Result      │◀────│  Voice          │
│  Dashboard  │     │  Formatter   │     │  Fingerprint    │
└──────────────┘     └──────────────┘     │  Matcher        │
                                           └─────────────────┘

3.2 Components

Audio Preprocessor (Python)

• Voice Activity Detection (VAD): Silero VAD
• Noise reduction: WebRTC VAD + RNNoise
• Sample rate normalization to 16kHz mono
• Chunking for real-time streaming analysis

ML Classifier — Synthetic Voice Detection

• Primary model: Fine-tuned ECAPA-TDNN (state-of-the-art speaker embedding)
• Secondary: WaveNet-based anomaly detector for artifacts in synthetic audio
• Training data: ASVspoof 2019/2021 corpus + internal synthetic voice samples
• Output: confidence score (0-1) that audio is synthetic/cloned
• Threshold: configurable per tier (Plus: 0.7, Premium: 0.6)

Voice Fingerprint Matcher

• Enrollments: store speaker embeddings for registered family members
• Cosine similarity matching against enrollment vault
• New voice detection: "unrecognized speaker" alerts for incoming calls
• Storage: FAISS index for fast approximate nearest neighbor search

Real-Time Call Analysis (Premium)

• WebRTC-based audio stream interception
• Sliding window analysis (5-second chunks, 1-second overlap)
• WebSocket push for real-time alerts to client

3.3 Build vs Buy

Component	Decision	Rationale
Synthetic voice detection	Build (fine-tune open models)	Core IP, differentiator, ASVspoof models are open
Voice fingerprinting	Build (ECAPA-TDNN + FAISS)	Well-understood, low cost at scale
Real-time audio pipeline	Build (WebRTC + Python)	Tight integration with blocking engine
Alternative API	Sonix or Rev.ai (fallback)	Use as secondary validation if needed

3.4 API Surface

POST   /api/v1/voiceprint/enroll          — Enroll a voice profile
GET    /api/v1/voiceprint/enrollments     — List enrolled profiles
DELETE /api/v1/voiceprint/enrollments/:id — Remove enrollment
POST   /api/v1/voiceprint/analyze         — Upload audio for analysis
WS     /api/v1/voiceprint/stream          — Real-time streaming analysis
GET    /api/v1/voiceprint/results/:id     — Get analysis result
POST   /api/v1/voiceprint/batch           — Batch analyze multiple files

---

4. DarkWatch Service — Dark Web Monitoring

4.1 Architecture

┌──────────────────────────────────────────────────────────────┐
│                    DarkWatch Service                          │
│                                                               │
│  ┌─────────────┐   ┌─────────────┐   ┌────────────────────┐ │
│  │  Scheduler  │──▶│  Data       │──▶│  Matching &        │ │
│  │  (Cron/    │   │  Ingestion  │   │  Alert Pipeline    │ │
│  │   Queue)   │   │  (APIs,     │   │  (Dedup, Severity, │ │
│  └─────────────┘   │    Scrapers)│   │   Notification)    │ │
│                    └─────────────┘   └────────────────────┘ │
│                                                               │
│  ┌─────────────┐   ┌─────────────┐   ┌────────────────────┐ │
│  │  User       │   │  Exposure   │   │  Report            │ │
│  │  Watch List │   │  Database   │   │  Generator         │ │
│  │  Manager    │   │  (Indexed)  │   │  (PDF, Digest)     │ │
│  └─────────────┘   └─────────────┘   └────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

4.2 Data Sources

Source	Type	Coverage	Cost Model	Tier
Have I Been Pwned (HIBP)	API	Email, password breaches	Free (rate limited) / Paid API	All tiers
SecurityTrails	API	DNS, domain exposures	~$100/month	Plus, Premium
Censys	API	Internet-wide scan data	~$200/month	Premium
Dark web forums	Scrapers/API	Phone numbers, SSN, emails	~$500/month (aggregator)	Premium
Shodan	API	IoT, exposed services	~$250/month	Premium
Internal honeypots	Build	Phone number exposure	Infrastructure cost	All tiers

4.3 Core Components

Watch List Manager

• Stores user-submitted identifiers: emails, phone numbers, SSN (hashed), home addresses
• Deduplication: SHA-256 hash of normalized identifiers
• Tier-based limits: Basic (2 identifiers), Plus (10), Premium (unlimited)

Data Ingestion Pipeline

• Scheduled jobs (BullMQ cron): daily for Basic, hourly for Plus, real-time for Premium
• Multi-source aggregation with fallback
• Normalization layer: standardize formats across sources
• Deduplication: content hash of exposure records

Matching Engine

• Exact match: email, phone number, SSN (last 4 digits for Basic, full hash for Premium)
• Fuzzy match: name + address combinations for home title monitoring
• Severity scoring: based on data type, recency, source reliability

Alert Pipeline

• Dedup window: 24 hours per exposure type
• Severity levels: INFO (email in old breach), WARNING (phone number recent), CRITICAL (SSN + financial)
• Notification channels: email, push notification, SMS (Premium)
• Alert fatigue protection: digest mode for INFO, immediate for WARNING+

Exposure Database

• PostgreSQL table with GIN index on identifier arrays
• Time-series: track exposure history per user
• Retention: 5 years for Premium, 1 year for Plus, 30 days for Basic

4.4 Build vs Buy

Component	Decision	Rationale
Data aggregation	Buy (APIs)	Faster time-to-market, battle-tested sources
Matching engine	Build	Core logic, tier-specific rules, dedup
Alert system	Build	Integrates with shared notification platform
Honeypot network	Build	Differentiator, early detection for phone numbers
Full alternative	Identity1 or WizIQ API	Evaluate if build cost exceeds ~$2K/month

4.5 API Surface

POST   /api/v1/darkwatch/watchlist        — Add identifier to watch
GET    /api/v1/darkwatch/watchlist        — List watched identifiers
DELETE /api/v1/darkwatch/watchlist/:id    — Remove identifier
POST   /api/v1/darkwatch/scan             — Trigger manual scan
GET    /api/v1/darkwatch/exposures        — List user's exposures
GET    /api/v1/darkwatch/exposures/:id    — Exposure detail
GET    /api/v1/darkwatch/reports          — List scan reports
POST   /api/v1/darkwatch/reports/generate — Generate PDF report
GET    /api/v1/darkwatch/alerts           — List user's alerts
PATCH  /api/v1/darkwatch/alerts/:id/read  — Mark alert as read

---

5. SpamShield Service — Spam Call/Text Blocking

5.1 Architecture

┌──────────────────────────────────────────────────────────┐
│                   SpamShield Service                      │
│                                                           │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────────┐ │
│  │  Ingestion  │──│  Feature    │──│  Classifier      │ │
│  │  (Call/Text │  │  Extractor  │  │  (ML + Rules)    │ │
│  │   Events)   │  │  (Metadata, │  │  (Random Forest  │ │
│  └─────────────┘  │   Content)  │  │   + Rule Engine) │ │
│                   └─────────────┘  └────────┬─────────┘ │
│                                              │            │
│  ┌─────────────┐  ┌─────────────┐  ┌────────▼─────────┐ │
│  │  Action     │◀─│  Decision   │◀─│  Score           │ │
│  │  Executor   │  │  Engine     │  │  Aggregator      │ │
│  │  (Block,   │  │  (Threshold,│  │  (Multi-signal   │ │
│  │   Flag,    │  │   Confidence)│  │   combination)   │ │
│  │   Notify)  │  │             │  │                  │ │
│  └─────────────┘  └─────────────┘  └──────────────────┘ │
└──────────────────────────────────────────────────────────┘

5.2 Spam Detection Layers

Layer 1: Number Reputation (Rule-Based)

• Carrier CNAM lookup: identify business vs. personal numbers
• Known spam databases: integration with Hiya, Truecaller API
• Number age: new numbers (<30 days) flagged as suspicious
• Call pattern analysis: high volume from single number = spam
• Geographic anomaly: unexpected country/region for user

Layer 2: Content Classification (ML)

• SMS text classification: fine-tuned BERT model for spam vs. ham
• Feature extraction: URL presence, emoji density, urgency keywords, sender ID
• Confidence threshold: 0.85 for auto-block, 0.6-0.85 for flag
• Continuous learning: user feedback (false positive/negative) retrains model

Layer 3: Behavioral Analysis

• Call frequency patterns: robo-dial detection (>5 calls/minute from same pool)
• Time-of-day anomaly: unusual hours for user's timezone
• Session analysis: short duration calls (<10s) = likely robo-call
• VOIP detection: identify carrier type (VOIP = higher spam probability)

Layer 4: Community Intelligence

• Aggregated user reports: crowd-sourced spam number database
• Weighted scoring: more reports = higher spam score
• Decay function: older reports lose weight over time

5.3 Real-Time Blocking

Call Blocking

• Integration: SIP trunking or carrier API (Twilio, Plivo)
• Flow: incoming call → API lookup → decision (<200ms) → block/flag/ring
• Block action: send to voicemail with "AI-detected spam" greeting
• Flag action: show "Likely Spam" on caller ID before answer
• False positive recovery: one-tap "keep call" overrides for 30 days

Text Blocking

• Integration: SMPP gateway or carrier API
• Flow: incoming SMS → content analysis → decision (<500ms) → block/flag
• Block action: move to spam folder with preview
• Flag action: show banner "Possible Spam" with swipe to keep

5.4 Build vs Buy

Component	Decision	Rationale
Number reputation	Buy (Hiya + Truecaller)	Established databases, hard to build from scratch
Content classifier	Build (fine-tune BERT)	Domain-specific, continuous improvement
Behavioral analysis	Build	Proprietary data advantage
Call/text routing	Buy (Twilio/Plivo)	Carrier relationships, global coverage
Community intelligence	Build	Network effect, differentiator
Full alternative	Syrrex or TollBridge	Evaluate if integration complexity is too high

5.5 API Surface

POST   /api/v1/spamshield/calls/analyze      — Analyze incoming call
POST   /api/v1/spamshield/sms/analyze        — Analyze incoming SMS
GET    /api/v1/spamshield/history            — User's blocked/flagged history
POST   /api/v1/spamshield/feedback           — Submit false positive/negative
POST   /api/v1/spamshield/whitelist          — Add number to whitelist
POST   /api/v1/spamshield/blacklist          — Add number to blacklist
GET    /api/v1/spamshield/stats              — User's spam statistics
WS     /api/v1/spamshield/realtime           — Real-time event stream

---

6. Shared Platform Services

6.1 Auth & User Management

• NextAuth.js with email/password + OAuth (Google, Apple)
• RBAC: user, family_admin, family_member, support
• Family group management: up to unlimited members (Premium), 3 (Plus)

6.2 Billing

• Stripe subscription management
• Tier-based feature gating via middleware
• Usage tracking for free tier limits

6.3 Notification System

• Multi-channel: email (Resend), push (FCM/APNs), SMS (Twilio)
• Template system with localization support
• Alert dedup and rate limiting per user

6.4 Analytics

• PostHog for product analytics
• Custom dashboards: detection rates, false positive rates, conversion funnels
• Model performance monitoring: precision, recall, drift detection

---

7. Development Timeline

Phase 1: Foundation (Weeks 1-4)

• Project scaffolding: monorepo (Turborepo), CI/CD pipeline
• Auth service: user registration, login, family groups
• Billing integration: Stripe subscriptions, tier gating
• API gateway: routing, rate limiting, authentication middleware
• Database schema: Prisma models, migrations
• Notification service: email, push infrastructure

Phase 2: DarkWatch MVP (Weeks 5-8)

• Watch list manager with CRUD API
• HIBP API integration (first data source)
• Matching engine: exact match for email/phone
• Alert pipeline: email notifications for exposures
• Dashboard: exposure list, watch list management
• Manual scan trigger with job queue

Phase 3: SpamShield MVP (Weeks 9-12)

• Number reputation integration (Hiya API)
• SMS content classifier: train initial BERT model
• Call analysis API with rule engine
• Blocking/flagging action executor
• User feedback loop: false positive/negative collection
• Dashboard: spam history, whitelist/blacklist

Phase 4: VoicePrint MVP (Weeks 13-16)

• Audio preprocessing pipeline
• ECAPA-TDNN model training on ASVspoof data
• Voice enrollment API with FAISS index
• Batch audio analysis endpoint
• Dashboard: enrollment management, analysis results
• Synthetic voice detection accuracy benchmarking

Phase 5: Real-Time Features (Weeks 17-20)

• Real-time call analysis via WebRTC
• Streaming WebSocket alerts
• DarkWatch automated scheduling (tier-based frequency)
• SpamShield real-time call/text interception
• Cross-service alert correlation

Phase 6: Beta & Launch (Weeks 21-24)

• Beta testing with 100 users
• Performance optimization: P99 latency targets
• Mobile app (React Native or Tauri)
• Documentation, onboarding flows
• Production deployment, monitoring, alerting
• Launch

---

8. Infrastructure & Deployment

8.1 Environment Strategy

• Dev: Docker Compose, local PostgreSQL/Redis
• Staging: AWS ECS Fargate, RDS PostgreSQL, ElastiCache Redis
• Prod: AWS ECS Fargate (or EKS if scaling demands), multi-AZ, auto-scaling

8.2 Key Services

Service	Provider	Notes
Compute	AWS ECS/Fargate	Container-based, auto-scale
Database	AWS RDS PostgreSQL	Multi-AZ, automated backups
Cache	AWS ElastiCache Redis	Cluster mode for BullMQ
Storage	AWS S3	Audio files, reports
CDN	CloudFront	Static assets, dashboard
Email	Resend	Transactional emails
SMS	Twilio	Alert notifications, call routing
ML Training	AWS SageMaker	Model training jobs
ML Inference	AWS Lambda / ECS	Real-time inference
Monitoring	Datadog + Sentry	APM, error tracking

8.3 Security

• All data encrypted at rest (AES-256) and in transit (TLS 1.3)
• PII field-level encryption for SSN, phone numbers
• SOC 2 Type II readiness from launch
• OWASP Top 10 compliance
• Regular penetration testing (quarterly)
• GDPR + CCPA compliance for data retention

---

9. Key Technical Risks & Mitigations

Risk	Impact	Mitigation
Voice model false positives	User trust erosion	Start with "flag" not "block", user feedback loop
Dark web data source reliability	Stale alerts	Multi-source redundancy, health monitoring
Real-time latency SLA	Missed spam calls	Edge deployment, <200ms target with fallback
Scalability of voice analysis	High compute cost	Async batch for non-real-time, GPU spot instances
API dependency (Hiya, Twilio)	Service outage	Circuit breakers, fallback providers
Model drift over time	Accuracy degradation	Monthly retraining pipeline, performance monitoring

---

10. Team & Resource Estimates

Role	Headcount	Phase 1	Phase 2-3	Phase 4-6
Backend Engineer	2	✓	✓	✓
ML Engineer	1	—	—	✓
Frontend Engineer	1	✓	✓	✓
DevOps/SRE	1	✓	✓	✓
QA Engineer	1	—	✓	✓

Estimated monthly burn (engineering only): ~$45K for 6-person team

---

11. Success Metrics (Technical)

Metric	Target	Measurement
Voice detection accuracy (F1)	>0.90	ASVspoof benchmark + internal test set
Spam classification precision	>0.95	User feedback, labeled test set
Dark web scan coverage	>3 major sources	Data source inventory
API P99 latency	<500ms	Datadog APM
False positive rate (calls)	<2%	User feedback tracking
System uptime	>99.9%	Uptime monitoring
Dark web alert freshness	<24h	Time from exposure to alert