# hack4innovation-2026/hack4innovation architecture

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

- Interactive diagram: https://gitdiagram.com/hack4innovation-2026/hack4innovation
- Repository: https://github.com/hack4innovation-2026/hack4innovation

## Overview

DrishtiAI is a voice- and camera-driven visual assistant for visually impaired users. The principal workflow starts with a user request, uses the Flutter voice copilot to route intent to signboard interpretation or person recognition, then delivers concise spoken feedback. Person recognition is also exposed through a FastAPI backend: it detects and distance-filters people, matches face embeddings against a local JSON store, and can optionally back up face images to Google Cloud Storage. README documents the frontend capabilities, but its Dart source is absent from the supplied tree, so those relationships are documented rather than source-verified.

Main entry points: [`backend/app/recognition.py`](https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/recognition.py) (Person Analysis & Registration), [`lib/services`](https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services) (Voice Copilot), [`backend/app/main.py`](https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/main.py) (Recognition API), [`backend/app/storage.py`](https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/storage.py) (Face Image Backup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter Assistant"]
  node_app["Flutter App<br/>[main.dart]"]
  node_voice["Voice Copilot"]
  node_intent["Intent Routing"]
  node_feedback["Speech &amp; Haptics"]
end

subgraph group_vision["Visual Understanding"]
  node_ocr["On-device OCR"]
  node_signboard["Signboard Interpretation"]
  node_person_client["Person Recognition Client"]
end

subgraph group_service["Recognition Backend"]
  node_backend_api["Recognition API<br/>[main.py]"]
  node_recognition["Person Analysis &amp; Registration<br/>[recognition.py]"]
  node_settings["Recognition Settings<br/>[config.py]"]
  node_schemas["API Schemas<br/>[schemas.py]"]
end

subgraph group_persistence["Recognition Data"]
  node_face_db[("Face Embedding Store<br/>[database.py]")]
  node_cloud_storage["Face Image Backup<br/>[storage.py]"]
end

node_user(("Visually Impaired User"))
node_gemini{{"Google Gemini"}}
node_gcs[("Google Cloud Storage")]

node_user -->|"speaks request"| node_voice
node_voice -->|"transcribes and routes"| node_intent
node_intent -->|"dispatches signboard queries"| node_signboard
node_intent -->|"dispatches person queries"| node_person_client
node_signboard -->|"uses extracted text"| node_ocr
node_signboard -->|"interprets image and text"| node_gemini
node_person_client -->|"sends frame requests"| node_backend_api
node_backend_api -->|"calls analysis or registration"| node_recognition
node_backend_api -->|"validates and returns"| node_schemas
node_recognition -->|"uses thresholds and paths"| node_settings
node_recognition -->|"matches or adds embeddings"| node_face_db
node_recognition -->|"uploads registered face"| node_cloud_storage
node_cloud_storage -->|"uploads image"| node_gcs
node_voice -->|"speaks prioritized response"| node_feedback
node_feedback -->|"returns spoken and haptic feedback"| node_user
node_cloud_storage -.->|"optionally backs up"| node_gcs

click node_app "https://github.com/hack4innovation-2026/hack4innovation/blob/main/lib/main.dart"
click node_voice "https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services"
click node_intent "https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services"
click node_feedback "https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services"
click node_ocr "https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services"
click node_signboard "https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services"
click node_person_client "https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services"
click node_backend_api "https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/main.py"
click node_recognition "https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/recognition.py"
click node_settings "https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/config.py"
click node_schemas "https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/schemas.py"
click node_face_db "https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/database.py"
click node_cloud_storage "https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/storage.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_app,node_voice,node_intent,node_feedback,node_user toneBlue
class node_ocr,node_signboard,node_person_client,node_gcs toneAmber
class node_backend_api,node_recognition,node_settings,node_schemas toneMint
class node_face_db,node_cloud_storage toneRose
class node_gemini toneIndigo
```

## Components

### Flutter Assistant

- [Flutter App](https://github.com/hack4innovation-2026/hack4innovation/blob/main/lib/main.dart): `lib/main.dart`
- [Voice Copilot](https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services): `lib/services`
- [Intent Routing](https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services): `lib/services`
- [Speech & Haptics](https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services): `lib/services`

### Visual Understanding

- [On-device OCR](https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services): `lib/services`
- [Signboard Interpretation](https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services): `lib/services`
- [Person Recognition Client](https://github.com/hack4innovation-2026/hack4innovation/tree/main/lib/services): `lib/services`

### Recognition Backend

- [Recognition API](https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/main.py): `backend/app/main.py`
- [Person Analysis & Registration](https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/recognition.py): `backend/app/recognition.py`
- [Recognition Settings](https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/config.py): `backend/app/config.py`
- [API Schemas](https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/schemas.py): `backend/app/schemas.py`

### Recognition Data

- [Face Embedding Store](https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/database.py): `backend/app/database.py`
- [Face Image Backup](https://github.com/hack4innovation-2026/hack4innovation/blob/main/backend/app/storage.py): `backend/app/storage.py`

### Other components

- **Visually Impaired User**
- **Google Gemini**
- **Google Cloud Storage**

## Connections

- Visually Impaired User → Voice Copilot: speaks request (evidence: `README.md`)
- Voice Copilot → Intent Routing: transcribes and routes (evidence: `README.md`)
- Intent Routing → Signboard Interpretation: dispatches signboard queries (evidence: `README.md`)
- Intent Routing → Person Recognition Client: dispatches person queries (evidence: `README.md`)
- Signboard Interpretation → On-device OCR: uses extracted text (evidence: `README.md`)
- Signboard Interpretation → Google Gemini: interprets image and text (evidence: `README.md`)
- Person Recognition Client → Recognition API: sends frame requests (evidence: `README.md`)
- Recognition API → Person Analysis & Registration: calls analysis or registration (evidence: `backend/app/main.py`)
- Recognition API → API Schemas: validates and returns (evidence: `backend/app/main.py`)
- Person Analysis & Registration → Recognition Settings: uses thresholds and paths (evidence: `backend/app/recognition.py`)
- Person Analysis & Registration → Face Embedding Store: matches or adds embeddings (evidence: `backend/app/recognition.py`)
- Person Analysis & Registration → Face Image Backup: uploads registered face (evidence: `backend/app/recognition.py`)
- Face Image Backup → Google Cloud Storage: uploads image (evidence: `backend/app/storage.py`)
- Voice Copilot → Speech & Haptics: speaks prioritized response (evidence: `README.md`)
- Speech & Haptics → Visually Impaired User: returns spoken and haptic feedback (evidence: `README.md`)
- Face Image Backup → Google Cloud Storage: optionally backs up (evidence: `README.md`)
