Skip to main content

Architecture

This page details the system topology, component interactions, and technical rationale for the JERC Sentry beta-release state.

System Topology​

The following diagram illustrates the high-level architecture of JERC Sentry, including major components, data flows, and external service dependencies.

JERC Sentry Beta Architecture

Component Breakdown​

1. Mobile Interface (Protector App)​

  • Framework: Flutter (Android/iOS)
  • Role: Provides the primary interface for protectors to register protectees, monitor calls, receive alerts, and take intervention actions (Join/Terminate).
  • Integrations:
    • Firebase Auth: Handles secure user authentication and session management.
    • Firebase Cloud Messaging (FCM): Receives high-priority push notifications when scams are detected.

2. Backend Services​

  • Framework: FastAPI (Python)
  • Role: Acts as the central orchestrator for telephony webhooks, AI inference pipelines, and state management.
  • Database: PostgreSQL (via SQLModel) for persistent storage of user profiles, call logs, and threat metadata.
  • Hosting: Containerized via Docker and deployed on Railway for production-grade reliability.

3. Telephony Infrastructure (Telnyx)​

  • Role: Manages the SIP backbone and audio forking.
  • Mechanism: When a call is intercepted, Telnyx forks the media stream via WebSockets (WSS) to the JERC backend for real-time analysis while maintaining the bridge between the caller and protectee.

4. AI Inference Pipeline​

  • Speech-to-Text (Deepgram): Utilizes the Nova-2 Phonecall model via streaming WebSockets for ultra-low latency transcription of telephony audio.
  • LLM Analysis (Groq): Leverages Llama 3.1 8B via Groq's LPUs to analyze transcription context for social engineering patterns in milliseconds.

5. Deployment Pipeline​

  • GitHub Actions: Orchestrates the CI/CD workflow. Deployments are automatically triggered whenever a new version tag (v*.*.*) is pushed to the repository, ensuring a hands-off release process.
  • Terraform (IaC): Programmatically manages Railway infrastructure, including projects, environments, and services. The pipeline utilizes HCP Terraform as a remote state store to maintain consistency across the team.
  • Railway CLI: Integrated into the deployment workflow to package the FastAPI backend into a Docker container and deploy it to the provisioned services once infrastructure is verified by Terraform.

Data Flows​

  1. Interception: A scammer calls the protectee. The call is forwarded to a Telnyx virtual number via CCF.
  2. Analysis: Telnyx sends call events to the Backend via HTTPS webhooks and forks audio via WSS.
  3. Transcription: The Backend streams audio to Deepgram; text returns in real-time.
  4. Inference: Transcribed text is sent to Groq. If a threat is detected, the Backend triggers a "whisper" warning in the Protectee's call leg.
  5. Alerting: Simultaneously, the Backend dispatches an FCM notification to the Protector’s device.
  6. Intervention: The Protector sends a command (Join/Terminate) via the Mobile App to the Backend, which instructs Telnyx to modify the call state.

Architectural Rationale (Alpha to Beta)​

Since the alpha release, the JERC Sentry architecture has evolved from a local-first prototype to a production-ready system.

Key Changes and Rationale​

  • Production Hosting (Railway): We transitioned from local development environments to Railway for our API and Database. This ensures high availability and removes the dependency on local developer hardware for beta testing.
  • Infrastructure as Code (Terraform) & CI/CD: To ensure environment parity and automated delivery, we implemented Terraform managed via GitHub Actions. All Railway cloud resources are now managed programmatically, with backend deployments triggered automatically by version tags to ensure a stable and reproducible release process.
  • Optimized AI Stack: In alpha, we explored various STT/LLM combinations. For beta, we committed to Deepgram Nova-2 and Groq (Llama 3.1 8B). This specific pairing was chosen to minimize "Time-to-Alert"—crucial for intervening in live phone scams before the victim provides sensitive information.