# sauti-yetu/sightra architecture

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

- Interactive diagram: https://gitdiagram.com/sauti-yetu/sightra
- Repository: https://github.com/sauti-yetu/sightra

## Overview

Sightra is an assistive Django web application for blind and low-vision users. Its principal workflow sends a browser camera frame to the navigation stream, runs object detection and hazard prioritization, generates safety-first Gemini narration, and returns audio feedback. Separate product branches provide image reading, account authentication, maps, volunteer connection, settings, privacy/legal controls, and PWA support. Some links are supported by the README rather than sampled implementation; those are cited as documented relationships.

Main entry points: [`sightra/sightra/urls.py`](https://github.com/sauti-yetu/sightra/blob/main/sightra/sightra/urls.py) (Django URL routing), [`sightra/apps/navigation/views.py`](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/navigation/views.py) (Navigation stream), [`sightra/apps/vision/tasks.py`](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/vision/tasks.py) (Frame pipeline), [`sightra/apps/core/tasks.py`](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/core/tasks.py) (Frame narration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and accounts"]
  node_auth_views["Auth flows<br/>[views.py]"]
  node_session["Session service<br/>[session_service.py]"]
end

subgraph group_assist["Scene assistance"]
  node_nav_stream["Navigation stream<br/>[views.py]"]
  node_vision_pipeline["Frame pipeline<br/>[tasks.py]"]
  node_detector["YOLO detection<br/>[services.py]"]
  node_priorities["Hazard prioritization<br/>[priorities.py]"]
  node_narration["Frame narration<br/>[tasks.py]"]
  node_gemini_service["Gemini analysis<br/>[services.py]"]
  node_audio["Speech feedback<br/>[services.py]"]
  node_reader_view["Reader endpoint<br/>[views.py]"]
  node_reader["Image reader<br/>[reader_service.py]"]
end

subgraph group_companions["Companion features"]
  node_map["Live map<br/>[views.py]"]
  node_volunteer["Volunteer connect<br/>[views.py]"]
end

subgraph group_governance["Privacy and settings"]
  node_settings["User settings<br/>[views.py]"]
  node_privacy_views["Privacy and legal<br/>[views.py]"]
  node_consent["Consent service<br/>[consent_service.py]"]
  node_privacy_store[("Privacy profiles<br/>[models.py]")]
  node_policies["Policy content<br/>[policies.py]"]
end

subgraph group_platform["Web experience"]
  node_routes["Django URL routing<br/>[urls.py]"]
  node_pwa["PWA assets<br/>[sw.js]"]
end

node_user(("Blind or low-vision user"))
node_browser(("Browser camera"))
node_supabase{{"Supabase auth API"}}
node_gemini_api{{"Google Gemini"}}

node_user -->|"uses camera"| node_browser
node_browser -->|"posts frame"| node_nav_stream
node_nav_stream -->|"processes frame"| node_vision_pipeline
node_vision_pipeline -->|"detects objects"| node_detector
node_detector -->|"ranks detections"| node_priorities
node_vision_pipeline -->|"builds hazard cues"| node_priorities
node_nav_stream -->|"requests analysis"| node_narration
node_narration -->|"runs vision first"| node_vision_pipeline
node_narration -->|"analyzes scene"| node_gemini_service
node_gemini_service -.->|"generates narration"| node_gemini_api
node_nav_stream -->|"returns audio feedback"| node_audio
node_reader_view -->|"analyzes image"| node_reader
node_reader -.->|"reads image"| node_gemini_api
node_user -->|"opens features"| node_routes
node_routes -->|"routes auth"| node_auth_views
node_auth_views -->|"sets session"| node_session
node_session -->|"refreshes tokens"| node_supabase
node_routes -->|"routes map"| node_map
node_routes -->|"routes connect"| node_volunteer
node_routes -->|"routes settings"| node_settings
node_routes -->|"routes legal"| node_privacy_views
node_privacy_views -->|"checks consent"| node_consent
node_consent -->|"reads and writes"| node_privacy_store
node_privacy_views -->|"serves policies"| node_policies
node_routes -->|"serves PWA"| node_pwa

click node_routes "https://github.com/sauti-yetu/sightra/blob/main/sightra/sightra/urls.py"
click node_auth_views "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/accounts/views.py"
click node_session "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/accounts/services/session_service.py"
click node_nav_stream "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/navigation/views.py"
click node_vision_pipeline "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/vision/tasks.py"
click node_detector "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/vision/services.py"
click node_priorities "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/vision/priorities.py"
click node_narration "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/core/tasks.py"
click node_gemini_service "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/core/services.py"
click node_audio "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/audio/services.py"
click node_reader_view "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/vision/views.py"
click node_reader "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/vision/reader_service.py"
click node_map "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/navigation/views.py"
click node_volunteer "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/volunteer/views.py"
click node_settings "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/settings/views.py"
click node_privacy_views "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/privacy/views.py"
click node_consent "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/privacy/services/consent_service.py"
click node_privacy_store "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/privacy/models.py"
click node_policies "https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/privacy/content/policies.py"
click node_pwa "https://github.com/sauti-yetu/sightra/blob/main/sightra/static/js/sw.js"

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_auth_views,node_session,node_user,node_browser toneBlue
class node_nav_stream,node_vision_pipeline,node_detector,node_priorities,node_narration,node_gemini_service,node_audio,node_reader_view,node_reader toneAmber
class node_map,node_volunteer,node_supabase toneMint
class node_settings,node_privacy_views,node_consent,node_privacy_store,node_policies toneRose
class node_routes,node_pwa,node_gemini_api toneIndigo
```

## Components

### Access and accounts

- [Auth flows](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/accounts/views.py): `sightra/apps/accounts/views.py`
- [Session service](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/accounts/services/session_service.py): `sightra/apps/accounts/services/session_service.py`

### Scene assistance

- [Navigation stream](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/navigation/views.py): `sightra/apps/navigation/views.py`
- [Frame pipeline](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/vision/tasks.py): `sightra/apps/vision/tasks.py`
- [YOLO detection](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/vision/services.py): `sightra/apps/vision/services.py`
- [Hazard prioritization](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/vision/priorities.py): `sightra/apps/vision/priorities.py`
- [Frame narration](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/core/tasks.py): `sightra/apps/core/tasks.py`
- [Gemini analysis](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/core/services.py): `sightra/apps/core/services.py`
- [Speech feedback](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/audio/services.py): `sightra/apps/audio/services.py`
- [Reader endpoint](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/vision/views.py): `sightra/apps/vision/views.py`
- [Image reader](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/vision/reader_service.py): `sightra/apps/vision/reader_service.py`

### Companion features

- [Live map](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/navigation/views.py): `sightra/apps/navigation/views.py`
- [Volunteer connect](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/volunteer/views.py): `sightra/apps/volunteer/views.py`

### Privacy and settings

- [User settings](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/settings/views.py): `sightra/apps/settings/views.py`
- [Privacy and legal](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/privacy/views.py): `sightra/apps/privacy/views.py`
- [Consent service](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/privacy/services/consent_service.py): `sightra/apps/privacy/services/consent_service.py`
- [Privacy profiles](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/privacy/models.py): `sightra/apps/privacy/models.py`
- [Policy content](https://github.com/sauti-yetu/sightra/blob/main/sightra/apps/privacy/content/policies.py): `sightra/apps/privacy/content/policies.py`

### Web experience

- [Django URL routing](https://github.com/sauti-yetu/sightra/blob/main/sightra/sightra/urls.py): `sightra/sightra/urls.py`
- [PWA assets](https://github.com/sauti-yetu/sightra/blob/main/sightra/static/js/sw.js): `sightra/static/js/sw.js`

### Other components

- **Blind or low-vision user**
- **Browser camera**
- **Supabase auth API**
- **Google Gemini**

## Connections

- Blind or low-vision user → Browser camera: uses camera (evidence: `README.md`)
- Browser camera → Navigation stream: posts frame (evidence: `README.md`)
- Navigation stream → Frame pipeline: processes frame (evidence: `sightra/apps/navigation/views.py`)
- Frame pipeline → YOLO detection: detects objects (evidence: `sightra/apps/vision/tasks.py`)
- YOLO detection → Hazard prioritization: ranks detections (evidence: `sightra/apps/vision/services.py`)
- Frame pipeline → Hazard prioritization: builds hazard cues (evidence: `sightra/apps/vision/tasks.py`)
- Navigation stream → Frame narration: requests analysis (evidence: `sightra/apps/navigation/views.py`)
- Frame narration → Frame pipeline: runs vision first (evidence: `sightra/apps/core/tasks.py`)
- Frame narration → Gemini analysis: analyzes scene (evidence: `sightra/apps/core/tasks.py`)
- Gemini analysis → Google Gemini: generates narration
- Navigation stream → Speech feedback: returns audio feedback (evidence: `README.md`)
- Reader endpoint → Image reader: analyzes image (evidence: `sightra/apps/vision/views.py`)
- Image reader → Google Gemini: reads image
- Blind or low-vision user → Django URL routing: opens features (evidence: `sightra/sightra/urls.py`)
- Django URL routing → Auth flows: routes auth (evidence: `sightra/sightra/urls.py`)
- Auth flows → Session service: sets session (evidence: `sightra/apps/accounts/views.py`)
- Session service → Supabase auth API: refreshes tokens (evidence: `sightra/apps/accounts/services/session_service.py`)
- Django URL routing → Live map: routes map (evidence: `sightra/sightra/urls.py`)
- Django URL routing → Volunteer connect: routes connect (evidence: `sightra/sightra/urls.py`)
- Django URL routing → User settings: routes settings (evidence: `sightra/sightra/urls.py`)
- Django URL routing → Privacy and legal: routes legal (evidence: `sightra/sightra/urls.py`)
- Privacy and legal → Consent service: checks consent (evidence: `sightra/apps/privacy/views.py`)
- Consent service → Privacy profiles: reads and writes (evidence: `sightra/apps/privacy/services/consent_service.py`)
- Privacy and legal → Policy content: serves policies (evidence: `sightra/apps/privacy/views.py`)
- Django URL routing → PWA assets: serves PWA (evidence: `sightra/sightra/urls.py`)