# rigen-manandhar/truthlens-fake-news-detection architecture

> Architecture diagram of the GitHub repository rigen-manandhar/truthlens-fake-news-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rigen-manandhar/truthlens-fake-news-detection
- Repository: https://github.com/rigen-manandhar/truthlens-fake-news-detection

## Overview

#### Purpose and Clients
TruthLens is a misinformation-risk assessment system, not a truth-verification engine. It combines language-model signals, source context, article extraction, claim hints, optional news coverage, and uncertainty handling. Primary clients are a Next.js web application and Chrome extension; both reach the same prediction boundary. Key entry points: `Frontend/app/page.tsx`, `Frontend/app/fake-detection/page.tsx`, `extension/popup-main.js`, `Backend/app/main.py`.

#### Web Application and API Boundary
The Next.js App Router application provides detection, deepfake detection, news, account, settings, and admin experiences. Browser-facing API routes act as a server-side boundary: prediction routes proxy/request backend analysis, while identity and product data remain handled in Next.js. Core paths: `Frontend/app/api/predict/route.ts`, `Frontend/app/api/deepfake/predict/route.ts`, `Frontend/app/components/fakeDetection/useFakeDetectionController.ts`.

#### Prediction Orchestration
FastAPI’s `/predict` flow is centralized in the prediction service. It accepts submitted text and/or URL, coordinates eligibility, extraction, source/evidence/model stages, and constructs a compatible structured response. This is the principal control-flow boundary between HTTP input and risk evaluation: `Backend/app/main.py`, `Backend/app/services/predict_service.py`, `Backend/app/services/predict_response_builders.py`.

#### Content Acquisition and Source Context
URLs are first screened for eligibility, then article text is safely extracted where possible; users may instead provide manual text. Source credibility is derived from a transparent local seed database rather than a live authority. Extraction provenance and source quality are inputs to final risk interpretation. Paths: `Backend/app/url_eligibility.py`, `Backend/app/article_extractor.py`, `Backend/app/data/source_credibility.json`.

#### Hybrid Language and Evidence Signals
Two local RoBERTa+LoRA artifacts contribute separate headline/claim and article-language signals. The hybrid layer runs and normalizes model outputs. Independently, the evidence layer identifies check-worthy claim hints and can query trusted-source coverage when `NEWS_API_KEY` is configured; missing API credentials explicitly leave coverage unchecked. Paths: `Backend/app/hybrid_model.py`, `Backend/app/hybrid/model_runner.py`, `Backend/app/evidence.py`; model assets: `Backend/model/model_a/adapter_model.safetensors`, `Backend/model/model_b/adapter_model.safetensors`.

#### Scoring, Explanation, and Uncertainty
Scoring fuses imperfect signals into `LIKELY REAL`, `SUSPICIOUS`, or `UNCERTAIN`, preserving the distinction between observed risk and factual truth. Confidence, model disagreement, conflicting evidence, extraction quality, limitations, and explanations are first-class response metadata rather than hidden implementation detail. Paths: `Backend/app/scoring.py`, `Backend/app/explanations.py`, `Backend/app/schemas.py`.

#### Deepfake Analysis
A distinct media-analysis pipeline is exposed separately from textual misinformation assessment. It handles media input, face detection, model loading/inference, and response schemas; the underlying Xception classifier code and training configuration are retained under the deepfake package. Paths: `Backend/app/deepfake_detection/service.py`, `Backend/app/deepfake_detection/inference.py`, `Backend/deepfake/src/models/xception_classifier.py`.

#### Identity, Persistence, and Operations
Next.js owns authentication, user/account lifecycle, privacy exports/deletions, sessions, feedback, and administration. It uses NextAuth-style auth components and a MongoDB client/server data layer, with email, audit, rate-limiting, and privacy services at the server boundary. Paths: `Frontend/lib/auth.ts`, `Frontend/lib/mongodb-client.ts`, `Frontend/lib/server/privacy.ts`, `Frontend/app/api/auth/[...nextauth]/route.ts`.

