# shalvirajpura2/letsverify architecture

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

- Interactive diagram: https://gitdiagram.com/shalvirajpura2/letsverify
- Repository: https://github.com/shalvirajpura2/letsverify

## Overview

1. **Overall shape**
   - This repo is a two-tier application: a **FastAPI inference backend** and a **React/Vite frontend**.
   - The core product boundary is clear: the frontend only handles user interaction and upload flow, while the backend owns all image-forensics logic and verdict generation.

2. **Backend entrypoint and API boundary**
   - `backend/api/main.py` is the server entrypoint.
   - It exposes at least two HTTP endpoints: `POST /detect` for image analysis and `GET /health` for liveness checks.
   - Input is a `multipart/form-data` file upload, and the response is a structured verdict payload containing the final class, confidence, individual detector signals, and human-readable explanation.

3. **Inference orchestration layer**
   - `backend/pipeline/inference_pipeline.py` is the backend’s coordination layer.
   - Its job is to run detectors, collect their outputs, and synthesize a single verdict with confidence scoring.
   - The README indicates an **async parallel runner** with **adaptive weighting**, so the architectural pattern is “fan out to signal detectors, then aggregate.”

4. **Detector subsystem**
   - `backend/detectors/` is the main analytical subsystem and is organized by signal type.
   - The README highlights four core detectors: **AI model classification**, **metadata/EXIF**, **frequency/FFT**, and **noise analysis**.
   - The tree shows additional forensic modules such as `c2pa`, `clip`, `color`, `edge`, `ela`, `face`, `jpeg`, `lighting`, `texture`, and `watermark`, suggesting the system is designed as a broader multi-signal detector framework, even if only a subset is primary in the current product story.

5. **How the backend produces a verdict**
   - The backend does not emit a simple binary answer; it produces a **7-class confidence verdict** ranging from “Real Photograph” to “AI Generated.”
   - Each detector contributes a numeric score and short explanation, which are combined into an overall confidence and a consensus/conflict indicator.
   - This makes the backend a fusion system rather than a single-model classifier.

6. **Primary data flow**
   - The end-to-end path is: **browser upload → frontend API call → FastAPI `/detect` → image decoding and detector execution → aggregation pipeline → JSON response → result display**.
   - The response schema is designed for both machine use and UX clarity: final label, confidence percentage, per-signal explanations, and the original filename.

7. **Frontend composition**
   - The frontend is a Vite-built React app in `frontend/src/`.
   - `App.jsx` is the orchestration component, with UI pieces split into `UploadZone`, `ResultPanel`, `BatchPanel`, and `Header`.
   - The UI is centered around a single-image upload flow, with an additional batch-oriented panel in the component structure for broader usage or future extension.

8. **Client-to-backend coupling**
   - The frontend is configured via `VITE_API_URL`, which means the backend URL is injected at build/runtime rather than hardcoded.
   - Backend CORS is controlled by `CORS_ORIGINS`, so cross-origin access is an explicit deployment concern.
   - This keeps the frontend and backend independently deployable while still connected through a small API surface.

9. **Deployment topology**
   - `docker-compose.yml` is the local integration boundary that runs both services together.
   - The backend has its own Dockerfile and Python dependency set; the frontend has a separate Dockerfile and Node/Vite toolchain.
   - The README also documents standalone deployment targets for the frontend and backend, reinforcing that the system is split into independently hosted services.

10. **Operational/environment concerns**
   - `backend/.env.example` includes runtime limits and network settings such as port, host, max file size, and allowed origins.
   - That implies the backend is responsible for request-size enforcement and safe exposure in production.
   - The architecture is therefore not just compute-oriented; it also includes basic service hardening around upload handling and cross-origin access.

11. **Technology boundaries that matter**
   - Backend analysis uses Python ML/image libraries: FastAPI for transport, plus PyTorch/Transformers, Pillow, NumPy, and SciPy for inference and signal processing.
   - The frontend uses React 18 and Vite, which favors a fast static client that communicates only with the API.
   - Docker is the main packaging boundary for local development and deployment portability.

12. **What to draw in an architecture diagram**
   - Draw two major boxes: **Frontend UI** and **Backend Inference Service**.
   - Inside the backend, show three layers: **API layer**, **pipeline/aggregation layer**, and **detector modules**.
   - Show the detector fan-out as parallel signals feeding into an aggregator, which emits a single verdict response back to the UI.
   - Include Docker Compose as the local runtime that connects the two services, and external deployment endpoints as optional production targets.

