# ramya-parsania/truthtell architecture

> Architecture diagram of the GitHub repository ramya-parsania/truthtell, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ramya-parsania/truthtell
- Repository: https://github.com/ramya-parsania/truthtell

## Overview

##### Project Type and Purpose
- Nexus of Truth is a full-stack, real-time misinformation detection system for live broadcasts.
- It comprises a React/TypeScript-based dashboard + Chrome extension (nexus-frontend & nexus-extension) and a Python microservice backend (nexus-backend) that ingests media streams, runs NLP and deepfake detection, and delivers fact-check results.

##### File Structure Analysis
- Top-Level Directories
- nexus-frontend: React/TS dashboard + static assets + Vite config + Tailwind CSS
- nexus-backend: Python services subdivided into Deep_fake_detection, deepfake2, fc (fact-checking), knowledge_graph, routes, db initializer + NLTK data
- nexus-extension: Browser extension with manifest, popup UI, Python backend integration
- Architectural Patterns
- Backend is organized as lightweight microservices (each folder is a self-contained module)
- Routes directory defines REST endpoints (likely using Flask or FastAPI)
- Event-driven stream processing implied by Kafka (README)
- Data persistence via a relational/NoSQL database (init_db.py) and knowledge graph (Neo4j mentioned in README)
- Deployment / Infrastructure
- Docker containerization (README)
- Apache Kafka for real-time messaging
- External fact-check APIs and social media streaming sources

##### Key Components
A. Frontend Layer
- Web Dashboard (React + Tailwind)
- Browser Extension (popup.html, popup.js)
B. API Gateway / Ingress
- REST/WebSocket endpoints (routes/*.py)
- Authentication service (auth.py)
C. Message Broker
- Apache Kafka topics for “raw_media_stream,” “fact_check_requests,” “detection_requests,” “results”
D. Microservices
1. Deepfake Detection
– Deep_fake_detection module (detector.py, videoprocess.py, basemodels.py)
– deepfake2 module (deepfake2.py, .h5 model)
2. Fact-Checking Engine (fc folder)
– news_summ, fact_checker, newsfetcher, serper_search integration
3. Knowledge Graph Generator
– knowledge_graph_generator.py, final.py
4. Social Media Analysis (not in code folder but noted in README)
5. Impact Analysis & Source Correction (framework described in README)
6. Continuous Learning Feedback Loop (user reports → model retraining)
E. Data Stores
- Primary DB (init_db.py)
- Knowledge Graph DB (Neo4j)
- NLTK data asset store
- Temporary JSON store (fetched_pages.json)
F. External Services
- FactCheck APIs (Google FactCheck, Loki, WordLift)
- Social media streams (Twitter, Facebook, TikTok)
- Cloud storage (AWS S3/GCS if deployed)

##### Component Relationships & Data Flow
- UI → API Gateway: HTTP / WebSocket calls (user inputs, live stream URLs)
- Gateway → Kafka: Publish raw data to media or NLP topics
- Microservices consume from Kafka, process (e.g., run BERT on text, TensorFlow/PyTorch on video frames)
- Microservices emit results back to Kafka “results” topic
- Result aggregator service reads from “results,” persists to DB & Knowledge Graph
- API Gateway pushes updates to UI (via WebSocket) and triggers browser extension notifications
- User feedback flows back as events for Continuous Learning

##### Architectural Patterns & Design Principles
- Microservices & Event-Driven Architecture via Apache Kafka
- Separation of Concerns: detection, NLP, graph generation, and API layers are independent
- Containerization: each service packaged in Docker for scalability
- Polyglot Persistence: relational DB + graph DB
- Asynchronous Processing for real-time throughput

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Frontend Layer"
    Dashboard["Web Dashboard"]:::frontend
    Extension["Browser Extension"]:::frontend
  end

  Dashboard -->|HTTP/WebSocket| APIGateway["API Gateway"]:::backend
  Extension -->|HTTP/WebSocket| APIGateway

  subgraph "Message Broker" 
    RawMedia["/ raw_media_stream"]:::broker
    FactReq["/ fact_check_requests"]:::broker
    DetectReq["/ detection_requests"]:::broker
    ResultsTopic["/ results"]:::broker
  end

  APIGateway -->|publish| RawMedia
  APIGateway -->|publish| FactReq
  APIGateway -->|publish| DetectReq

  subgraph "Microservices Layer"
    subgraph "Deepfake Services"
      DFCore["Deep_fake_detection"]:::backend
      DF2["deepfake2"]:::backend
    end
    FactCheck["Fact-Checking Engine"]:::backend
    KGGen["Knowledge Graph Generator"]:::backend
  end

  RawMedia -->|consume| DFCore
  DetectReq -->|consume| DFCore
  DetectReq -->|consume| DF2
  FactReq -->|consume| FactCheck

  DFCore -->|publish| ResultsTopic
  DF2 -->|publish| ResultsTopic
  FactCheck -->|publish| ResultsTopic
  KGGen -->|publish| ResultsTopic

  subgraph "Result Aggregation"
    ResultAgg["Result Aggregator"]:::backend
  end

  ResultsTopic -->|consume| ResultAgg
  ResultAgg -->|write| DB["Primary DB"]:::datastore
  ResultAgg -->|write| KGDB["Knowledge Graph DB"]:::datastore
  ResultAgg -->|updates| APIGateway

  subgraph "Data Stores"
    DB
    KGDB
    NLTK["NLTK Data Store"]:::datastore
    Fetched["Fetched Pages Store"]:::datastore
  end

  KGGen -->|read| NLTK
  FactCheck -->|read/write| Fetched

  subgraph "External Services"
    FactAPIs["FactCheck APIs"]:::external
    SocialStreams["Social Media Streams"]:::external
  end

  SocialStreams -->|stream| APIGateway
  FactCheck -->|call| FactAPIs

  %% Click Events
  click Dashboard "https://github.com/ramya-parsania/truthtell/tree/main/nexus-frontend/src"
  click Extension "https://github.com/ramya-parsania/truthtell/tree/main/nexus-extension"
  click APIGateway "https://github.com/ramya-parsania/truthtell/tree/main/nexus-backend/routes"
  click DFCore "https://github.com/ramya-parsania/truthtell/tree/main/nexus-backend/Deep_fake_detection"
  click DF2 "https://github.com/ramya-parsania/truthtell/tree/main/nexus-backend/deepfake2"
  click FactCheck "https://github.com/ramya-parsania/truthtell/tree/main/nexus-backend/fc"
  click KGGen "https://github.com/ramya-parsania/truthtell/tree/main/nexus-backend/knowledge_graph"
  click DB "https://github.com/ramya-parsania/truthtell/blob/main/nexus-backend/db/init_db.py"
  click NLTK "https://github.com/ramya-parsania/truthtell/tree/main/nexus-backend/nltk_data"
  click Fetched "https://github.com/ramya-parsania/truthtell/blob/main/nexus-backend/fetched_pages.json"

  %% Styles
  classDef frontend fill:#AEDFF7,stroke:#2C7FB8,stroke-width:2px
  classDef backend fill:#D5E8D4,stroke:#82B366,stroke-width:2px
  classDef broker fill:#FFE6CC,stroke:#D99000,stroke-width:2px
  classDef datastore fill:#E1E1E1,stroke:#888888,stroke-width:2px
  classDef external fill:#E2D5F6,stroke:#9673A6,stroke-width:2px
```
