# bakulya014-dot/tumar-ai architecture

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

- Interactive diagram: https://gitdiagram.com/bakulya014-dot/tumar-ai
- Repository: https://github.com/bakulya014-dot/tumar-ai

## Overview

Tumar.AI is a multilingual cybersecurity assistant. In the main user workflow, a person submits a message, URL, email, or image through the Streamlit app; the Trust Engine routes it to an analyzer, which produces a shared TrustReport that the UI renders and may retain in session history. Other product branches include breach checks, dashboard/history, optional sample contributions, and a REST API with customer-key management. The README documents additional password-health and API capabilities; their implementation is not fully represented in the sampled excerpts, so those links are documented rather than source-verified.

Main entry points: [`services/trust_engine.py`](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/trust_engine.py) (Trust Engine), [`views`](https://github.com/bakulya014-dot/tumar-ai/tree/main/views) (Analysis pages), [`api/main.py`](https://github.com/bakulya014-dot/tumar-ai/blob/main/api/main.py) (REST API), [`services/scam_analysis.py`](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/scam_analysis.py) (Scam analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User experience"]
  node_streamlit["Streamlit app<br/>[app.py]"]
  node_feature_pages["Analysis pages"]
  node_dashboard["Dashboard<br/>[home.py]"]
  node_translations["Translations<br/>[__init__.py]"]
  node_ui_components["UI components<br/>[components.py]"]
end

subgraph group_analysis["Analysis platform"]
  node_trust_engine["Trust Engine<br/>[trust_engine.py]"]
  node_scam["Scam analysis<br/>[scam_analysis.py]"]
  node_heuristics["Deterministic scanner<br/>[heuristics.py]"]
  node_url_scan["URL scanner<br/>[url_scanner.py]"]
  node_breach["Breach checker<br/>[breach_checker.py]"]
  node_vision["Image analysis<br/>[vision_analysis.py]"]
  node_password["Password health"]
  node_report["TrustReport schema<br/>[trust_report.py]"]
end

subgraph group_providers["AI integrations"]
  node_provider_registry["Provider registry<br/>[__init__.py]"]
  node_gemini_client["Gemini client<br/>[gemini_client.py]"]
  node_compatible_provider["Compatible providers"]
end

subgraph group_api["REST and contributions"]
  node_contribution_ui["Contribution consent<br/>[contribution_ui.py]"]
  node_rest_api["REST API<br/>[main.py]"]
  node_key_management["Customer keys<br/>[keys.py]"]
  node_keystore[("Key store<br/>[keystore.py]")]
  node_corpus_store[("Detection corpus<br/>[corpus_store.py]")]
end

subgraph group_state["Reports and history"]
  node_report_view["Report renderer<br/>[report_view.py]"]
  node_report_store["Session report history<br/>[report_store.py]"]
end

node_person(("User"))
node_ai_service{{"AI providers"}}
node_hibp{{"Have I Been Pwned"}}

node_person -->|"submits checks"| node_streamlit
node_streamlit -->|"routes to"| node_feature_pages
node_feature_pages -->|"analyzes subjects"| node_trust_engine
node_feature_pages -->|"checks emails"| node_breach
node_feature_pages -->|"analyzes images"| node_vision
node_trust_engine -->|"dispatches to"| node_scam
node_trust_engine -->|"dispatches to"| node_url_scan
node_trust_engine -->|"dispatches to"| node_breach
node_trust_engine -->|"dispatches to"| node_vision
node_trust_engine -.->|"supports declared kind"| node_password
node_scam -->|"scans message"| node_heuristics
node_scam -->|"requests provider"| node_provider_registry
node_url_scan -->|"requests analysis"| node_gemini_client
node_vision -->|"requests vision"| node_provider_registry
node_provider_registry -->|"builds provider"| node_compatible_provider
node_provider_registry -->|"builds Gemini"| node_gemini_client
node_gemini_client -->|"sends prompts"| node_ai_service
node_compatible_provider -->|"sends requests"| node_ai_service
node_scam -->|"creates report"| node_report
node_trust_engine -->|"returns report"| node_report
node_feature_pages -->|"renders report"| node_report_view
node_report_view -->|"composes components"| node_ui_components
node_report_view -->|"translates labels"| node_translations
node_feature_pages -->|"stores reports"| node_report_store
node_dashboard -->|"summarizes history"| node_report_store
node_feature_pages -->|"offers contribution"| node_contribution_ui
node_contribution_ui -->|"stores samples"| node_corpus_store
node_contribution_ui -.->|"optionally submits"| node_rest_api
node_person -->|"sends API request"| node_rest_api
node_rest_api -->|"analyzes request"| node_trust_engine
node_rest_api -->|"handles contributions"| node_corpus_store
node_key_management -->|"manages keys"| node_keystore
node_rest_api -->|"checks and meters"| node_keystore
node_breach -.->|"checks range"| node_hibp
node_password -.->|"checks hash prefix"| node_hibp

click node_streamlit "https://github.com/bakulya014-dot/tumar-ai/blob/main/app.py"
click node_feature_pages "https://github.com/bakulya014-dot/tumar-ai/tree/main/views"
click node_dashboard "https://github.com/bakulya014-dot/tumar-ai/blob/main/views/home.py"
click node_translations "https://github.com/bakulya014-dot/tumar-ai/blob/main/i18n/__init__.py"
click node_ui_components "https://github.com/bakulya014-dot/tumar-ai/blob/main/components.py"
click node_trust_engine "https://github.com/bakulya014-dot/tumar-ai/blob/main/services/trust_engine.py"
click node_scam "https://github.com/bakulya014-dot/tumar-ai/blob/main/services/scam_analysis.py"
click node_heuristics "https://github.com/bakulya014-dot/tumar-ai/blob/main/services/heuristics.py"
click node_url_scan "https://github.com/bakulya014-dot/tumar-ai/blob/main/services/url_scanner.py"
click node_breach "https://github.com/bakulya014-dot/tumar-ai/blob/main/services/breach_checker.py"
click node_vision "https://github.com/bakulya014-dot/tumar-ai/blob/main/services/vision_analysis.py"
click node_password "https://github.com/bakulya014-dot/tumar-ai/tree/main/services"
click node_report "https://github.com/bakulya014-dot/tumar-ai/blob/main/services/trust_report.py"
click node_provider_registry "https://github.com/bakulya014-dot/tumar-ai/blob/main/services/providers/__init__.py"
click node_gemini_client "https://github.com/bakulya014-dot/tumar-ai/blob/main/services/gemini_client.py"
click node_compatible_provider "https://github.com/bakulya014-dot/tumar-ai/blob/main/services/providers/openai_compatible.py"
click node_report_view "https://github.com/bakulya014-dot/tumar-ai/blob/main/report_view.py"
click node_report_store "https://github.com/bakulya014-dot/tumar-ai/blob/main/report_store.py"
click node_contribution_ui "https://github.com/bakulya014-dot/tumar-ai/blob/main/contribution_ui.py"
click node_rest_api "https://github.com/bakulya014-dot/tumar-ai/blob/main/api/main.py"
click node_key_management "https://github.com/bakulya014-dot/tumar-ai/blob/main/api/keys.py"
click node_keystore "https://github.com/bakulya014-dot/tumar-ai/blob/main/api/keystore.py"
click node_corpus_store "https://github.com/bakulya014-dot/tumar-ai/blob/main/api/corpus_store.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_streamlit,node_feature_pages,node_dashboard,node_translations,node_ui_components,node_person toneBlue
class node_trust_engine,node_scam,node_heuristics,node_url_scan,node_breach,node_vision,node_password,node_report toneAmber
class node_provider_registry,node_gemini_client,node_compatible_provider toneMint
class node_contribution_ui,node_rest_api,node_key_management,node_keystore,node_corpus_store toneRose
class node_report_view,node_report_store,node_ai_service,node_hibp toneIndigo
```

## Components

### User experience

- [Streamlit app](https://github.com/bakulya014-dot/tumar-ai/blob/main/app.py): `app.py`
- [Analysis pages](https://github.com/bakulya014-dot/tumar-ai/tree/main/views): `views`
- [Dashboard](https://github.com/bakulya014-dot/tumar-ai/blob/main/views/home.py): `views/home.py`
- [Translations](https://github.com/bakulya014-dot/tumar-ai/blob/main/i18n/__init__.py): `i18n/__init__.py`
- [UI components](https://github.com/bakulya014-dot/tumar-ai/blob/main/components.py): `components.py`

### Analysis platform

- [Trust Engine](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/trust_engine.py): `services/trust_engine.py`
- [Scam analysis](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/scam_analysis.py): `services/scam_analysis.py`
- [Deterministic scanner](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/heuristics.py): `services/heuristics.py`
- [URL scanner](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/url_scanner.py): `services/url_scanner.py`
- [Breach checker](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/breach_checker.py): `services/breach_checker.py`
- [Image analysis](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/vision_analysis.py): `services/vision_analysis.py`
- [Password health](https://github.com/bakulya014-dot/tumar-ai/tree/main/services): `services`
- [TrustReport schema](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/trust_report.py): `services/trust_report.py`

### AI integrations

- [Provider registry](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/providers/__init__.py): `services/providers/__init__.py`
- [Gemini client](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/gemini_client.py): `services/gemini_client.py`
- [Compatible providers](https://github.com/bakulya014-dot/tumar-ai/blob/main/services/providers/openai_compatible.py): `services/providers/openai_compatible.py`

### REST and contributions

- [Contribution consent](https://github.com/bakulya014-dot/tumar-ai/blob/main/contribution_ui.py): `contribution_ui.py`
- [REST API](https://github.com/bakulya014-dot/tumar-ai/blob/main/api/main.py): `api/main.py`
- [Customer keys](https://github.com/bakulya014-dot/tumar-ai/blob/main/api/keys.py): `api/keys.py`
- [Key store](https://github.com/bakulya014-dot/tumar-ai/blob/main/api/keystore.py): `api/keystore.py`
- [Detection corpus](https://github.com/bakulya014-dot/tumar-ai/blob/main/api/corpus_store.py): `api/corpus_store.py`

### Reports and history

- [Report renderer](https://github.com/bakulya014-dot/tumar-ai/blob/main/report_view.py): `report_view.py`
- [Session report history](https://github.com/bakulya014-dot/tumar-ai/blob/main/report_store.py): `report_store.py`

### Other components

- **User**
- **AI providers**
- **Have I Been Pwned**

## Connections

- User → Streamlit app: submits checks
- Streamlit app → Analysis pages: routes to
- Analysis pages → Trust Engine: analyzes subjects (evidence: `views/home.py`)
- Analysis pages → Breach checker: checks emails (evidence: `views/breach_checker.py`)
- Analysis pages → Image analysis: analyzes images (evidence: `views/image_scanner.py`)
- Trust Engine → Scam analysis: dispatches to (evidence: `services/trust_engine.py`)
- Trust Engine → URL scanner: dispatches to (evidence: `services/trust_engine.py`)
- Trust Engine → Breach checker: dispatches to (evidence: `services/trust_engine.py`)
- Trust Engine → Image analysis: dispatches to (evidence: `services/trust_engine.py`)
- Trust Engine → Password health: supports declared kind (evidence: `services/trust_engine.py`)
- Scam analysis → Deterministic scanner: scans message (evidence: `services/scam_analysis.py`)
- Scam analysis → Provider registry: requests provider (evidence: `services/scam_analysis.py`)
- URL scanner → Gemini client: requests analysis (evidence: `services/url_scanner.py`)
- Image analysis → Provider registry: requests vision (evidence: `services/vision_analysis.py`)
- Provider registry → Compatible providers: builds provider (evidence: `services/providers/__init__.py`)
- Provider registry → Gemini client: builds Gemini
- Gemini client → AI providers: sends prompts (evidence: `services/gemini_client.py`)
- Compatible providers → AI providers: sends requests (evidence: `services/providers/openai_compatible.py`)
- Scam analysis → TrustReport schema: creates report (evidence: `services/trust_report.py`)
- Trust Engine → TrustReport schema: returns report (evidence: `services/trust_engine.py`)
- Analysis pages → Report renderer: renders report (evidence: `views/image_scanner.py`)
- Report renderer → UI components: composes components (evidence: `report_view.py`)
- Report renderer → Translations: translates labels (evidence: `report_view.py`)
- Analysis pages → Session report history: stores reports (evidence: `views/home.py`)
- Dashboard → Session report history: summarizes history (evidence: `views/home.py`)
- Analysis pages → Contribution consent: offers contribution (evidence: `views/home.py`)
- Contribution consent → Detection corpus: stores samples (evidence: `contribution_ui.py`)
- Contribution consent → REST API: optionally submits (evidence: `contribution_ui.py`)
- User → REST API: sends API request
- REST API → Trust Engine: analyzes request (evidence: `api/main.py`)
- REST API → Detection corpus: handles contributions (evidence: `api/main.py`)
- Customer keys → Key store: manages keys (evidence: `api/keys.py`)
- REST API → Key store: checks and meters (evidence: `api/main.py`)
- Breach checker → Have I Been Pwned: checks range
- Password health → Have I Been Pwned: checks hash prefix