Main entry points: [`backend/pipeline/inference_pipeline.py`](https://github.com/shalvirajpura2/letsverify/blob/main/backend/pipeline/inference_pipeline.py) (Inference Pipeline), [`frontend/src/App.jsx`](https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/App.jsx) (App), [`backend/api/main.py`](https://github.com/shalvirajpura2/letsverify/blob/main/backend/api/main.py) (API Main), [`docker-compose.yml`](https://github.com/shalvirajpura2/letsverify/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend UI"]
  node_frontend_app["App<br/>React shell<br/>[App.jsx]"]
  node_frontend_upload["Upload Zone<br/>upload UI<br/>[UploadZone.jsx]"]
  node_frontend_result["Result Panel<br/>results UI<br/>[ResultPanel.jsx]"]
  node_frontend_batch["Batch Panel<br/>batch UI<br/>[BatchPanel.jsx]"]
  node_frontend_header["Header<br/>layout UI<br/>[Header.jsx]"]
  node_frontend_main["Entry<br/>[main.jsx]"]
end

subgraph group_backend["Backend Inference"]
  node_backend_main["API Main<br/>FastAPI entry<br/>[main.py]"]
  node_backend_pipeline["Inference Pipeline<br/>orchestrator"]
  node_backend_ai["AI Detector<br/>signal detector<br/>[ai_detector.py]"]
  node_backend_metadata["Metadata<br/>signal detector"]
  node_backend_frequency["Frequency<br/>signal detector"]
  node_backend_noise["Noise<br/>signal detector<br/>[noise_detector.py]"]
  node_backend_c2pa["C2PA<br/>signal detector<br/>[c2pa_detector.py]"]
  node_backend_jpeg["JPEG<br/>signal detector<br/>[jpeg_detector.py]"]
  node_backend_ela["ELA<br/>signal detector<br/>[ela_detector.py]"]
  node_backend_texture["Texture<br/>signal detector"]
  node_backend_face["Face<br/>signal detector<br/>[face_detector.py]"]
  node_backend_other["Other Signals<br/>detector bundle<br/>[clip_detector.py]"]
end

subgraph group_infra["Runtime"]
  node_docker_compose["Compose<br/>local runtime<br/>[docker-compose.yml]"]
  node_backend_env["Backend Env<br/>config<br/>[.env.example]"]
  node_frontend_env["Frontend Env<br/>config<br/>[.env.example]"]
end

node_frontend_main -->|"mounts"| node_frontend_app
node_frontend_app -->|"renders"| node_frontend_header
node_frontend_app -->|"uses"| node_frontend_upload
node_frontend_app -->|"uses"| node_frontend_result
node_frontend_app -->|"uses"| node_frontend_batch
node_frontend_upload -->|"POST /detect"| node_backend_main
node_frontend_app -.->|"reads"| node_frontend_env
node_backend_main -->|"calls"| node_backend_pipeline
node_backend_main -.->|"reads"| node_backend_env
node_backend_pipeline -->|"fans out"| node_backend_ai
node_backend_pipeline -->|"fans out"| node_backend_metadata
node_backend_pipeline -->|"fans out"| node_backend_frequency
node_backend_pipeline -->|"fans out"| node_backend_noise
node_backend_pipeline -->|"fans out"| node_backend_c2pa
node_backend_pipeline -->|"fans out"| node_backend_jpeg
node_backend_pipeline -->|"fans out"| node_backend_ela
node_backend_pipeline -->|"fans out"| node_backend_texture
node_backend_pipeline -->|"fans out"| node_backend_face
node_backend_pipeline -.->|"fans out"| node_backend_other
node_backend_pipeline -->|"returns verdict"| node_backend_main
node_docker_compose -->|"starts"| node_frontend_main
node_docker_compose -->|"starts"| node_backend_main

click node_frontend_app "https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/App.jsx"
click node_frontend_upload "https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/components/UploadZone.jsx"
click node_frontend_result "https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/components/ResultPanel.jsx"
click node_frontend_batch "https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/components/BatchPanel.jsx"
click node_frontend_header "https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/components/Header.jsx"
click node_frontend_main "https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/main.jsx"
click node_backend_main "https://github.com/shalvirajpura2/letsverify/blob/main/backend/api/main.py"
click node_backend_pipeline "https://github.com/shalvirajpura2/letsverify/blob/main/backend/pipeline/inference_pipeline.py"
click node_backend_ai "https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/ai_detector.py"
click node_backend_metadata "https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/metadata_detector.py"
click node_backend_frequency "https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/frequency_detector.py"
click node_backend_noise "https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/noise_detector.py"
click node_backend_c2pa "https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/c2pa_detector.py"
click node_backend_jpeg "https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/jpeg_detector.py"
click node_backend_ela "https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/ela_detector.py"
click node_backend_texture "https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/texture_detector.py"
click node_backend_face "https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/face_detector.py"
click node_backend_other "https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/clip_detector.py"
click node_docker_compose "https://github.com/shalvirajpura2/letsverify/blob/main/docker-compose.yml"
click node_backend_env "https://github.com/shalvirajpura2/letsverify/blob/main/backend/.env.example"
click node_frontend_env "https://github.com/shalvirajpura2/letsverify/blob/main/frontend/.env.example"

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_frontend_app,node_frontend_upload,node_frontend_result,node_frontend_batch,node_frontend_header,node_frontend_main toneBlue
class node_backend_main,node_backend_pipeline,node_backend_ai,node_backend_metadata,node_backend_frequency,node_backend_noise,node_backend_c2pa,node_backend_jpeg,node_backend_ela,node_backend_texture,node_backend_face,node_backend_other toneAmber
class node_docker_compose,node_backend_env,node_frontend_env toneMint
```

## Components

### Frontend UI

React/Vite client for upload and verdict display

- [App](https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/App.jsx): React shell · Top-level UI orchestration and API wiring · `frontend/src/App.jsx`
- [Upload Zone](https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/components/UploadZone.jsx): upload UI · Single-image upload and submission entry point · `frontend/src/components/UploadZone.jsx`
- [Result Panel](https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/components/ResultPanel.jsx): results UI · Displays final verdict, confidence, and explanations · `frontend/src/components/ResultPanel.jsx`
- [Batch Panel](https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/components/BatchPanel.jsx): batch UI · Secondary panel for multi-item or future batch workflows · `frontend/src/components/BatchPanel.jsx`
- [Header](https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/components/Header.jsx): layout UI · Branding and page-level framing · `frontend/src/components/Header.jsx`
- [Entry](https://github.com/shalvirajpura2/letsverify/blob/main/frontend/src/main.jsx): React entry · Mounts the Vite React application · `frontend/src/main.jsx`

### Backend Inference

FastAPI service and image-forensics pipeline

- [API Main](https://github.com/shalvirajpura2/letsverify/blob/main/backend/api/main.py): FastAPI entry · Server entrypoint exposing detect and health endpoints · `backend/api/main.py`
- [Inference Pipeline](https://github.com/shalvirajpura2/letsverify/blob/main/backend/pipeline/inference_pipeline.py): orchestrator · Coordinates detectors and fuses their outputs into one verdict · `backend/pipeline/inference_pipeline.py`
- [AI Detector](https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/ai_detector.py): signal detector · Model-based classification signal · `backend/detectors/ai_detector.py`
- [Metadata](https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/metadata_detector.py): signal detector · EXIF and file metadata analysis · `backend/detectors/metadata_detector.py`
- [Frequency](https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/frequency_detector.py): signal detector · FFT and frequency-domain analysis · `backend/detectors/frequency_detector.py`
- [Noise](https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/noise_detector.py): signal detector · Noise-consistency analysis · `backend/detectors/noise_detector.py`
- [C2PA](https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/c2pa_detector.py): signal detector · Content provenance and authenticity checks · `backend/detectors/c2pa_detector.py`
- [JPEG](https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/jpeg_detector.py): signal detector · Compression artifact analysis · `backend/detectors/jpeg_detector.py`
- [ELA](https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/ela_detector.py): signal detector · Error-level analysis signal · `backend/detectors/ela_detector.py`
- [Texture](https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/texture_detector.py): signal detector · Texture-consistency analysis · `backend/detectors/texture_detector.py`
- [Face](https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/face_detector.py): signal detector · Face-region forensic signal · `backend/detectors/face_detector.py`
- [Other Signals](https://github.com/shalvirajpura2/letsverify/blob/main/backend/detectors/clip_detector.py): detector bundle · Additional forensic detectors such as clip, color, edge, lighting, and watermark · `backend/detectors/clip_detector.py`

### Runtime

Local container orchestration and deployment packaging

- [Compose](https://github.com/shalvirajpura2/letsverify/blob/main/docker-compose.yml): local runtime · Runs frontend and backend together for local integration · `docker-compose.yml`
- [Backend Env](https://github.com/shalvirajpura2/letsverify/blob/main/backend/.env.example): config · Host, port, file-size, and CORS settings · `backend/.env.example`
- [Frontend Env](https://github.com/shalvirajpura2/letsverify/blob/main/frontend/.env.example): config · Build-time API endpoint configuration · `frontend/.env.example`

## Connections

- Entry → App: mounts · Bootstraps the React app
- App → Header: renders · Page framing
- App → Upload Zone: uses · Collects image input
- App → Result Panel: uses · Shows verdict output
- App → Batch Panel: uses · Secondary batch-oriented UI
- Upload Zone → API Main: POST /detect · Sends multipart image upload
- App → Frontend Env: reads · Uses API base URL at build/runtime
- API Main → Inference Pipeline: calls · Delegates analysis to the inference pipeline
- API Main → Backend Env: reads · Uses runtime limits and CORS settings
- Inference Pipeline → AI Detector: fans out · Runs model classification in parallel
- Inference Pipeline → Metadata: fans out · Runs metadata analysis in parallel
- Inference Pipeline → Frequency: fans out · Runs frequency analysis in parallel
- Inference Pipeline → Noise: fans out · Runs noise analysis in parallel
- Inference Pipeline → C2PA: fans out · Runs provenance checks when available
- Inference Pipeline → JPEG: fans out · Runs compression analysis
- Inference Pipeline → ELA: fans out · Runs ELA signal extraction
- Inference Pipeline → Texture: fans out · Runs texture analysis
- Inference Pipeline → Face: fans out · Runs face-region signal analysis
- Inference Pipeline → Other Signals: fans out · Collects additional forensic signals
- Inference Pipeline → API Main: returns verdict · Aggregates scores and explanations into JSON response
- Compose → Entry: starts · Brings up the client service
- Compose → API Main: starts · Brings up the inference service
