Frontend State Management
Relevant source files
The following files were used as context for generating this wiki page:
Frontend state management in TrueLens is handled through a combination of React component-level state, URL-based routing state, and asynchronous data fetching patterns. The application utilizes the "use client" directive extensively to manage interactive UI states, including form inputs, loading indicators, and API response data for content analysis and document verification.
The architecture relies on React's useState and useEffect hooks to synchronize local UI state with data returned from the backend API. Key stateful domains include content scanning results, document upload history, and verification status.
Data Models and Type Definitions
The state structure is governed by a set of TypeScript interfaces that define the shape of the data being managed across different views. These interfaces ensure consistency between the API responses and the internal state of the frontend components.
| Interface | Description | Key Fields |
|---|---|---|
Scan | Represents a content analysis result. | id, trustScore, verdict, signals, status |
Signal | A specific evidence point within a scan. | type, score, confidence, evidence |
Document | Represents an uploaded file and its analysis. | filename, hash, trustScore, findings, signature |
AnalysisResult | Structure for raw analysis metrics. | score, label, confidence, highlights |
Sources: truelens-app/src/lib/types.ts:18-64, truelens-app/src/lib/types.ts:98-104
Component State Lifecycle
State transitions in TrueLens typically follow a pattern of User Input -> API Request -> State Update. This is observed in modules such as the Scan page and the Document Verification dashboard.
Content Scan State Flow
When a user submits content (URL or text) for analysis, the component manages several states: activeTab to toggle input types, loading to trigger UI placeholders, and error to handle validation or network failures.
Document Verification State
The Document Verification module manages local arrays of documents and active modal states. It uses useCallback to optimize drag-and-drop event handlers that update the dragActive and uploading states.
Navigation and Persistent State
TrueLens uses Next.js routing to handle state that needs to persist across page refreshes or be shareable via URL. The ResultsPage derives its state from the id parameter provided in the URL path.
- URL Parameters: Components use
use(params)to extract IDs (e.g.,scanId). - Initial Load: A
useEffecthook triggers a fetch based on that ID. - Local Sync: The fetched data is stored in a
scanstate variable to drive theTrustScoreGaugeandSignalCardcomponents.
Sources: truelens-app/src/app/results/[id]/page.tsx:21-42
API Synchronization and Mapping
The frontend state often requires mapping from backend naming conventions (snake_case) to frontend conventions (camelCase). This mapping is performed in the Route Handlers which act as a proxy between the Next.js frontend and the FastAPI backend.
// Example of state mapping in route handlers
const scan = {
...data,
contentType: data.content_type,
trustScore: data.trust_score,
scanDuration: data.scan_duration,
createdAt: data.created_at
};
Sources: truelens-app/src/app/api/v1/scans/route.ts:37-44
Verification and QR State
The VerifyPage manages a complex state involving a third-party library (html5-qrcode). It manages the lifecycle of a scanner instance and transitions to a "Verified" or "Failed" state based on the input hash or scan ID.
- Scanner State: Managed via
scannerOpenboolean. - Result State: Uses a
VerificationResultobject that includes the document details and verification messages. - Input State: Real-time tracking of the SHA-256 hash or Scan ID string.
Sources: truelens-app/src/app/verify/page.tsx:24-69
Conclusion
State management in TrueLens is decentralized, focusing on component-level ownership of data. By strictly defining types in src/lib/types.ts and utilizing standard React hooks for API synchronization, the system maintains a predictable flow of data from content submission to result visualization.