Pydantic Data Schemas

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/app/developers/page.tsx
• truelens-backend/app/services/document_analysis.py
• truelens-app/src/lib/analysis.ts
• truelens-backend/app/services/review_analysis.py

Pydantic data schemas in TrueLens serve as the foundational contract for data exchange between the frontend Next.js application and the backend FastAPI services. These schemas define the structure for content analysis results, document verification findings, and user-related information, ensuring type safety and consistent validation across the platform.

Within the project, these structures bridge the gap between the persistent SQLAlchemy models in the database and the JSON payloads delivered via API endpoints. They encapsulate complex analysis signals, cryptographic signatures, and detailed evidence used to generate authenticity verdicts.

Data Model Architecture

The data architecture is centered around four primary entities: Users, Scans, Signals, and Documents. These entities interact to provide a complete audit trail of content verification.

Entity Relationships

The following diagram illustrates the relationships between the core data structures used in the system.

The system maintains a hierarchical relationship where a Scan acts as a container for multiple Signal objects, each representing a specific analysis vector like text or domain reputation.
Sources: truelens-backend/app/models/models.py:34-93, truelens-app/src/lib/types.ts:9-64

Core Analysis Schemas

Analysis schemas are designed to capture the output of various ML engines, including text stylometry, domain reputation, and fact-checking.

Scan and Signal Structures

A Scan object captures the high-level metadata and the final trust verdict, while Signal objects provide the granular evidence.

Field	Type	Description
id	String / UUID	Unique identifier for the scan or signal.
trustScore	Integer (0-100)	Aggregated score representing the authenticity of the content.
verdict	Enum	Classification: Authentic, Suspicious, or AI-Generated.
type	String	The analysis vector: text, image, metadata, review, domain, or provenance.
confidence	Float (0-1.0)	The ML model's certainty in the specific signal result.
evidence	JSON / Record	Key-value pairs of raw data (e.g., avg sentence length).

Sources: truelens-app/src/lib/types.ts:16-37, truelens-backend/app/models/models.py:46-77

Text Analysis Features

The text analysis engine utilizes a specific internal schema to represent stylometric features used to detect AI generation.

interface TextFeatures {
  avgSentenceLength: number;
  sentenceLengthVariance: number;
  vocabularyRichness: number;
  punctuationDensity: number;
  burstiness: number;
  repetitionScore: number;
}

Sources: truelens-app/src/lib/analysis.ts:9-20

Document Verification Schemas

The document verification module uses schemas to track file integrity, tamper detection findings, and cryptographic authenticity.

Document and Finding Structure

When a document is processed, it generates a Document object populated with DocumentFinding entries that categorize issues by severity.

Component	Field	Type	Description
Document	hash	String	SHA-256 hash of the file for integrity tracking.
	status	Enum	verified, flagged, pending, or analyzing.
Finding	type	String	Category (e.g., Font Consistency, Tamper Detection).
	severity	Enum	low, medium, or high.
	message	String	Human-readable explanation of the finding.

Sources: truelens-app/src/lib/types.ts:39-64, truelens-backend/app/services/document_analysis.py:84-110

Cryptographic Signatures

For verified documents, a signature schema ensures the content remains tamper-evident.

API Request and Response Schemas

The Developer Portal defines the external-facing structure for these schemas used in RESTful interactions.

Scan Request Schema

Used when submitting content via POST /api/v1/scans.

• url: (Optional) The target website to scrape and analyze.
• text: (Optional) Raw text content for analysis.
• contentType: Required enum ("url" or "text").

Standardized Response Schema

A successful analysis returns a structured JSON object containing the scan results and associated signals.

{
  "success": true,
  "scan": {
    "id": "scan_abc123",
    "trustScore": 82,
    "verdict": "Authentic",
    "signals": [
      {
        "type": "text",
        "score": 85,
        "label": "Likely Human-Written"
      }
    ]
  }
}

Sources: truelens-app/src/app/developers/page.tsx:12-20, truelens-app/src/lib/types.ts:86-90

Conclusion

Pydantic data schemas in TrueLens provide the necessary structure for complex multi-signal analysis. By standardizing the format of signals, findings, and signatures, the system maintains high data integrity from the moment a URL is scanned or a document is uploaded until the final verdict is stored and displayed on the dashboard.