# aravde/trueview architecture

> Architecture diagram of the GitHub repository aravde/trueview, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aravde/trueview
- Repository: https://github.com/aravde/trueview

## Overview

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: [`backend/save_file.py`](https://github.com/aravde/trueview/blob/main/backend/save_file.py) (Save File API), [`frontend/src/pages/Dashboard.tsx`](https://github.com/aravde/trueview/blob/main/frontend/src/pages/Dashboard.tsx) (Dashboard), [`frontend/src/App.tsx`](https://github.com/aravde/trueview/blob/main/frontend/src/App.tsx) (App Shell), [`frontend/src/components/DataBreakdown.tsx`](https://github.com/aravde/trueview/blob/main/frontend/src/components/DataBreakdown.tsx) (Data Breakdown)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_upload["Upload<br/>screen<br/>[Upload.tsx]"]
  node_ui_dashboard["Dashboard<br/>screen<br/>[Dashboard.tsx]"]
  node_ui_notfound["Not Found<br/>screen<br/>[NotFound.tsx]"]
  node_comp_verdict["Verdict Card<br/>result-card"]
  node_comp_reasoning["Reasoning Panel<br/>explanation-panel"]
  node_comp_breakdown["Data Breakdown<br/>metrics-view<br/>[DataBreakdown.tsx]"]
  node_comp_summary["Conclusion Summary<br/>summary-panel"]
  node_comp_image["Image Viewer<br/>media-view<br/>[ImageViewer.tsx]"]
  node_comp_metric["Metric Box<br/>metric-ui<br/>[MetricBox.tsx]"]
  node_app_shell["App Shell<br/>react-root<br/>[App.tsx]"]
end

subgraph group_backend["Backend"]
  node_backend_api["Save File API<br/>fastapi-entrypoint<br/>[save_file.py]"]
  node_file_validation["File Validation<br/>validation-service"]
  node_detector["Detector<br/>verdict-engine<br/>[detector.py]"]
  node_classifier["Attr Classifier<br/>[attrClassifier.py]"]
  node_explainability["Explainability<br/>cv-interpretation<br/>[explainability.py]"]
  node_prompt_builder["Prompt Builder<br/>llm-prompting<br/>[prompt_builder.py]"]
  node_backend_tests["Explainability Tests<br/>test-suite"]
end

node_ui_upload -->|"submit media"| node_backend_api
node_app_shell -->|"routes to"| node_ui_upload
node_app_shell -->|"routes to"| node_ui_dashboard
node_app_shell -->|"fallback"| node_ui_notfound
node_ui_dashboard -->|"renders"| node_comp_verdict
node_ui_dashboard -->|"renders"| node_comp_reasoning
node_ui_dashboard -->|"renders"| node_comp_breakdown
node_ui_dashboard -->|"renders"| node_comp_summary
node_ui_dashboard -->|"renders"| node_comp_image
node_comp_breakdown -->|"uses"| node_comp_metric
node_backend_api -->|"validates"| node_file_validation
node_backend_api -->|"verdict flow"| node_detector
node_detector -->|"uses"| node_classifier
node_backend_api -->|"analyzes"| node_explainability
node_explainability -->|"builds prompt"| node_prompt_builder
node_backend_api -->|"returns analysis"| node_comp_reasoning
node_backend_api -->|"returns metrics"| node_comp_breakdown
node_backend_api -->|"returns verdict"| node_comp_verdict
node_backend_tests -.->|"covers"| node_explainability

click node_ui_upload "https://github.com/aravde/trueview/blob/main/frontend/src/pages/Upload.tsx"
click node_ui_dashboard "https://github.com/aravde/trueview/blob/main/frontend/src/pages/Dashboard.tsx"
click node_ui_notfound "https://github.com/aravde/trueview/blob/main/frontend/src/pages/NotFound.tsx"
click node_comp_verdict "https://github.com/aravde/trueview/blob/main/frontend/src/components/AnalysisVerdict.tsx"
click node_comp_reasoning "https://github.com/aravde/trueview/blob/main/frontend/src/components/AnalysisReasoning.tsx"
click node_comp_breakdown "https://github.com/aravde/trueview/blob/main/frontend/src/components/DataBreakdown.tsx"
click node_comp_summary "https://github.com/aravde/trueview/blob/main/frontend/src/components/ConclusionSummary.tsx"
click node_comp_image "https://github.com/aravde/trueview/blob/main/frontend/src/components/ImageViewer.tsx"
click node_comp_metric "https://github.com/aravde/trueview/blob/main/frontend/src/components/MetricBox.tsx"
click node_app_shell "https://github.com/aravde/trueview/blob/main/frontend/src/App.tsx"
click node_backend_api "https://github.com/aravde/trueview/blob/main/backend/save_file.py"
click node_file_validation "https://github.com/aravde/trueview/blob/main/backend/file_validation_service.py"
click node_detector "https://github.com/aravde/trueview/blob/main/backend/detector.py"
click node_classifier "https://github.com/aravde/trueview/blob/main/backend/attrClassifier.py"
click node_explainability "https://github.com/aravde/trueview/blob/main/backend/explainability.py"
click node_prompt_builder "https://github.com/aravde/trueview/blob/main/backend/prompt_builder.py"
click node_backend_tests "https://github.com/aravde/trueview/blob/main/backend/test/test_explainability_image.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui_upload,node_ui_dashboard,node_ui_notfound,node_comp_verdict,node_comp_reasoning,node_comp_breakdown,node_comp_summary,node_comp_image,node_comp_metric,node_app_shell toneBlue
class node_backend_api,node_file_validation,node_detector,node_classifier,node_explainability,node_prompt_builder,node_backend_tests toneAmber
```

## Components

### Frontend

React/TypeScript UI for upload, results, and explanation rendering.

- [Upload](https://github.com/aravde/trueview/blob/main/frontend/src/pages/Upload.tsx): screen · Entry screen for submitting media for analysis. · `frontend/src/pages/Upload.tsx`
- [Dashboard](https://github.com/aravde/trueview/blob/main/frontend/src/pages/Dashboard.tsx): screen · Results view that presents verdicts, reasoning, and breakdowns. · `frontend/src/pages/Dashboard.tsx`
- [Not Found](https://github.com/aravde/trueview/blob/main/frontend/src/pages/NotFound.tsx): screen · Fallback route for unknown pages. · `frontend/src/pages/NotFound.tsx`
- [Verdict Card](https://github.com/aravde/trueview/blob/main/frontend/src/components/AnalysisVerdict.tsx): result-card · Displays the primary authenticity decision. · `frontend/src/components/AnalysisVerdict.tsx`
- [Reasoning Panel](https://github.com/aravde/trueview/blob/main/frontend/src/components/AnalysisReasoning.tsx): explanation-panel · Renders human-readable analysis explanations. · `frontend/src/components/AnalysisReasoning.tsx`
- [Data Breakdown](https://github.com/aravde/trueview/blob/main/frontend/src/components/DataBreakdown.tsx): metrics-view · Shows structured forensic metrics and signal details. · `frontend/src/components/DataBreakdown.tsx`
- [Conclusion Summary](https://github.com/aravde/trueview/blob/main/frontend/src/components/ConclusionSummary.tsx): summary-panel · Condenses findings into a final takeaway. · `frontend/src/components/ConclusionSummary.tsx`
- [Image Viewer](https://github.com/aravde/trueview/blob/main/frontend/src/components/ImageViewer.tsx): media-view · Displays the uploaded image or video frame context. · `frontend/src/components/ImageViewer.tsx`
- [Metric Box](https://github.com/aravde/trueview/blob/main/frontend/src/components/MetricBox.tsx): metric-ui · Reusable metric presentation component. · `frontend/src/components/MetricBox.tsx`
- [App Shell](https://github.com/aravde/trueview/blob/main/frontend/src/App.tsx): react-root · 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](https://github.com/aravde/trueview/blob/main/backend/save_file.py): fastapi-entrypoint · Backend entrypoint exposing upload and analysis orchestration. · `backend/save_file.py`
- [File Validation](https://github.com/aravde/trueview/blob/main/backend/file_validation_service.py): validation-service · Checks uploaded media before downstream processing. · `backend/file_validation_service.py`
- [Detector](https://github.com/aravde/trueview/blob/main/backend/detector.py): verdict-engine · Wraps primary detection or classification signals. · `backend/detector.py`
- [Attr Classifier](https://github.com/aravde/trueview/blob/main/backend/attrClassifier.py): classifier · Produces classification signals used by the verdict layer. · `backend/attrClassifier.py`
- [Explainability](https://github.com/aravde/trueview/blob/main/backend/explainability.py): cv-interpretation · Computes forensic metrics and turns them into user-facing analysis. · `backend/explainability.py`
- [Prompt Builder](https://github.com/aravde/trueview/blob/main/backend/prompt_builder.py): llm-prompting · Builds prompts from metrics for text explanation generation. · `backend/prompt_builder.py`
- [Explainability Tests](https://github.com/aravde/trueview/blob/main/backend/test/test_explainability_image.py): test-suite · Image and video validation paths for explainability logic. · `backend/test/test_explainability_image.py`

## Connections

- 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.
