# nikilesh-garip/echov2 architecture

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

- Interactive diagram: https://gitdiagram.com/nikilesh-garip/echov2
- Repository: https://github.com/nikilesh-garip/echov2

## Overview

Echo is a local acoustic hazard-detection and emergency-response system, with a web interface for mission control, accounts, and emergency contacts. Its core workflow captures microphone and speaker-loopback audio, classifies and temporally validates sounds, applies escalation policy, then alerts contacts through Telegram. The backend also provides authenticated account/contact APIs and real-time telemetry; the frontend presents product pages and dashboard access. The README is empty, so product capabilities are inferred from source descriptions and the feature-page excerpts; unsampled relationships are omitted where their call paths are not shown.

Main entry points: [`frontend/src/App.tsx`](https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/App.tsx) (Page routing), [`server.py`](https://github.com/nikilesh-garip/echov2/blob/main/server.py) (API and telemetry), [`yamnet_classifier.py`](https://github.com/nikilesh-garip/echov2/blob/main/yamnet_classifier.py) (Sound classifier), [`agent_orchestrator.py`](https://github.com/nikilesh-garip/echov2/blob/main/agent_orchestrator.py) (Escalation agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Acoustic detection"]
  node_capture["Audio capture<br/>[audio_ingestion.py]"]
  node_classifier["Sound classifier"]
  node_firewall["Audio firewall"]
end

subgraph group_response["Incident response"]
  node_policy_agent["Escalation agent"]
  node_telegram_dispatch["Telegram dispatch"]
end

subgraph group_backend["Backend services"]
  node_server["API and telemetry<br/>[server.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_database[("Accounts and contacts<br/>[database.py]")]
  node_dashboard["Mission dashboard<br/>[app.js]"]
end

subgraph group_frontend["Web experience"]
  node_web_app["Page routing<br/>[App.tsx]"]
  node_home["Product overview<br/>[Home.tsx]"]
  node_features["Feature showcase<br/>[Features.tsx]"]
  node_contacts_page["Emergency contacts"]
  node_about_page["About page<br/>[About.tsx]"]
  node_dashboard_link["Dashboard link<br/>[DashboardLink.tsx]"]
  node_navbar["Navigation<br/>[Navbar.tsx]"]
  node_telemetry_hook["Telemetry hook"]
end

node_resident(("User"))
node_audio_devices["Audio devices"]
node_model_service["YAMNet model"]
node_telegram_service["Telegram API"]

node_audio_devices -.->|"provides audio"| node_capture
node_capture -->|"classifies chunks"| node_classifier
node_classifier -.->|"runs inference"| node_model_service
node_classifier -.->|"filters echoes"| node_firewall
node_policy_agent -->|"dispatches alerts"| node_telegram_dispatch
node_telegram_dispatch -->|"sends alerts"| node_telegram_service
node_policy_agent -->|"fetches contacts"| node_database
node_server -->|"triggers dispatch"| node_policy_agent
node_server -->|"reads and writes"| node_database
node_server -->|"uses authentication"| node_auth
node_server -->|"handles pairing"| node_telegram_dispatch
node_resident -->|"browses"| node_web_app
node_web_app -->|"routes to"| node_home
node_web_app -->|"routes to"| node_features
node_web_app -->|"routes to"| node_contacts_page
node_web_app -->|"routes to"| node_about_page
node_web_app -->|"routes to"| node_dashboard_link
node_web_app -->|"renders"| node_navbar
node_navbar -->|"uses telemetry"| node_telemetry_hook
node_dashboard_link -.->|"links to dashboard"| node_dashboard

click node_capture "https://github.com/nikilesh-garip/echov2/blob/main/audio_ingestion.py"
click node_classifier "https://github.com/nikilesh-garip/echov2/blob/main/yamnet_classifier.py"
click node_firewall "https://github.com/nikilesh-garip/echov2/blob/main/acoustic_firewall.py"
click node_policy_agent "https://github.com/nikilesh-garip/echov2/blob/main/agent_orchestrator.py"
click node_telegram_dispatch "https://github.com/nikilesh-garip/echov2/blob/main/telegram_manager.py"
click node_server "https://github.com/nikilesh-garip/echov2/blob/main/server.py"
click node_auth "https://github.com/nikilesh-garip/echov2/blob/main/auth.py"
click node_database "https://github.com/nikilesh-garip/echov2/blob/main/database.py"
click node_dashboard "https://github.com/nikilesh-garip/echov2/blob/main/dashboard/app.js"
click node_web_app "https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/App.tsx"
click node_home "https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/pages/Home.tsx"
click node_features "https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/pages/Features.tsx"
click node_contacts_page "https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/pages/EmergencyContacts.tsx"
click node_about_page "https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/pages/About.tsx"
click node_dashboard_link "https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/pages/DashboardLink.tsx"
click node_navbar "https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/components/Navbar.tsx"
click node_telemetry_hook "https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/hooks/useEchoTelemetry.ts"

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_capture,node_classifier,node_firewall,node_resident toneBlue
class node_policy_agent,node_telegram_dispatch toneAmber
class node_server,node_auth,node_database,node_dashboard,node_telegram_service toneMint
class node_web_app,node_home,node_features,node_contacts_page,node_about_page,node_dashboard_link,node_navbar,node_telemetry_hook toneRose
class node_audio_devices,node_model_service toneIndigo
```

## Components

### Acoustic detection

- [Audio capture](https://github.com/nikilesh-garip/echov2/blob/main/audio_ingestion.py): `audio_ingestion.py`
- [Sound classifier](https://github.com/nikilesh-garip/echov2/blob/main/yamnet_classifier.py): `yamnet_classifier.py`
- [Audio firewall](https://github.com/nikilesh-garip/echov2/blob/main/acoustic_firewall.py): `acoustic_firewall.py`

### Incident response

- [Escalation agent](https://github.com/nikilesh-garip/echov2/blob/main/agent_orchestrator.py): `agent_orchestrator.py`
- [Telegram dispatch](https://github.com/nikilesh-garip/echov2/blob/main/telegram_manager.py): `telegram_manager.py`

### Backend services

- [API and telemetry](https://github.com/nikilesh-garip/echov2/blob/main/server.py): `server.py`
- [Authentication](https://github.com/nikilesh-garip/echov2/blob/main/auth.py): `auth.py`
- [Accounts and contacts](https://github.com/nikilesh-garip/echov2/blob/main/database.py): `database.py`
- [Mission dashboard](https://github.com/nikilesh-garip/echov2/blob/main/dashboard/app.js): `dashboard/app.js`

### Web experience

- [Page routing](https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Product overview](https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/pages/Home.tsx): `frontend/src/pages/Home.tsx`
- [Feature showcase](https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/pages/Features.tsx): `frontend/src/pages/Features.tsx`
- [Emergency contacts](https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/pages/EmergencyContacts.tsx): `frontend/src/pages/EmergencyContacts.tsx`
- [About page](https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/pages/About.tsx): `frontend/src/pages/About.tsx`
- [Dashboard link](https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/pages/DashboardLink.tsx): `frontend/src/pages/DashboardLink.tsx`
- [Navigation](https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/components/Navbar.tsx): `frontend/src/components/Navbar.tsx`
- [Telemetry hook](https://github.com/nikilesh-garip/echov2/blob/main/frontend/src/hooks/useEchoTelemetry.ts): `frontend/src/hooks/useEchoTelemetry.ts`

### Other components

- **User**
- **Audio devices**
- **YAMNet model**
- **Telegram API**

## Connections

- Audio devices → Audio capture: provides audio
- Audio capture → Sound classifier: classifies chunks (evidence: `audio_ingestion.py`)
- Sound classifier → YAMNet model: runs inference
- Sound classifier → Audio firewall: filters echoes (evidence: `acoustic_firewall.py`)
- Escalation agent → Telegram dispatch: dispatches alerts (evidence: `agent_orchestrator.py`)
- Telegram dispatch → Telegram API: sends alerts (evidence: `telegram_manager.py`)
- Escalation agent → Accounts and contacts: fetches contacts (evidence: `agent_orchestrator.py`)
- API and telemetry → Escalation agent: triggers dispatch (evidence: `server.py`)
- API and telemetry → Accounts and contacts: reads and writes (evidence: `server.py`)
- API and telemetry → Authentication: uses authentication (evidence: `server.py`)
- API and telemetry → Telegram dispatch: handles pairing (evidence: `server.py`)
- User → Page routing: browses (evidence: `frontend/src/App.tsx`)
- Page routing → Product overview: routes to (evidence: `frontend/src/App.tsx`)
- Page routing → Feature showcase: routes to (evidence: `frontend/src/App.tsx`)
- Page routing → Emergency contacts: routes to (evidence: `frontend/src/App.tsx`)
- Page routing → About page: routes to (evidence: `frontend/src/App.tsx`)
- Page routing → Dashboard link: routes to (evidence: `frontend/src/App.tsx`)
- Page routing → Navigation: renders (evidence: `frontend/src/App.tsx`)
- Navigation → Telemetry hook: uses telemetry (evidence: `frontend/src/components/Navbar.tsx`)
- Dashboard link → Mission dashboard: links to dashboard
