Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
TrueLens is an AI-powered content verification platform designed to detect AI-generated text, fake reviews, and fraudulent documents. The system employs a multi-signal ensemble architecture that combines machine learning models (transformers), heuristic stylometry analysis, and cryptographic verification to generate comprehensive "Trust Scores" for digital content.
The platform is split into a Next.js frontend application (truelens-app) and a FastAPI-based backend (truelens-backend). The frontend handles user interactions, scanning interfaces, and cryptographic verification of signed documents, while the backend provides specialized analysis services for text, domains, and documents.
Sources: truelens-app/src/app/page.tsx, truelens-app/src/lib/analysis.ts:1-10
System Components
The architecture consists of several specialized modules categorized into Frontend and Backend services.
Frontend Architecture
The frontend is built with Next.js and includes an internal analysis engine for quick client-side checks and an API integration layer for complex backend processing.
| Component | Description |
|---|---|
| Analysis Engine | Client-side logic for stylometry and domain analysis using heuristic weights. |
| Data Store | An in-memory singleton for managing scans and document states in the prototype. |
| Developer Portal | Provides API documentation and access for third-party integrations. |
| Verification Module | Handles QR code scanning and SHA-256 hash verification for document authenticity. |
Sources: truelens-app/src/lib/analysis.ts:101-150, truelens-app/src/lib/store.ts:10-30, truelens-app/src/app/developers/page.tsx:20-50, truelens-app/src/app/verify/page.tsx:30-60
Backend Services
The backend contains the "heavy-lifting" analysis services written in Python, utilizing specialized ML libraries.
| Service | Focus Area |
|---|---|
| Review Analysis | Detects fake reviews using RoBERTa transformers and behavioral heuristics. |
| Document Analysis | Analyzes PDF/Image files for metadata integrity, font consistency, and arithmetic logic. |
| Fact-Check API | Integrates with external databases (e.g., Google Fact Check) and AI evaluators. |
Sources: truelens-backend/app/services/review_analysis.py:10-25, truelens-backend/app/services/document_analysis.py:20-60, truelens-app/src/app/fact-check/page.tsx:40-70
Multi-Signal Analysis Pipeline
TrueLens uses an ensemble scoring method where multiple "Signals" are weighted to produce a final verdict. The system supports signals for text, domain, image, review, and provenance.
Ensemble Weighting
The final Trust Score is calculated using a weighted sum of individual signal scores adjusted by their confidence levels.
The diagram shows the logical flow of data through the various analysis signals into the ensemble scoring engine.
| Signal Type | Weight | Primary Indicators |
|---|---|---|
| Text | 0.40 | Vocabulary richness, burstiness, sentence variance, formal word choice. |
| Domain | 0.25 | TLD reputation, domain age, HTTPS status, subdomain depth. |
| Image | 0.20 | Pixel manipulation, metadata integrity, GAN fingerprinting. |
| Review | 0.10 | Sentiment extremity, repetition, cliche marketing phrases. |
| Provenance | 0.05 | Historical cached matches, image matches across the web. |
Sources: truelens-app/src/lib/analysis.ts:251-260, truelens-app/src/lib/types.ts:12-21, truelens-backend/app/services/review_analysis.py:45-80
Document Verification Architecture
Document analysis combines structural verification with cryptographic signing. When a document is verified as "Authentic," it is cryptographically signed with a SHA-256 hash and a digital signature.
Analysis Logic
- Format Validation: Verification of PDF/Image/DOCX structure.
- Metadata Check: Analysis of Producer/Creator software for known editing tools (e.g., Inkscape, LibreOffice).
- Heuristic Analysis: Checks for font consistency (detecting copy-paste forgery) and Verhoeff checksums on documents like Aadhaar cards.
- Arithmetic Validation: For invoices, line items are extracted via OCR and compared against the total sum.
This sequence illustrates the document processing lifecycle from upload to cryptographic signing.
Sources: truelens-backend/app/services/document_analysis.py:102-150, truelens-backend/app/services/document_analysis.py:321-340, truelens-app/src/lib/analysis.ts:315-350
Data Structures and Models
The system relies on several core interfaces defined in the TypeScript library to maintain consistency across the frontend and API responses.
Core Scan Model
export interface Scan {
id: string;
url?: string;
contentType: "url" | "text" | "file";
trustScore: number;
verdict: "Authentic" | "Suspicious" | "AI-Generated";
signals: Signal[];
status: "pending" | "processing" | "completed" | "failed";
scanDuration?: number;
}
Sources: truelens-app/src/lib/types.ts:23-37
Signal Model
Each Signal includes specific evidence and highlights found during analysis.
export interface Signal {
id: string;
type: "text" | "image" | "metadata" | "review" | "domain" | "provenance";
score: number;
label: string;
confidence: number;
evidence: Record<string, unknown>;
highlights?: string[];
}
Sources: truelens-app/src/lib/types.ts:12-21
Conclusion
TrueLens' architecture is built on a modular "Signal-based" approach, allowing it to evaluate content through multiple lenses simultaneously. By separating heuristic stylometry analysis (frontend/backend) from cryptographic verification and deep learning models (backend), the system provides a scalable framework for maintaining digital trust in an environment increasingly dominated by AI-generated and manipulated content.