# kiranmgowda0105-max/dhruva_guardian_ architecture

> Architecture diagram of the GitHub repository kiranmgowda0105-max/dhruva_guardian_, 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/kiranmgowda0105-max/dhruva_guardian_
- Repository: https://github.com/kiranmgowda0105-max/dhruva_guardian_

## Overview

Dhruva appears to be a digital-arrest scam warning product: its web client listens to speech, scores transcripts against staged scam phrases, presents warnings and can send event reports or export evidence. The backend exposes event and alert endpoints and can notify paired Telegram chats. The tree also contains an Android app, but its runtime behavior is unsampled; its relationships are therefore shown only as unverified. The README provides no substantive capability or setup details.

Main entry points: [`web/src/App.tsx`](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/App.tsx) (Monitoring Interface), [`android/app/src/main/java/com/example/dhruvaguardian/GuardianService.kt`](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/android/app/src/main/java/com/example/dhruvaguardian/GuardianService.kt) (Guardian Service), [`web/src/engine/score.ts`](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/engine/score.ts) (Transcript Scorer), [`web/src/lib/api.ts`](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/lib/api.ts) (Event Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Monitoring"]
  node_webapp["Monitoring Interface<br/>[App.tsx]"]
  node_listener["Speech Listener"]
  node_gauge["Risk Gauge<br/>[RiskGauge.tsx]"]
  node_timeline["Scam Timeline<br/>[ScamTimeline.tsx]"]
  node_redalert["Red Alert<br/>[RedAlert.tsx]"]
  node_matched["Matched Phrases<br/>[MatchedPhrases.tsx]"]
  node_voice["Voice Warning<br/>[voice.ts]"]
  node_evidence["Evidence PDF<br/>[evidence.ts]"]
end

subgraph group_analysis["Scam Analysis"]
  node_scorer["Transcript Scorer<br/>[score.ts]"]
  node_rules["Stage Phrase Rules<br/>[rules.ts]"]
end

subgraph group_backend["Alert Backend"]
  node_api_client["Event Client<br/>[api.ts]"]
  node_api["HTTP API<br/>[main.py]"]
  node_models["API Models<br/>[models.py]"]
  node_state[("Event State<br/>[state.py]")]
  node_telegram["Telegram Notifier<br/>[telegram_bot.py]"]
end

subgraph group_android["Android App"]
  node_android_main["Android Interface<br/>[MainActivity.kt]"]
  node_guardian_service["Guardian Service<br/>[GuardianService.kt]"]
  node_accessibility["Accessibility Monitor"]
  node_boot["Boot Receiver<br/>[BootReceiver.kt]"]
  node_alert_activity["Alert Screen<br/>[AlertActivity.kt]"]
end

node_user(("User"))
node_telegram_service["Telegram"]

node_user -->|"uses"| node_webapp
node_webapp -->|"starts listening"| node_listener
node_webapp -->|"scores transcript"| node_scorer
node_scorer -->|"matches phrases"| node_rules
node_webapp -->|"renders score"| node_gauge
node_webapp -->|"renders stages"| node_timeline
node_webapp -->|"shows alert"| node_redalert
node_webapp -->|"renders matches"| node_matched
node_webapp -->|"speaks warning"| node_voice
node_webapp -->|"builds report"| node_evidence
node_webapp -->|"sends events"| node_api_client
node_api_client -.->|"posts event"| node_api
node_api -->|"notifies on red"| node_telegram
node_telegram -->|"sends messages"| node_telegram_service
node_user -.->|"uses"| node_android_main
node_android_main -.->|"starts monitoring"| node_guardian_service
node_guardian_service -.->|"uses service"| node_accessibility
node_boot -.->|"starts on boot"| node_guardian_service
node_guardian_service -.->|"shows alert"| node_alert_activity

click node_webapp "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/App.tsx"
click node_listener "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/hooks/useSpeechListener.ts"
click node_gauge "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/components/RiskGauge.tsx"
click node_timeline "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/components/ScamTimeline.tsx"
click node_redalert "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/components/RedAlert.tsx"
click node_matched "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/components/MatchedPhrases.tsx"
click node_voice "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/lib/voice.ts"
click node_evidence "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/lib/evidence.ts"
click node_scorer "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/engine/score.ts"
click node_rules "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/engine/rules.ts"
click node_api_client "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/lib/api.ts"
click node_api "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/api/main.py"
click node_models "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/api/models.py"
click node_state "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/api/state.py"
click node_telegram "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/api/telegram_bot.py"
click node_android_main "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/android/app/src/main/java/com/example/dhruvaguardian/MainActivity.kt"
click node_guardian_service "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/android/app/src/main/java/com/example/dhruvaguardian/GuardianService.kt"
click node_accessibility "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/android/app/src/main/java/com/example/dhruvaguardian/GuardianAccessibilityService.kt"
click node_boot "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/android/app/src/main/java/com/example/dhruvaguardian/BootReceiver.kt"
click node_alert_activity "https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/android/app/src/main/java/com/example/dhruvaguardian/AlertActivity.kt"

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_webapp,node_listener,node_gauge,node_timeline,node_redalert,node_matched,node_voice,node_evidence,node_user toneBlue
class node_scorer,node_rules toneAmber
class node_api_client,node_api,node_models,node_state,node_telegram toneMint
class node_android_main,node_guardian_service,node_accessibility,node_boot,node_alert_activity toneRose
class node_telegram_service toneIndigo
```

## Components

### Web Monitoring

- [Monitoring Interface](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Speech Listener](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/hooks/useSpeechListener.ts): `web/src/hooks/useSpeechListener.ts`
- [Risk Gauge](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/components/RiskGauge.tsx): `web/src/components/RiskGauge.tsx`
- [Scam Timeline](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/components/ScamTimeline.tsx): `web/src/components/ScamTimeline.tsx`
- [Red Alert](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/components/RedAlert.tsx): `web/src/components/RedAlert.tsx`
- [Matched Phrases](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/components/MatchedPhrases.tsx): `web/src/components/MatchedPhrases.tsx`
- [Voice Warning](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/lib/voice.ts): `web/src/lib/voice.ts`
- [Evidence PDF](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/lib/evidence.ts): `web/src/lib/evidence.ts`

### Scam Analysis

- [Transcript Scorer](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/engine/score.ts): `web/src/engine/score.ts`
- [Stage Phrase Rules](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/engine/rules.ts): `web/src/engine/rules.ts`

### Alert Backend

- [Event Client](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [HTTP API](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/api/main.py): `api/main.py`
- [API Models](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/api/models.py): `api/models.py`
- [Event State](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/api/state.py): `api/state.py`
- [Telegram Notifier](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/api/telegram_bot.py): `api/telegram_bot.py`

### Android App

- [Android Interface](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/android/app/src/main/java/com/example/dhruvaguardian/MainActivity.kt): `android/app/src/main/java/com/example/dhruvaguardian/MainActivity.kt`
- [Guardian Service](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/android/app/src/main/java/com/example/dhruvaguardian/GuardianService.kt): `android/app/src/main/java/com/example/dhruvaguardian/GuardianService.kt`
- [Accessibility Monitor](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/android/app/src/main/java/com/example/dhruvaguardian/GuardianAccessibilityService.kt): `android/app/src/main/java/com/example/dhruvaguardian/GuardianAccessibilityService.kt`
- [Boot Receiver](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/android/app/src/main/java/com/example/dhruvaguardian/BootReceiver.kt): `android/app/src/main/java/com/example/dhruvaguardian/BootReceiver.kt`
- [Alert Screen](https://github.com/kiranmgowda0105-max/dhruva_guardian_/blob/main/android/app/src/main/java/com/example/dhruvaguardian/AlertActivity.kt): `android/app/src/main/java/com/example/dhruvaguardian/AlertActivity.kt`

### Other components

- **User**
- **Telegram**

## Connections

- User → Monitoring Interface: uses
- Monitoring Interface → Speech Listener: starts listening (evidence: `web/src/App.tsx`)
- Monitoring Interface → Transcript Scorer: scores transcript (evidence: `web/src/App.tsx`)
- Transcript Scorer → Stage Phrase Rules: matches phrases (evidence: `web/src/engine/score.ts`)
- Monitoring Interface → Risk Gauge: renders score (evidence: `web/src/App.tsx`)
- Monitoring Interface → Scam Timeline: renders stages (evidence: `web/src/App.tsx`)
- Monitoring Interface → Red Alert: shows alert (evidence: `web/src/App.tsx`)
- Monitoring Interface → Matched Phrases: renders matches (evidence: `web/src/App.tsx`)
- Monitoring Interface → Voice Warning: speaks warning (evidence: `web/src/App.tsx`)
- Monitoring Interface → Evidence PDF: builds report (evidence: `web/src/App.tsx`)
- Monitoring Interface → Event Client: sends events (evidence: `web/src/App.tsx`)
- Event Client → HTTP API: posts event
- HTTP API → Telegram Notifier: notifies on red (evidence: `api/main.py`)
- Telegram Notifier → Telegram: sends messages (evidence: `api/telegram_bot.py`)
- User → Android Interface: uses
- Android Interface → Guardian Service: starts monitoring
- Guardian Service → Accessibility Monitor: uses service
- Boot Receiver → Guardian Service: starts on boot
- Guardian Service → Alert Screen: shows alert