How aravde/trueview works
1. What this repo is
- TrueView is a two-tier deepfake detection system: a Python backend performs media validation, computer-vision analysis, and explainability generation; a TypeScript/React frontend presents uploads, verdicts, and metric-driven explanations.
2. Primary architectural boundary
- The main boundary is between the browser UI and the FastAPI backend.
- The frontend is responsible for user interaction and rendering results; the backend owns all detection logic, file handling, and model/API calls.
- This is a local-first design, with the README emphasizing privacy and on-machine processing.
3. Frontend subsystem
- The frontend lives under frontend/ and is built with Vite + React + TypeScript + Tailwind/shadcn-style UI components.
- Key screens are Upload, Dashboard, and NotFound, which suggests a flow from media submission to results visualization.
- The component set indicates a dashboard-style experience: verdict cards, reasoning panels, metric boxes, image viewer, data breakdown, and conclusion summary.
4. Frontend data presentation
- AnalysisVerdict, AnalysisReasoning, DataBreakdown, ConclusionSummary, and MetricBox imply the UI is structured around:
- a final authenticity classification,
- human-readable explanation text,
- numeric forensic metrics,
- and a summarized conclusion.
- ImageViewer suggests the frontend can show the uploaded media alongside the analysis.
5. Backend entrypoint and file flow
- The backend entrypoint is backend/save_file.py, which is the module referenced in the README’s uvicorn backend.save_file:app.
- This implies FastAPI routes are defined there and likely handle upload, persistence, and orchestration of downstream analysis.
- backend/file_validation_service.py suggests uploads are validated before analysis, forming the first backend gate.
6. Detection and classification layer
- backend/detector.py and backend/attrClassifier.py indicate a dedicated analysis layer for classifying media and/or extracting detection signals.
- The README states the primary verdict comes from the AI or NOT API, so this layer likely wraps the external verdict source and normalizes its output for the rest of the system.
7. Computer-vision forensic analysis
- backend/explainability.py is the main bridge between raw media metrics and user-facing interpretation.
- The README mentions OpenCV-derived signals such as edge consistency, texture variance, motion artifacts, flickering edges, and unnatural smoothing.
- This means the backend produces structured forensic metrics first, then transforms them into explanation text rather than directly outputting a black-box verdict.
8. LLM-based explanation generation
- backend/prompt_builder.py strongly suggests a prompt construction layer for feeding computed metrics into a local or external LLM.
- The README mentions Ollama and optionally Gemini API for explainability, so the architecture separates:
- metric extraction,
- prompt composition,
- and natural-language explanation generation.
- This keeps explanation logic decoupled from the CV pipeline.
9. Concurrency and performance model
- The README explicitly calls out an async FastAPI backend, parallel explanation generation with asyncio.gather, and offloading heavy CV work to thread executors.
- Architecturally, that means request handling is designed to avoid blocking the server while media analysis runs, which is important for upload responsiveness and multi-user concurrency.
10. Tests and validation assets
- backend/test/test_explainability_image.py and backend/test/test_explainability_video.py indicate separate validation paths for still images and videos.
- The test_images/ directory contains sample media and UI screenshots, supporting manual verification and likely regression testing of the analysis pipeline.
11. Repository structure signal
- The repo contains both frontend and backend build artifacts/configuration (package.json, Vite config, Python requirements), so it is a full-stack application rather than a library.
- The README’s “vanilla JS” note is outdated relative to the current tree; the actual frontend is a React/TypeScript app.
12. End-to-end data flow
- The intended flow is: user uploads media in the frontend → backend validates and stores/processes the file → detector/classifier obtains a primary verdict → OpenCV-based analysis computes forensic metrics → prompt builder feeds those metrics to an LLM → frontend renders verdict, reasoning, and detailed breakdown.
- The architectural emphasis is not just detection accuracy, but explainability and education through transparent metric reporting.
Main entry points: save_file.py Save File API · Dashboard.tsx Dashboard · App.tsx App Shell · DataBreakdown.tsx Data Breakdown
Components 17
Frontend
React/TypeScript UI for upload, results, and explanation rendering.
- Upload · Entry screen for submitting media for analysis.
frontend/src/pages/Upload.tsx - Dashboard · Results view that presents verdicts, reasoning, and breakdowns.
frontend/src/pages/Dashboard.tsx - Not Found · Fallback route for unknown pages.
frontend/src/pages/NotFound.tsx - Verdict Card · Displays the primary authenticity decision.
frontend/src/components/AnalysisVerdict.tsx - Reasoning Panel · Renders human-readable analysis explanations.
frontend/src/components/AnalysisReasoning.tsx - Data Breakdown · Shows structured forensic metrics and signal details.
frontend/src/components/DataBreakdown.tsx - Conclusion Summary · Condenses findings into a final takeaway.
frontend/src/components/ConclusionSummary.tsx - Image Viewer · Displays the uploaded image or video frame context.
frontend/src/components/ImageViewer.tsx - Metric Box · Reusable metric presentation component.
frontend/src/components/MetricBox.tsx - App Shell · Top-level frontend composition and routing bootstrap.
frontend/src/App.tsx
Backend
FastAPI analysis pipeline for validation, detection, forensic metrics, and explanations.
- Save File API · Backend entrypoint exposing upload and analysis orchestration.
backend/save_file.py - File Validation · Checks uploaded media before downstream processing.
backend/file_validation_service.py - Detector · Wraps primary detection or classification signals.
backend/detector.py - Attr Classifier · Produces classification signals used by the verdict layer.
backend/attrClassifier.py - Explainability · Computes forensic metrics and turns them into user-facing analysis.
backend/explainability.py - Prompt Builder · Builds prompts from metrics for text explanation generation.
backend/prompt_builder.py - Explainability Tests · Image and video validation paths for explainability logic.
backend/test/test_explainability_image.py
Connections 19
- Upload → Save File API: submit media · User uploads media for backend analysis.
- App Shell → Upload: routes to · App routes users into the upload flow.
- App Shell → Dashboard: routes to · App routes users to results after analysis.
- App Shell → Not Found: fallback · Unknown routes render the fallback page.
- Dashboard → Verdict Card: renders · Dashboard presents the main verdict component.
- Dashboard → Reasoning Panel: renders · Dashboard presents explanation text and rationale.
- Dashboard → Data Breakdown: renders · Dashboard presents metric breakdowns.
- Dashboard → Conclusion Summary: renders · Dashboard presents the final summary.
- Dashboard → Image Viewer: renders · Dashboard shows the analyzed media preview.
- Data Breakdown → Metric Box: uses · Metric boxes are reused inside the breakdown view.
- Save File API → File Validation: validates · Upload requests are checked before analysis.
- Save File API → Detector: verdict flow · Backend delegates primary detection/classification.
- Detector → Attr Classifier: uses · Detection layer uses classification signals.
- Save File API → Explainability: analyzes · Backend computes forensic metrics and explanation inputs.
- Explainability → Prompt Builder: builds prompt · Computed metrics are transformed into LLM prompts.
- Save File API → Reasoning Panel: returns analysis · Backend supplies explanation text to the frontend.
- Save File API → Data Breakdown: returns metrics · Backend supplies structured metrics for display.
- Save File API → Verdict Card: returns verdict · Backend provides the final authenticity result.
- Explainability Tests → Explainability: covers · Tests exercise explainability for images and videos.