# hoandng/trust_me_bro_extension architecture

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

- Interactive diagram: https://gitdiagram.com/hoandng/trust_me_bro_extension
- Repository: https://github.com/hoandng/trust_me_bro_extension

## Overview

Trust Me Bro is a browser extension and FastAPI service for checking selected Facebook text. The user selects a post, invokes analysis, and receives a verdict, explanation, confidence score, and sources in the side panel. Backend analysis extracts a claim, searches prior fact-checks and current web results, then assesses the gathered evidence and applies fact-check prioritization. The README documents the client flow and integrations; source excerpts show backend dispatch and service behavior. Extension-to-backend wiring is documented rather than excerpted.

Main entry points: [`backend/app/orchestrator/analysis_orchestrator.py`](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/orchestrator/analysis_orchestrator.py) (Analysis Orchestrator), [`backend/app/api/v1/analyze.py`](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/api/v1/analyze.py) (Analyze Endpoint), [`backend/app/main.py`](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/main.py) (FastAPI App), [`backend/app/services/gemini_service.py`](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/services/gemini_service.py) (Gemini Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Browser Extension"]
  node_content["Selection Capture<br/>[index.ts]"]
  node_adapter["Facebook Adapter"]
  node_button["Floating Button<br/>[floating-button.ts]"]
  node_worker["Background Worker<br/>[index.ts]"]
  node_panel["Results Panel<br/>[index.ts]"]
  node_exttypes["Extension Messages<br/>[types.ts]"]
end

subgraph group_api["API and Security"]
  node_app["FastAPI App<br/>[main.py]"]
  node_route["Analyze Endpoint<br/>[analyze.py]"]
  node_auth["API Key Checks<br/>[deps.py]"]
  node_limits["Rate Limits<br/>[rate_limit.py]"]
  node_config["Settings<br/>[config.py]"]
  node_logging["Logging Setup<br/>[logging.py]"]
end

subgraph group_analysis["Analysis Pipeline"]
  node_orchestrator["Analysis Orchestrator"]
  node_gemini["Gemini Analysis<br/>[gemini_service.py]"]
  node_prompts["Analysis Prompts<br/>[gemini_prompts.py]"]
end

subgraph group_integrations["Evidence Integrations"]
  node_factcheck["Fact Check Search"]
  node_tavily["Web Search<br/>[tavily_service.py]"]
end

subgraph group_contracts["Data Contracts"]
  node_context["Analysis Context<br/>[internal.py]"]
  node_response["Analysis Response<br/>[response.py]"]
  node_servicebase["Service Execution<br/>[base_service.py]"]
end

node_user(("Extension User"))
node_facebook["Facebook Page"]
node_googleapi["Google Fact Check API"]
node_tavilyapi["Tavily API"]
node_geminiapi["Gemini API"]

node_user -->|"selects text"| node_facebook
node_facebook -->|"provides selection"| node_content
node_content -->|"adapts platform"| node_adapter
node_content -->|"shows action"| node_button
node_user -->|"starts analysis"| node_button
node_worker -->|"sends analysis"| node_app
node_app -->|"routes requests"| node_route
node_app -->|"configures app"| node_config
node_app -->|"sets up logging"| node_logging
node_route -->|"requires key"| node_auth
node_auth -->|"checks quotas"| node_limits
node_auth -->|"reads settings"| node_config
node_route -->|"builds context"| node_context
node_route -->|"dispatches analysis"| node_orchestrator
node_route -->|"returns result"| node_response
node_orchestrator -->|"extracts claim"| node_gemini
node_orchestrator -->|"searches claims"| node_factcheck
node_orchestrator -->|"searches web"| node_tavily
node_orchestrator -->|"assesses evidence"| node_gemini
node_gemini -->|"uses prompts"| node_prompts
node_gemini -->|"requests analysis"| node_geminiapi
node_factcheck -->|"queries claims"| node_googleapi
node_tavily -->|"searches sources"| node_tavilyapi
node_orchestrator -->|"composes verdict"| node_response
node_factcheck -->|"uses safe execution"| node_servicebase
node_tavily -->|"uses safe execution"| node_servicebase
node_worker -->|"uses messages"| node_exttypes
node_panel -->|"uses response types"| node_exttypes
node_worker -->|"delivers results"| node_panel

click node_content "https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/content-script/index.ts"
click node_adapter "https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/content-script/adapters/facebook-adapter.ts"
click node_button "https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/content-script/ui/floating-button.ts"
click node_worker "https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/background/index.ts"
click node_panel "https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/sidepanel/index.ts"
click node_exttypes "https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/shared/types.ts"
click node_app "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/main.py"
click node_route "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/api/v1/analyze.py"
click node_auth "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/api/deps.py"
click node_limits "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/core/rate_limit.py"
click node_config "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/core/config.py"
click node_orchestrator "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/orchestrator/analysis_orchestrator.py"
click node_gemini "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/services/gemini_service.py"
click node_prompts "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/prompts/gemini_prompts.py"
click node_factcheck "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/services/factcheck_service.py"
click node_tavily "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/services/tavily_service.py"
click node_context "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/schemas/internal.py"
click node_response "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/schemas/response.py"
click node_servicebase "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/services/base_service.py"
click node_logging "https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/core/logging.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_content,node_adapter,node_button,node_worker,node_panel,node_exttypes,node_user toneBlue
class node_app,node_route,node_auth,node_limits,node_config,node_logging toneAmber
class node_orchestrator,node_gemini,node_prompts,node_googleapi,node_tavilyapi,node_geminiapi toneMint
class node_factcheck,node_tavily toneRose
class node_context,node_response,node_servicebase,node_facebook toneIndigo
```

## Components

### Browser Extension

- [Selection Capture](https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/content-script/index.ts): `extension/src/content-script/index.ts`
- [Facebook Adapter](https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/content-script/adapters/facebook-adapter.ts): `extension/src/content-script/adapters/facebook-adapter.ts`
- [Floating Button](https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/content-script/ui/floating-button.ts): `extension/src/content-script/ui/floating-button.ts`
- [Background Worker](https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/background/index.ts): `extension/src/background/index.ts`
- [Results Panel](https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/sidepanel/index.ts): `extension/src/sidepanel/index.ts`
- [Extension Messages](https://github.com/hoandng/trust_me_bro_extension/blob/main/extension/src/shared/types.ts): `extension/src/shared/types.ts`

### API and Security

- [FastAPI App](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/main.py): `backend/app/main.py`
- [Analyze Endpoint](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/api/v1/analyze.py): `backend/app/api/v1/analyze.py`
- [API Key Checks](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [Rate Limits](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/core/rate_limit.py): `backend/app/core/rate_limit.py`
- [Settings](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [Logging Setup](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/core/logging.py): `backend/app/core/logging.py`

### Analysis Pipeline

- [Analysis Orchestrator](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/orchestrator/analysis_orchestrator.py): `backend/app/orchestrator/analysis_orchestrator.py`
- [Gemini Analysis](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/services/gemini_service.py): `backend/app/services/gemini_service.py`
- [Analysis Prompts](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/prompts/gemini_prompts.py): `backend/app/prompts/gemini_prompts.py`

### Evidence Integrations

- [Fact Check Search](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/services/factcheck_service.py): `backend/app/services/factcheck_service.py`
- [Web Search](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/services/tavily_service.py): `backend/app/services/tavily_service.py`

### Data Contracts

- [Analysis Context](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/schemas/internal.py): `backend/app/schemas/internal.py`
- [Analysis Response](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/schemas/response.py): `backend/app/schemas/response.py`
- [Service Execution](https://github.com/hoandng/trust_me_bro_extension/blob/main/backend/app/services/base_service.py): `backend/app/services/base_service.py`

### Other components

- **Extension User**
- **Facebook Page**
- **Google Fact Check API**
- **Tavily API**
- **Gemini API**

## Connections

- Extension User → Facebook Page: selects text (evidence: `README.md`)
- Facebook Page → Selection Capture: provides selection (evidence: `README.md`)
- Selection Capture → Facebook Adapter: adapts platform (evidence: `extension/src/content-script/adapters/facebook-adapter.ts`)
- Selection Capture → Floating Button: shows action (evidence: `README.md`)
- Extension User → Floating Button: starts analysis (evidence: `README.md`)
- Background Worker → FastAPI App: sends analysis (evidence: `README.md`)
- FastAPI App → Analyze Endpoint: routes requests (evidence: `backend/app/main.py`)
- FastAPI App → Settings: configures app (evidence: `backend/app/main.py`)
- FastAPI App → Logging Setup: sets up logging (evidence: `backend/app/main.py`)
- Analyze Endpoint → API Key Checks: requires key (evidence: `backend/app/api/v1/analyze.py`)
- API Key Checks → Rate Limits: checks quotas (evidence: `backend/app/api/deps.py`)
- API Key Checks → Settings: reads settings (evidence: `backend/app/api/deps.py`)
- Analyze Endpoint → Analysis Context: builds context (evidence: `backend/app/api/v1/analyze.py`)
- Analyze Endpoint → Analysis Orchestrator: dispatches analysis (evidence: `backend/app/api/v1/analyze.py`)
- Analyze Endpoint → Analysis Response: returns result (evidence: `backend/app/api/v1/analyze.py`)
- Analysis Orchestrator → Gemini Analysis: extracts claim (evidence: `backend/app/orchestrator/analysis_orchestrator.py`)
- Analysis Orchestrator → Fact Check Search: searches claims (evidence: `backend/app/orchestrator/analysis_orchestrator.py`)
- Analysis Orchestrator → Web Search: searches web (evidence: `backend/app/orchestrator/analysis_orchestrator.py`)
- Analysis Orchestrator → Gemini Analysis: assesses evidence (evidence: `backend/app/orchestrator/analysis_orchestrator.py`)
- Gemini Analysis → Analysis Prompts: uses prompts (evidence: `backend/app/services/gemini_service.py`)
- Gemini Analysis → Gemini API: requests analysis (evidence: `backend/app/services/gemini_service.py`)
- Fact Check Search → Google Fact Check API: queries claims (evidence: `backend/app/services/factcheck_service.py`)
- Web Search → Tavily API: searches sources (evidence: `backend/app/services/tavily_service.py`)
- Analysis Orchestrator → Analysis Response: composes verdict (evidence: `backend/app/orchestrator/analysis_orchestrator.py`)
- Fact Check Search → Service Execution: uses safe execution (evidence: `backend/app/services/factcheck_service.py`)
- Web Search → Service Execution: uses safe execution (evidence: `backend/app/services/tavily_service.py`)
- Background Worker → Extension Messages: uses messages (evidence: `extension/src/background/index.ts`)
- Results Panel → Extension Messages: uses response types (evidence: `extension/src/sidepanel/index.ts`)
- Background Worker → Results Panel: delivers results (evidence: `README.md`)