# kais-aljammal/truthnet architecture

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

- Interactive diagram: https://gitdiagram.com/kais-aljammal/truthnet
- Repository: https://github.com/kais-aljammal/truthnet

## Overview

TruthNet accepts a claim and returns a sourced, confidence-scored verdict. The main workflow passes through source gathering, parallel prosecution and defense, and final judgment; the API can stream progress and results to the React app. Separate branches provide account access, quotas, billing, and saved-check history. The README documents the agent and provider capabilities; sampled excerpts do not show all agent internals or every route implementation, so those links are limited to documented behavior.

Main entry points: [`backend/main.py`](https://github.com/kais-aljammal/truthnet/blob/main/backend/main.py) (HTTP API), [`frontend/app.jsx`](https://github.com/kais-aljammal/truthnet/blob/main/frontend/app.jsx) (Fact-check UI), [`backend/database.py`](https://github.com/kais-aljammal/truthnet/blob/main/backend/database.py) (Application database), [`frontend/router.jsx`](https://github.com/kais-aljammal/truthnet/blob/main/frontend/router.jsx) (Page router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_app["Fact-check UI<br/>[app.jsx]"]
  node_router["Page router<br/>[router.jsx]"]
  node_billing_ui["Billing page<br/>[billing.jsx]"]
  node_history_ui["History page<br/>[history.jsx]"]
end

subgraph group_analysis["Fact-check pipeline"]
  node_api["HTTP API<br/>[main.py]"]
  node_pipeline["Pipeline orchestration<br/>[pipeline.py]"]
  node_agents["Four AI agents<br/>[agents.py]"]
end

subgraph group_account["Accounts and usage"]
  node_auth["Authentication routes<br/>[auth_routes.py]"]
  node_auth_utils["Password utilities<br/>[auth_utils.py]"]
  node_quota["Quota and history service<br/>[quota_service.py]"]
  node_tiers["Tier definitions<br/>[tiers.py]"]
  node_rate["Rate limiting<br/>[rate_limit.py]"]
  node_db[("Application database<br/>[database.py]")]
end

subgraph group_commerce["Billing"]
  node_billing["Billing routes<br/>[billing_routes.py]"]
  node_webhooks["Stripe webhook handler<br/>[stripe_webhooks.py]"]
end

node_person(("Claim submitter"))
node_search["Google Search and Fact Check"]
node_gemini["Gemini provider"]
node_stripe["Stripe"]

node_person -->|"submits claim"| node_app
node_app -->|"posts claim"| node_api
node_api -->|"checks session"| node_auth
node_api -->|"checks rate"| node_rate
node_api -->|"checks quota"| node_quota
node_api -->|"runs analysis"| node_pipeline
node_pipeline -->|"invokes stages"| node_agents
node_agents -->|"requests generation"| node_gemini
node_agents -.->|"grounds research"| node_search
node_pipeline -->|"streams progress and verdict"| node_api
node_api -->|"sends SSE"| node_app
node_api -->|"records successful check"| node_quota
node_app -->|"refreshes quota"| node_api
node_router -->|"renders checker"| node_app
node_router -->|"renders billing"| node_billing_ui
node_router -->|"renders history"| node_history_ui
node_router -->|"loads session"| node_auth
node_auth -->|"hashes and verifies"| node_auth_utils
node_auth -->|"reads and writes users"| node_db
node_api -->|"reads and writes checks"| node_db
node_quota -->|"reads and updates usage"| node_db
node_quota -->|"gets tier limits"| node_tiers
node_billing_ui -->|"requests billing actions"| node_billing
node_billing -.->|"creates checkout or portal"| node_stripe
node_api -->|"dispatches webhook"| node_webhooks
node_webhooks -->|"verifies event"| node_stripe
node_webhooks -->|"updates subscriptions"| node_db
node_billing -->|"reads and updates billing"| node_db
node_history_ui -->|"loads check history"| node_api

click node_app "https://github.com/kais-aljammal/truthnet/blob/main/frontend/app.jsx"
click node_router "https://github.com/kais-aljammal/truthnet/blob/main/frontend/router.jsx"
click node_billing_ui "https://github.com/kais-aljammal/truthnet/blob/main/frontend/billing.jsx"
click node_history_ui "https://github.com/kais-aljammal/truthnet/blob/main/frontend/history.jsx"
click node_api "https://github.com/kais-aljammal/truthnet/blob/main/backend/main.py"
click node_pipeline "https://github.com/kais-aljammal/truthnet/blob/main/backend/pipeline.py"
click node_agents "https://github.com/kais-aljammal/truthnet/blob/main/backend/agents.py"
click node_auth "https://github.com/kais-aljammal/truthnet/blob/main/backend/auth_routes.py"
click node_auth_utils "https://github.com/kais-aljammal/truthnet/blob/main/backend/auth_utils.py"
click node_quota "https://github.com/kais-aljammal/truthnet/blob/main/backend/quota_service.py"
click node_tiers "https://github.com/kais-aljammal/truthnet/blob/main/backend/tiers.py"
click node_rate "https://github.com/kais-aljammal/truthnet/blob/main/backend/rate_limit.py"
click node_db "https://github.com/kais-aljammal/truthnet/blob/main/backend/database.py"
click node_billing "https://github.com/kais-aljammal/truthnet/blob/main/backend/billing_routes.py"
click node_webhooks "https://github.com/kais-aljammal/truthnet/blob/main/backend/stripe_webhooks.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_app,node_router,node_billing_ui,node_history_ui toneBlue
class node_api,node_pipeline,node_agents toneAmber
class node_auth,node_auth_utils,node_quota,node_tiers,node_rate,node_db toneMint
class node_billing,node_webhooks toneRose
class node_person,node_search,node_gemini,node_stripe toneIndigo
```

## Components

### Web experience

- [Fact-check UI](https://github.com/kais-aljammal/truthnet/blob/main/frontend/app.jsx): `frontend/app.jsx`
- [Page router](https://github.com/kais-aljammal/truthnet/blob/main/frontend/router.jsx): `frontend/router.jsx`
- [Billing page](https://github.com/kais-aljammal/truthnet/blob/main/frontend/billing.jsx): `frontend/billing.jsx`
- [History page](https://github.com/kais-aljammal/truthnet/blob/main/frontend/history.jsx): `frontend/history.jsx`

### Fact-check pipeline

- [HTTP API](https://github.com/kais-aljammal/truthnet/blob/main/backend/main.py): `backend/main.py`
- [Pipeline orchestration](https://github.com/kais-aljammal/truthnet/blob/main/backend/pipeline.py): `backend/pipeline.py`
- [Four AI agents](https://github.com/kais-aljammal/truthnet/blob/main/backend/agents.py): `backend/agents.py`

### Accounts and usage

- [Authentication routes](https://github.com/kais-aljammal/truthnet/blob/main/backend/auth_routes.py): `backend/auth_routes.py`
- [Password utilities](https://github.com/kais-aljammal/truthnet/blob/main/backend/auth_utils.py): `backend/auth_utils.py`
- [Quota and history service](https://github.com/kais-aljammal/truthnet/blob/main/backend/quota_service.py): `backend/quota_service.py`
- [Tier definitions](https://github.com/kais-aljammal/truthnet/blob/main/backend/tiers.py): `backend/tiers.py`
- [Rate limiting](https://github.com/kais-aljammal/truthnet/blob/main/backend/rate_limit.py): `backend/rate_limit.py`
- [Application database](https://github.com/kais-aljammal/truthnet/blob/main/backend/database.py): `backend/database.py`

### Billing

- [Billing routes](https://github.com/kais-aljammal/truthnet/blob/main/backend/billing_routes.py): `backend/billing_routes.py`
- [Stripe webhook handler](https://github.com/kais-aljammal/truthnet/blob/main/backend/stripe_webhooks.py): `backend/stripe_webhooks.py`

### Other components

- **Claim submitter**
- **Google Search and Fact Check**
- **Gemini provider**
- **Stripe**

## Connections

- Claim submitter → Fact-check UI: submits claim
- Fact-check UI → HTTP API: posts claim
- HTTP API → Authentication routes: checks session
- HTTP API → Rate limiting: checks rate
- HTTP API → Quota and history service: checks quota
- HTTP API → Pipeline orchestration: runs analysis
- Pipeline orchestration → Four AI agents: invokes stages
- Four AI agents → Gemini provider: requests generation
- Four AI agents → Google Search and Fact Check: grounds research
- Pipeline orchestration → HTTP API: streams progress and verdict
- HTTP API → Fact-check UI: sends SSE
- HTTP API → Quota and history service: records successful check
- Fact-check UI → HTTP API: refreshes quota
- Page router → Fact-check UI: renders checker
- Page router → Billing page: renders billing
- Page router → History page: renders history
- Page router → Authentication routes: loads session
- Authentication routes → Password utilities: hashes and verifies
- Authentication routes → Application database: reads and writes users
- HTTP API → Application database: reads and writes checks
- Quota and history service → Application database: reads and updates usage
- Quota and history service → Tier definitions: gets tier limits
- Billing page → Billing routes: requests billing actions
- Billing routes → Stripe: creates checkout or portal
- HTTP API → Stripe webhook handler: dispatches webhook
- Stripe webhook handler → Stripe: verifies event
- Stripe webhook handler → Application database: updates subscriptions
- Billing routes → Application database: reads and updates billing
- History page → HTTP API: loads check history