# regullar/shynai architecture

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

- Interactive diagram: https://gitdiagram.com/regullar/shynai
- Repository: https://github.com/regullar/shynai

## Overview

ShynAI is a Chrome-based fact-checking product: users check selected claims or scan an article, then inspect a structured verdict and auditable evidence. The extension sends requests to a FastAPI backend, which searches its Russian/Kazakh corpus and can use live search when local evidence is inadequate; evidence is quote-checked before a decisive result is returned. The extension also supports framing analysis, evidence-bounded chat, report highlights, export, and local history. Arrows are limited to README-documented flows and relationships shown in sampled source references; unsampled internals are not expanded.

Main entry points: [`apps/backend/app/main.py`](https://github.com/regullar/shynai/blob/main/apps/backend/app/main.py) (API routes), [`apps/extension/src/sidepanel/App.tsx`](https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/App.tsx) (Side panel), [`apps/extension/src/lib/api.ts`](https://github.com/regullar/shynai/blob/main/apps/extension/src/lib/api.ts) (API client), [`apps/extension/src/sidepanel/components/ResultView.tsx`](https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/components/ResultView.tsx) (Verdict and evidence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser extension"]
  node_content["Page extraction<br/>[content.ts]"]
  node_background["Extension background<br/>[background.ts]"]
  node_panel["Side panel<br/>[App.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_local_state[("Local preferences<br/>[storage.ts]")]
  node_result["Verdict and evidence<br/>[ResultView.tsx]"]
  node_audit["Page audit<br/>[PageAuditView.tsx]"]
  node_history["Local history<br/>[HistoryPanel.tsx]"]
end

subgraph group_backend["Fact-check backend"]
  node_backend_api["API routes<br/>[main.py]"]
  node_contracts["Request schemas<br/>[schemas.py]"]
  node_retrieval["Corpus retrieval<br/>[retrieval.py]"]
  node_verification["Verdict verification<br/>[verifier.py]"]
  node_live_fetch["Safe source fetch<br/>[scraper.py]"]
  node_report_store[("Scan reports<br/>[report_store.py]")]
end

subgraph group_evidence["Evidence sources"]
  node_corpus[("Local corpus<br/>[chunks.jsonl]")]
  node_ai_provider{{"AI search and models"}}
end

subgraph group_support["User support features"]
  node_chat["Evidence-bounded chat<br/>[chat.py]"]
  node_framing["Framing analysis"]
end

node_reader(("Reader"))
node_article["Article page"]

node_reader -->|"requests check"| node_panel
node_article -->|"provides text"| node_content
node_content -.->|"sends selection"| node_panel
node_reader -->|"starts page scan"| node_panel
node_panel -->|"calls"| node_api_client
node_background -->|"calls"| node_api_client
node_background -->|"reads and writes"| node_local_state
node_panel -->|"reads and writes"| node_local_state
node_api_client -->|"HTTP requests"| node_backend_api
node_backend_api -->|"uses schemas"| node_contracts
node_backend_api -->|"retrieves evidence"| node_retrieval
node_retrieval -->|"searches chunks"| node_corpus
node_backend_api -->|"verifies claim"| node_verification
node_verification -->|"uses local context"| node_retrieval
node_verification -->|"queries models"| node_ai_provider
node_verification -->|"validates live quote"| node_live_fetch
node_live_fetch -.->|"fetches public source"| node_article
node_backend_api -->|"stores scan report"| node_report_store
node_api_client -->|"fetches report"| node_report_store
node_backend_api -->|"handles chat"| node_chat
node_chat -.->|"generates answer"| node_ai_provider
node_backend_api -->|"returns result"| node_api_client
node_panel -->|"renders scan"| node_audit
node_panel -->|"renders verdict"| node_result
node_result -->|"shows analysis"| node_framing
node_result -.->|"asks evidence questions"| node_chat
node_result -.->|"records result"| node_history

click node_content "https://github.com/regullar/shynai/blob/main/apps/extension/src/content.ts"
click node_background "https://github.com/regullar/shynai/blob/main/apps/extension/src/background.ts"
click node_panel "https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/App.tsx"
click node_api_client "https://github.com/regullar/shynai/blob/main/apps/extension/src/lib/api.ts"
click node_local_state "https://github.com/regullar/shynai/blob/main/apps/extension/src/lib/storage.ts"
click node_backend_api "https://github.com/regullar/shynai/blob/main/apps/backend/app/main.py"
click node_contracts "https://github.com/regullar/shynai/blob/main/apps/backend/app/schemas.py"
click node_retrieval "https://github.com/regullar/shynai/blob/main/apps/backend/app/services/retrieval.py"
click node_corpus "https://github.com/regullar/shynai/blob/main/data/chunks.jsonl"
click node_verification "https://github.com/regullar/shynai/blob/main/apps/backend/app/services/verifier.py"
click node_live_fetch "https://github.com/regullar/shynai/blob/main/apps/backend/app/services/scraper.py"
click node_report_store "https://github.com/regullar/shynai/blob/main/apps/backend/app/services/report_store.py"
click node_chat "https://github.com/regullar/shynai/blob/main/apps/backend/app/services/chat.py"
click node_result "https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/components/ResultView.tsx"
click node_framing "https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/components/CognitiveBiasRadar.tsx"
click node_audit "https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/components/PageAuditView.tsx"
click node_history "https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/components/HistoryPanel.tsx"

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_background,node_panel,node_api_client,node_local_state,node_result,node_audit,node_history toneBlue
class node_backend_api,node_contracts,node_retrieval,node_verification,node_live_fetch,node_report_store toneAmber
class node_corpus,node_ai_provider toneMint
class node_chat,node_framing toneRose
class node_reader,node_article toneIndigo
```

## Components

### Browser extension

- [Page extraction](https://github.com/regullar/shynai/blob/main/apps/extension/src/content.ts): `apps/extension/src/content.ts`
- [Extension background](https://github.com/regullar/shynai/blob/main/apps/extension/src/background.ts): `apps/extension/src/background.ts`
- [Side panel](https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/App.tsx): `apps/extension/src/sidepanel/App.tsx`
- [API client](https://github.com/regullar/shynai/blob/main/apps/extension/src/lib/api.ts): `apps/extension/src/lib/api.ts`
- [Local preferences](https://github.com/regullar/shynai/blob/main/apps/extension/src/lib/storage.ts): `apps/extension/src/lib/storage.ts`
- [Verdict and evidence](https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/components/ResultView.tsx): `apps/extension/src/sidepanel/components/ResultView.tsx`
- [Page audit](https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/components/PageAuditView.tsx): `apps/extension/src/sidepanel/components/PageAuditView.tsx`
- [Local history](https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/components/HistoryPanel.tsx): `apps/extension/src/sidepanel/components/HistoryPanel.tsx`

### Fact-check backend

- [API routes](https://github.com/regullar/shynai/blob/main/apps/backend/app/main.py): `apps/backend/app/main.py`
- [Request schemas](https://github.com/regullar/shynai/blob/main/apps/backend/app/schemas.py): `apps/backend/app/schemas.py`
- [Corpus retrieval](https://github.com/regullar/shynai/blob/main/apps/backend/app/services/retrieval.py): `apps/backend/app/services/retrieval.py`
- [Verdict verification](https://github.com/regullar/shynai/blob/main/apps/backend/app/services/verifier.py): `apps/backend/app/services/verifier.py`
- [Safe source fetch](https://github.com/regullar/shynai/blob/main/apps/backend/app/services/scraper.py): `apps/backend/app/services/scraper.py`
- [Scan reports](https://github.com/regullar/shynai/blob/main/apps/backend/app/services/report_store.py): `apps/backend/app/services/report_store.py`

### Evidence sources

- [Local corpus](https://github.com/regullar/shynai/blob/main/data/chunks.jsonl): `data/chunks.jsonl`
- **AI search and models**

### User support features

- [Evidence-bounded chat](https://github.com/regullar/shynai/blob/main/apps/backend/app/services/chat.py): `apps/backend/app/services/chat.py`
- [Framing analysis](https://github.com/regullar/shynai/blob/main/apps/extension/src/sidepanel/components/CognitiveBiasRadar.tsx): `apps/extension/src/sidepanel/components/CognitiveBiasRadar.tsx`

### Other components

- **Reader**
- **Article page**

## Connections

- Reader → Side panel: requests check (evidence: `README.md`)
- Article page → Page extraction: provides text (evidence: `README.md`)
- Page extraction → Side panel: sends selection
- Reader → Side panel: starts page scan (evidence: `README.md`)
- Side panel → API client: calls (evidence: `apps/extension/src/sidepanel/App.tsx`)
- Extension background → API client: calls (evidence: `apps/extension/src/background.ts`)
- Extension background → Local preferences: reads and writes (evidence: `apps/extension/src/background.ts`)
- Side panel → Local preferences: reads and writes (evidence: `apps/extension/src/sidepanel/App.tsx`)
- API client → API routes: HTTP requests (evidence: `README.md`)
- API routes → Request schemas: uses schemas (evidence: `apps/backend/app/main.py`)
- API routes → Corpus retrieval: retrieves evidence (evidence: `apps/backend/app/main.py`)
- Corpus retrieval → Local corpus: searches chunks (evidence: `README.md`)
- API routes → Verdict verification: verifies claim (evidence: `apps/backend/app/main.py`)
- Verdict verification → Corpus retrieval: uses local context (evidence: `apps/backend/app/services/verifier.py`)
- Verdict verification → AI search and models: queries models (evidence: `apps/backend/app/services/verifier.py`)
- Verdict verification → Safe source fetch: validates live quote (evidence: `apps/backend/app/services/verifier.py`)
- Safe source fetch → Article page: fetches public source
- API routes → Scan reports: stores scan report (evidence: `apps/backend/app/main.py`)
- API client → Scan reports: fetches report (evidence: `README.md`)
- API routes → Evidence-bounded chat: handles chat (evidence: `apps/backend/app/main.py`)
- Evidence-bounded chat → AI search and models: generates answer
- API routes → API client: returns result (evidence: `README.md`)
- Side panel → Page audit: renders scan (evidence: `apps/extension/src/sidepanel/App.tsx`)
- Side panel → Verdict and evidence: renders verdict (evidence: `apps/extension/src/sidepanel/App.tsx`)
- Verdict and evidence → Framing analysis: shows analysis (evidence: `apps/extension/src/sidepanel/components/ResultView.tsx`)
- Verdict and evidence → Evidence-bounded chat: asks evidence questions
- Verdict and evidence → Local history: records result
