# renzkirby/truthlens architecture

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

- Interactive diagram: https://gitdiagram.com/renzkirby/truthlens
- Repository: https://github.com/renzkirby/truthlens

## Overview

TruthLens combines a browser extension, web community, and Django service for evidence-first misinformation verification. The primary workflow takes text, URLs, images, or documents through input processing, claim matching, internal knowledge lookup, external evidence retrieval, and evidence-grounded analysis; uncertain claims can enter collaborative review. The web platform also supports community discussions, moderation, organization workspaces, and publication. Edges reflect README-documented flows or source-index references; unsampled implementations are represented only at supported directory paths.

Main entry points: [`backend/truthlens_backend/api/models.py`](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/models.py) (Domain records), [`frontend/frontend/src/App.jsx`](https://github.com/renzkirby/truthlens/blob/main/frontend/frontend/src/App.jsx) (Web platform), [`backend/truthlens_backend/api/evidence_review_service.py`](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/evidence_review_service.py) (Evidence review), [`backend/truthlens_backend/api/publication_workflow_query_service.py`](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/publication_workflow_query_service.py) (Publication workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_extension["Browser extension<br/>[App.jsx]"]
  node_web_app["Web platform<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_verification["Verification pipeline"]
  node_input_processing["Input processing<br/>[ocr_service.py]"]
  node_claim_matching["Claim matching<br/>[claim_matching.py]"]
  node_knowledge_reuse["Knowledge reuse"]
  node_evidence_pipeline["Evidence retrieval"]
  node_verification_result["AI analysis"]
end

subgraph group_community["Community review"]
  node_community_feed["Community feed<br/>[CommunityFeed.jsx]"]
  node_thread_detail["Threads and evidence"]
  node_evidence_review["Evidence review"]
  node_moderation["Moderation"]
  node_trust["Trust scores<br/>[trust_service.py]"]
  node_assignment["Verification assignment"]
end

subgraph group_publishing["Organizations and publishing"]
  node_workspace["Organization workspace<br/>[WorkspacePage.jsx]"]
  node_organization["Organization services"]
  node_publication_work["Publication workflow"]
  node_publishing_service["Publishing"]
  node_correction["Factual corrections"]
  node_accountability["Accountability"]
end

subgraph group_foundation["Shared backend"]
  node_api_routes["Backend API<br/>[views.py]"]
  node_models[("Domain records<br/>[models.py]")]
  node_evidence_schema["Evidence snapshots"]
  node_publication_schema["Publication snapshots"]
  node_background_tasks["Background tasks<br/>[tasks.py]"]
end

node_browser_user(("Browser user"))
node_web_user(("Web user"))

node_browser_user -->|"submits content"| node_extension
node_extension -.->|"requests verification"| node_api_routes
node_web_user -->|"uses platform"| node_web_app
node_web_app -->|"calls API"| node_api_client
node_api_client -.->|"sends requests"| node_api_routes
node_api_routes -->|"processes inputs"| node_input_processing
node_input_processing -->|"matches claims"| node_claim_matching
node_claim_matching -->|"checks knowledge"| node_knowledge_reuse
node_knowledge_reuse -->|"retrieves evidence"| node_evidence_pipeline
node_evidence_pipeline -->|"grounds analysis"| node_verification_result
node_verification_result -->|"escalates uncertain claims"| node_thread_detail
node_web_app -->|"routes to feed"| node_community_feed
node_web_app -->|"routes to threads"| node_thread_detail
node_thread_detail -->|"submits evidence"| node_evidence_review
node_evidence_review -->|"reads and writes"| node_models
node_evidence_review -->|"uses moderation"| node_moderation
node_evidence_review -->|"uses assignments"| node_assignment
node_evidence_review -->|"updates reputation"| node_trust
node_web_app -->|"routes to workspace"| node_workspace
node_workspace -.->|"manages publication work"| node_publication_work
node_publication_work -->|"checks capabilities"| node_organization
node_publication_work -->|"reads records"| node_models
node_publication_work -->|"validates snapshots"| node_evidence_schema
node_publishing_service -.->|"writes records"| node_models
node_correction -->|"reads records"| node_models
node_accountability -.->|"uses records"| node_models
node_models -->|"validates publication data"| node_publication_schema
node_api_routes -.->|"dispatches work"| node_background_tasks

click node_extension "https://github.com/renzkirby/truthlens/blob/main/extension/src/App.jsx"
click node_web_app "https://github.com/renzkirby/truthlens/blob/main/frontend/frontend/src/App.jsx"
click node_api_client "https://github.com/renzkirby/truthlens/blob/main/frontend/frontend/src/utils/api.js"
click node_api_routes "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/views.py"
click node_input_processing "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/ocr_service.py"
click node_claim_matching "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/claim_matching.py"
click node_knowledge_reuse "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/knowledge_reuse_service.py"
click node_evidence_pipeline "https://github.com/renzkirby/truthlens/tree/main/backend/truthlens_backend/api/verification"
click node_verification_result "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/verification_intelligence_service.py"
click node_community_feed "https://github.com/renzkirby/truthlens/blob/main/frontend/frontend/src/Pages/CommunityFeed.jsx"
click node_thread_detail "https://github.com/renzkirby/truthlens/blob/main/frontend/frontend/src/Pages/ThreadDetailPage.jsx"
click node_evidence_review "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/evidence_review_service.py"
click node_moderation "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/moderation_service.py"
click node_trust "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/trust_service.py"
click node_assignment "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/verification_assignment_service.py"
click node_workspace "https://github.com/renzkirby/truthlens/blob/main/frontend/frontend/src/Pages/WorkspacePage.jsx"
click node_organization "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/organization_service.py"
click node_publication_work "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/publication_workflow_query_service.py"
click node_publishing_service "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/publishing_service.py"
click node_correction "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/factual_correction_query_service.py"
click node_accountability "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/accountability_service.py"
click node_models "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/models.py"
click node_evidence_schema "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/evidence_snapshot_schema.py"
click node_publication_schema "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/publication_snapshot_schema.py"
click node_background_tasks "https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/tasks.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_extension,node_web_app,node_api_client,node_browser_user,node_web_user toneBlue
class node_input_processing,node_claim_matching,node_knowledge_reuse,node_evidence_pipeline,node_verification_result toneAmber
class node_community_feed,node_thread_detail,node_evidence_review,node_moderation,node_trust,node_assignment toneMint
class node_workspace,node_organization,node_publication_work,node_publishing_service,node_correction,node_accountability toneRose
class node_api_routes,node_models,node_evidence_schema,node_publication_schema,node_background_tasks toneIndigo
```

## Components

### User clients

- [Browser extension](https://github.com/renzkirby/truthlens/blob/main/extension/src/App.jsx): `extension/src/App.jsx`
- [Web platform](https://github.com/renzkirby/truthlens/blob/main/frontend/frontend/src/App.jsx): `frontend/frontend/src/App.jsx`
- [API client](https://github.com/renzkirby/truthlens/blob/main/frontend/frontend/src/utils/api.js): `frontend/frontend/src/utils/api.js`

### Verification pipeline

- [Input processing](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/ocr_service.py): `backend/truthlens_backend/api/ocr_service.py`
- [Claim matching](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/claim_matching.py): `backend/truthlens_backend/api/claim_matching.py`
- [Knowledge reuse](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/knowledge_reuse_service.py): `backend/truthlens_backend/api/knowledge_reuse_service.py`
- [Evidence retrieval](https://github.com/renzkirby/truthlens/tree/main/backend/truthlens_backend/api/verification): `backend/truthlens_backend/api/verification`
- [AI analysis](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/verification_intelligence_service.py): `backend/truthlens_backend/api/verification_intelligence_service.py`

### Community review

- [Community feed](https://github.com/renzkirby/truthlens/blob/main/frontend/frontend/src/Pages/CommunityFeed.jsx): `frontend/frontend/src/Pages/CommunityFeed.jsx`
- [Threads and evidence](https://github.com/renzkirby/truthlens/blob/main/frontend/frontend/src/Pages/ThreadDetailPage.jsx): `frontend/frontend/src/Pages/ThreadDetailPage.jsx`
- [Evidence review](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/evidence_review_service.py): `backend/truthlens_backend/api/evidence_review_service.py`
- [Moderation](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/moderation_service.py): `backend/truthlens_backend/api/moderation_service.py`
- [Trust scores](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/trust_service.py): `backend/truthlens_backend/api/trust_service.py`
- [Verification assignment](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/verification_assignment_service.py): `backend/truthlens_backend/api/verification_assignment_service.py`

### Organizations and publishing

- [Organization workspace](https://github.com/renzkirby/truthlens/blob/main/frontend/frontend/src/Pages/WorkspacePage.jsx): `frontend/frontend/src/Pages/WorkspacePage.jsx`
- [Organization services](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/organization_service.py): `backend/truthlens_backend/api/organization_service.py`
- [Publication workflow](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/publication_workflow_query_service.py): `backend/truthlens_backend/api/publication_workflow_query_service.py`
- [Publishing](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/publishing_service.py): `backend/truthlens_backend/api/publishing_service.py`
- [Factual corrections](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/factual_correction_query_service.py): `backend/truthlens_backend/api/factual_correction_query_service.py`
- [Accountability](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/accountability_service.py): `backend/truthlens_backend/api/accountability_service.py`

### Shared backend

- [Backend API](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/views.py): `backend/truthlens_backend/api/views.py`
- [Domain records](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/models.py): `backend/truthlens_backend/api/models.py`
- [Evidence snapshots](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/evidence_snapshot_schema.py): `backend/truthlens_backend/api/evidence_snapshot_schema.py`
- [Publication snapshots](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/publication_snapshot_schema.py): `backend/truthlens_backend/api/publication_snapshot_schema.py`
- [Background tasks](https://github.com/renzkirby/truthlens/blob/main/backend/truthlens_backend/api/tasks.py): `backend/truthlens_backend/api/tasks.py`

### Other components

- **Browser user**
- **Web user**

## Connections

- Browser user → Browser extension: submits content
- Browser extension → Backend API: requests verification
- Web user → Web platform: uses platform
- Web platform → API client: calls API (evidence: `frontend/frontend/src/App.jsx`)
- API client → Backend API: sends requests
- Backend API → Input processing: processes inputs
- Input processing → Claim matching: matches claims
- Claim matching → Knowledge reuse: checks knowledge
- Knowledge reuse → Evidence retrieval: retrieves evidence
- Evidence retrieval → AI analysis: grounds analysis
- AI analysis → Threads and evidence: escalates uncertain claims
- Web platform → Community feed: routes to feed (evidence: `frontend/frontend/src/App.jsx`)
- Web platform → Threads and evidence: routes to threads (evidence: `frontend/frontend/src/App.jsx`)
- Threads and evidence → Evidence review: submits evidence
- Evidence review → Domain records: reads and writes (evidence: `backend/truthlens_backend/api/evidence_review_service.py`)
- Evidence review → Moderation: uses moderation (evidence: `backend/truthlens_backend/api/evidence_review_service.py`)
- Evidence review → Verification assignment: uses assignments (evidence: `backend/truthlens_backend/api/evidence_review_service.py`)
- Evidence review → Trust scores: updates reputation (evidence: `backend/truthlens_backend/api/evidence_review_service.py`)
- Web platform → Organization workspace: routes to workspace (evidence: `frontend/frontend/src/App.jsx`)
- Organization workspace → Publication workflow: manages publication work
- Publication workflow → Organization services: checks capabilities (evidence: `backend/truthlens_backend/api/publication_workflow_query_service.py`)
- Publication workflow → Domain records: reads records (evidence: `backend/truthlens_backend/api/publication_workflow_query_service.py`)
- Publication workflow → Evidence snapshots: validates snapshots (evidence: `backend/truthlens_backend/api/publication_workflow_query_service.py`)
- Publishing → Domain records: writes records
- Factual corrections → Domain records: reads records (evidence: `backend/truthlens_backend/api/factual_correction_query_service.py`)
- Accountability → Domain records: uses records
- Domain records → Publication snapshots: validates publication data (evidence: `backend/truthlens_backend/api/models.py`)
- Backend API → Background tasks: dispatches work