Main entry points: [`Backend/app/services/predict_service.py`](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/services/predict_service.py) (Prediction service), [`Backend/app/main.py`](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/main.py) (FastAPI API), [`Frontend/app/page.tsx`](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/page.tsx) (Next.js experiences), [`Frontend/app/components/fakeDetection/useFakeDetectionController.ts`](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/components/fakeDetection/useFakeDetectionController.ts) (Detection controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web & Extension"]
  node_web_ui["Next.js experiences<br/>Next.js App Router<br/>[page.tsx]"]
  node_detection_controller["Detection controller<br/>client controller"]
  node_extension["Chrome extension<br/>extension client<br/>[popup-main.js]"]
  node_predict_route["Prediction API route<br/>Next.js route<br/>[route.ts]"]
  node_deepfake_route["Deepfake API route<br/>Next.js route<br/>[route.ts]"]
end

subgraph group_text["Text Risk Analysis"]
  node_fastapi["FastAPI API<br/>HTTP entrypoint<br/>[main.py]"]
  node_predict_service["Prediction service<br/>orchestrator<br/>[predict_service.py]"]
  node_content_acquisition["URL eligibility &amp; extraction<br/>content acquisition<br/>[url_eligibility.py]"]
  node_source_data[("Source credibility seed<br/>local JSON data")]
  node_hybrid_signals["Hybrid language signals<br/>model normalization<br/>[hybrid_model.py]"]
  node_model_runner["RoBERTa + LoRA models<br/>local model artifacts"]
  node_evidence["Evidence &amp; coverage<br/>evidence service<br/>[evidence.py]"]
  node_scoring["Risk scoring<br/>decision fusion<br/>[scoring.py]"]
  node_response_builder["Response metadata<br/>response builder"]
end

subgraph group_deepfake["Deepfake Analysis"]
  node_deepfake_service["Deepfake service<br/>media orchestrator<br/>[service.py]"]
  node_deepfake_inference["Media inference<br/>face detection &amp; inference<br/>[inference.py]"]
  node_xception["Xception classifier<br/>media classifier"]
end

subgraph group_identity["Identity &amp; Data"]
  node_auth["Auth &amp; sessions<br/>NextAuth service<br/>[auth.ts]"]
  node_auth_route["Auth API route<br/>Next.js route<br/>[route.ts]"]
  node_privacy["Privacy lifecycle<br/>server service<br/>[privacy.ts]"]
  node_mongodb[("MongoDB data layer<br/>database client<br/>[mongodb-client.ts]")]
end

node_web_ui -->|"uses"| node_detection_controller
node_detection_controller -->|"submits text or URL"| node_predict_route
node_extension -->|"requests prediction"| node_fastapi
node_predict_route -->|"proxies analysis"| node_fastapi
node_deepfake_route -->|"submits media"| node_deepfake_service
node_fastapi -->|"/predict"| node_predict_service
node_predict_service -->|"acquires URL content"| node_content_acquisition
node_predict_service -->|"reads source context"| node_source_data
node_predict_service -->|"evaluates language"| node_hybrid_signals
node_hybrid_signals -->|"runs adapters"| node_model_runner
node_predict_service -->|"collects claim hints"| node_evidence
node_predict_service -->|"fuses signals"| node_scoring
node_scoring -->|"risk and uncertainty"| node_response_builder
node_response_builder -->|"structured response"| node_fastapi
node_deepfake_service -->|"runs analysis"| node_deepfake_inference
node_deepfake_inference -->|"classifies media"| node_xception
node_web_ui -->|"auth requests"| node_auth_route
node_auth_route -->|"handles identity"| node_auth
node_auth -->|"persists accounts"| node_mongodb
node_privacy -->|"exports or deletes data"| node_mongodb

click node_web_ui "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/page.tsx"
click node_detection_controller "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/components/fakeDetection/useFakeDetectionController.ts"
click node_extension "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/extension/popup-main.js"
click node_predict_route "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/api/predict/route.ts"
click node_deepfake_route "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/api/deepfake/predict/route.ts"
click node_fastapi "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/main.py"
click node_predict_service "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/services/predict_service.py"
click node_content_acquisition "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/url_eligibility.py"
click node_source_data "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/data/source_credibility.json"
click node_hybrid_signals "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/hybrid_model.py"
click node_model_runner "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/model/model_a/adapter_model.safetensors"
click node_evidence "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/evidence.py"
click node_scoring "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/scoring.py"
click node_response_builder "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/services/predict_response_builders.py"
click node_deepfake_service "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/deepfake_detection/service.py"
click node_deepfake_inference "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/deepfake_detection/inference.py"
click node_xception "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/deepfake/src/models/xception_classifier.py"
click node_auth "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/lib/auth.ts"
click node_auth_route "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/api/auth/%5B...nextauth%5D/route.ts"
click node_privacy "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/lib/server/privacy.ts"
click node_mongodb "https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/lib/mongodb-client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_ui,node_detection_controller,node_extension,node_predict_route,node_deepfake_route toneBlue
class node_fastapi,node_predict_service,node_content_acquisition,node_source_data,node_hybrid_signals,node_model_runner,node_evidence,node_scoring,node_response_builder toneAmber
class node_deepfake_service,node_deepfake_inference,node_xception toneMint
class node_auth,node_auth_route,node_privacy,node_mongodb toneRose
```

## Components

### Web & Extension

Client experiences and Next.js server boundary.

- [Next.js experiences](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/page.tsx): Next.js App Router · Detection, news, account, settings, and admin UI. · `Frontend/app/page.tsx`
- [Detection controller](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/components/fakeDetection/useFakeDetectionController.ts): client controller · `Frontend/app/components/fakeDetection/useFakeDetectionController.ts`
- [Chrome extension](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/extension/popup-main.js): extension client · `extension/popup-main.js`
- [Prediction API route](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/api/predict/route.ts): Next.js route · Server-side proxy boundary for text risk analysis. · `Frontend/app/api/predict/route.ts`
- [Deepfake API route](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/api/deepfake/predict/route.ts): Next.js route · `Frontend/app/api/deepfake/predict/route.ts`

### Text Risk Analysis

FastAPI orchestration and misinformation-risk signals.

- [FastAPI API](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/main.py): HTTP entrypoint · `Backend/app/main.py`
- [Prediction service](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/services/predict_service.py): orchestrator · Coordinates acquisition, signals, scoring, and response construction. · `Backend/app/services/predict_service.py`
- [URL eligibility & extraction](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/url_eligibility.py): content acquisition · Screens URLs and safely extracts article text. · `Backend/app/url_eligibility.py`
- [Source credibility seed](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/data/source_credibility.json): local JSON data · Transparent local source-quality database. · `Backend/app/data/source_credibility.json`
- [Hybrid language signals](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/hybrid_model.py): model normalization · Runs separate headline/claim and article-language signals. · `Backend/app/hybrid_model.py`
- [RoBERTa + LoRA models](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/model/model_a/adapter_model.safetensors): local model artifacts · Two local adapters provide independent language signals. · `Backend/model/model_a/adapter_model.safetensors`
- [Evidence & coverage](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/evidence.py): evidence service · Finds claim hints and optionally checks trusted-source coverage. · `Backend/app/evidence.py`
- [Risk scoring](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/scoring.py): decision fusion · Produces likely real, suspicious, or uncertain risk assessments. · `Backend/app/scoring.py`
- [Response metadata](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/services/predict_response_builders.py): response builder · Preserves confidence, uncertainty, limitations, and explanations. · `Backend/app/services/predict_response_builders.py`

### Deepfake Analysis

Separate media-analysis pipeline.

- [Deepfake service](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/deepfake_detection/service.py): media orchestrator · `Backend/app/deepfake_detection/service.py`
- [Media inference](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/app/deepfake_detection/inference.py): face detection & inference · `Backend/app/deepfake_detection/inference.py`
- [Xception classifier](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Backend/deepfake/src/models/xception_classifier.py): media classifier · `Backend/deepfake/src/models/xception_classifier.py`

### Identity & Data

Next.js-owned account and product services.

- [Auth & sessions](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/lib/auth.ts): NextAuth service · `Frontend/lib/auth.ts`
- [Auth API route](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/app/api/auth/%5B...nextauth%5D/route.ts): Next.js route · `Frontend/app/api/auth/[...nextauth]/route.ts`
- [Privacy lifecycle](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/lib/server/privacy.ts): server service · Handles user privacy exports and deletions. · `Frontend/lib/server/privacy.ts`
- [MongoDB data layer](https://github.com/rigen-manandhar/truthlens-fake-news-detection/blob/main/Frontend/lib/mongodb-client.ts): database client · Stores product and account data. · `Frontend/lib/mongodb-client.ts`

## Connections

- Next.js experiences → Detection controller: uses
- Detection controller → Prediction API route: submits text or URL
- Chrome extension → FastAPI API: requests prediction
- Prediction API route → FastAPI API: proxies analysis
- Deepfake API route → Deepfake service: submits media
- FastAPI API → Prediction service: /predict
- Prediction service → URL eligibility & extraction: acquires URL content
- Prediction service → Source credibility seed: reads source context
- Prediction service → Hybrid language signals: evaluates language
- Hybrid language signals → RoBERTa + LoRA models: runs adapters
- Prediction service → Evidence & coverage: collects claim hints
- Prediction service → Risk scoring: fuses signals
- Risk scoring → Response metadata: risk and uncertainty
- Response metadata → FastAPI API: structured response
- Deepfake service → Media inference: runs analysis
- Media inference → Xception classifier: classifies media
- Next.js experiences → Auth API route: auth requests
- Auth API route → Auth & sessions: handles identity
- Auth & sessions → MongoDB data layer: persists accounts
- Privacy lifecycle → MongoDB data layer: exports or deletes data