Database Schema & Models

Relevant source files

The following files were used as context for generating this wiki page:

• truelens-backend/app/models/models.py
• truelens-app/src/lib/types.ts
• truelens-app/src/lib/store.ts
• truelens-backend/app/tasks/ml_pipeline.py
• truelens-app/src/lib/analysis.ts

The Database Schema and Models in TrueLens define the structural foundation for content authenticity analysis, user management, and document verification. The system utilizes an Object-Relational Mapping (ORM) approach via SQLAlchemy in the backend and TypeScript interfaces in the frontend to ensure data consistency across the stack.

The schema is designed to support a multi-signal analysis pipeline where a single content scan or document upload generates multiple diagnostic "signals." These signals are aggregated to produce a final trust score and verdict, providing explainable AI results to the end user.

Sources: truelens-backend/app/models/models.py:1-12, truelens-app/src/lib/types.ts:1-50

Core Data Entities

The TrueLens data architecture revolves around four primary entities: User, Scan, Signal, and Document. These entities capture the lifecycle of an analysis request from submission to result generation.

Entity Relationship Diagram

The following ER diagram illustrates the relationships between the core database tables, highlighting the one-to-many relationships from Users to Scans/Documents and from Scans to individual Signals.

Detailed Model Definitions

User Model

The User model manages account information and subscription tiers. It serves as the parent entity for all user-generated content and analysis history.

Field	Type	Description
id	String (UUID)	Unique identifier for the user.
email	String	Unique email address, indexed for performance.
name	String	Display name of the user.
plan	String	Subscription tier (default: "free").
created_at	DateTime	Timestamp of account creation.

Sources: truelens-backend/app/models/models.py:23-33

Scan Model

The Scan model represents a content analysis request. It supports different input types (URLs or raw text) and tracks the progress of the asynchronous ML pipeline.

Field	Type	Constraints	Description
id	String	PK	Unique identifier generated via UUID.
content_type	Enum	Not Null	Values: url, text, file.
trust_score	Integer	Nullable	Final calculated score (0-100).
verdict	Enum	Nullable	Categorization: Authentic, Suspicious, AI-Generated.
status	Enum	Default: pending	Pipeline status: pending, processing, completed, failed.
scan_duration	Float	Nullable	Total time taken for analysis in seconds.

Sources: truelens-backend/app/models/models.py:36-54, truelens-backend/app/tasks/ml_pipeline.py:46-55

Signal Model

The Signal model stores granular results from specific analysis engines (e.g., text stylometry, domain reputation, or image forensics).

class Signal(Base):
    __tablename__ = "signals"

    id = Column(String, primary_key=True, default=generate_uuid)
    scan_id = Column(String, ForeignKey("scans.id"), nullable=False)
    type = Column(String, nullable=False) # e.g. text, image, metadata, review
    score = Column(Integer, nullable=False)
    label = Column(String, nullable=False)
    confidence = Column(Float, nullable=False)
    evidence = Column(JSON, nullable=True) # stores JSON breakdown
    highlights = Column(JSON, nullable=True) # stores array of strings

Sources: truelens-backend/app/models/models.py:57-69

Document Verification & Cryptography

The Document model includes specialized fields for tamper detection and cryptographic proof of authenticity. This system uses SHA-256 hashing to identify unique files and stores digital signatures issued by the TrueLens platform.

Document Model Fields

• hash: A unique SHA-256 string used to verify document integrity and prevent duplicate processing.
• findings: A JSON field containing an array of specific issues found during analysis (e.g., "Font Inconsistency").
• signature: A cryptographic string verifying that the document was analyzed and approved by TrueLens.
• public_key: Stored to allow third-party verification of the document's signature.

Sources: truelens-backend/app/models/models.py:72-92, truelens-app/src/lib/types.ts:33-47

Data Flow & State Transitions

The lifecycle of a scan involves state transitions managed by the ml_pipeline.py task. The following sequence diagram details how data moves from a pending request to a completed analysis with associated signals.

Summary of Constants and Enums

The models utilize specific enums to standardize the classification of content and verdicts across the application.

Enum Type	Values	Source
ContentTypeEnum	url, text, file	models.py:14-17
ScanStatusEnum	pending, processing, completed, failed	models.py:19-23
VerdictEnum	Authentic, Suspicious, AI-Generated	models.py:25-28
Signal Weights	text: 0.40, metadata: 0.25, image: 0.20, review: 0.10	ml_pipeline.py:31-38

The backend models are mirrored in the frontend via TypeScript interfaces in truelens-app/src/lib/types.ts, allowing for a type-safe flow of data from the PostgreSQL database through the FastAPI backend to the Next.js user interface.

Sources: truelens-backend/app/models/models.py:14-28, truelens-backend/app/tasks/ml_pipeline.py:31-38, truelens-app/src/lib/types.ts:18-31