# vishnu-tppr/terax-ai architecture

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

- Interactive diagram: https://gitdiagram.com/vishnu-tppr/terax-ai
- Repository: https://github.com/vishnu-tppr/terax-ai

## Overview

Terax AI is documented as a cross-platform personal-safety app: a voice, gesture, or distress trigger starts emergency recording/location sharing and alerts trusted contacts. The available runtime evidence chiefly covers two backend surfaces: a Node SMS/location API and a FastAPI authentication, profile, contact, and incident API. The Flutter application source is absent from the supplied tree, so its documented capabilities are represented without invented implementation paths or backend call links; wiring between the two backends is also not established.

Main entry points: [`backend-python/app/main.py`](https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/main.py) (FastAPI app), [`backend/server.js`](https://github.com/vishnu-tppr/terax-ai/blob/main/backend/server.js) (SMS dispatch), [`backend-python/app/supabase_helpers.py`](https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/supabase_helpers.py) (Supabase helpers), [`backend-python/app/routers/auth.py`](https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/routers/auth.py) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Safety app"]
  node_flutter["Flutter client"]
  node_triggers["Voice and SOS triggers"]
  node_safety["Recording and tracking"]
  node_protection["Background protection"]
end

subgraph group_alerts["Alert API"]
  node_node_api["Node API<br/>[server.js]"]
  node_sms_route["SMS dispatch<br/>[server.js]"]
  node_location_route["Location sharing<br/>[server.js]"]
  node_message_state[("SMS history and status<br/>[server.js]")]
end

subgraph group_python["Account API"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_profiles["Profiles<br/>[profile.py]"]
  node_contacts["Contacts<br/>[contacts.py]"]
  node_incidents["Incidents<br/>[incidents.py]"]
  node_supabase_helpers["Supabase helpers"]
end

subgraph group_external["External services"]
  node_twilio{{"Twilio"}}
  node_supabase[("Supabase")]
end

node_person(("App user"))
node_trusted_contacts(("Trusted contacts"))

node_person -->|"uses"| node_flutter
node_flutter -->|"activates"| node_triggers
node_triggers -->|"starts"| node_safety
node_triggers -->|"starts"| node_protection
node_node_api -->|"routes"| node_sms_route
node_node_api -->|"routes"| node_location_route
node_sms_route -->|"sends SMS"| node_twilio
node_location_route -->|"sends SMS"| node_twilio
node_sms_route -->|"writes history"| node_message_state
node_message_state -->|"serves status"| node_sms_route
node_twilio -->|"posts webhook"| node_node_api
node_fastapi -->|"includes router"| node_auth
node_fastapi -->|"includes router"| node_profiles
node_fastapi -->|"includes router"| node_contacts
node_fastapi -->|"includes router"| node_incidents
node_fastapi -->|"checks health"| node_supabase_helpers
node_auth -->|"calls helpers"| node_supabase_helpers
node_supabase_helpers -->|"accesses"| node_supabase
node_safety -.->|"notifies"| node_trusted_contacts

click node_node_api "https://github.com/vishnu-tppr/terax-ai/blob/main/backend/server.js"
click node_sms_route "https://github.com/vishnu-tppr/terax-ai/blob/main/backend/server.js"
click node_location_route "https://github.com/vishnu-tppr/terax-ai/blob/main/backend/server.js"
click node_message_state "https://github.com/vishnu-tppr/terax-ai/blob/main/backend/server.js"
click node_fastapi "https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/main.py"
click node_auth "https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/routers/auth.py"
click node_profiles "https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/routers/profile.py"
click node_contacts "https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/routers/contacts.py"
click node_incidents "https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/routers/incidents.py"
click node_supabase_helpers "https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/supabase_helpers.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_flutter,node_triggers,node_safety,node_protection,node_person toneBlue
class node_node_api,node_sms_route,node_location_route,node_message_state toneAmber
class node_fastapi,node_auth,node_profiles,node_contacts,node_incidents,node_supabase_helpers toneMint
class node_twilio,node_supabase toneRose
class node_trusted_contacts toneIndigo
```

## Components

### Safety app

- **Flutter client**
- **Voice and SOS triggers**
- **Recording and tracking**
- **Background protection**

### Alert API

- [Node API](https://github.com/vishnu-tppr/terax-ai/blob/main/backend/server.js): `backend/server.js`
- [SMS dispatch](https://github.com/vishnu-tppr/terax-ai/blob/main/backend/server.js): `backend/server.js`
- [Location sharing](https://github.com/vishnu-tppr/terax-ai/blob/main/backend/server.js): `backend/server.js`
- [SMS history and status](https://github.com/vishnu-tppr/terax-ai/blob/main/backend/server.js): `backend/server.js`

### Account API

- [FastAPI app](https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/main.py): `backend-python/app/main.py`
- [Authentication](https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/routers/auth.py): `backend-python/app/routers/auth.py`
- [Profiles](https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/routers/profile.py): `backend-python/app/routers/profile.py`
- [Contacts](https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/routers/contacts.py): `backend-python/app/routers/contacts.py`
- [Incidents](https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/routers/incidents.py): `backend-python/app/routers/incidents.py`
- [Supabase helpers](https://github.com/vishnu-tppr/terax-ai/blob/main/backend-python/app/supabase_helpers.py): `backend-python/app/supabase_helpers.py`

### External services

- **Twilio**
- **Supabase**

### Other components

- **App user**
- **Trusted contacts**

## Connections

- App user → Flutter client: uses
- Flutter client → Voice and SOS triggers: activates
- Voice and SOS triggers → Recording and tracking: starts
- Voice and SOS triggers → Background protection: starts
- Node API → SMS dispatch: routes
- Node API → Location sharing: routes
- SMS dispatch → Twilio: sends SMS
- Location sharing → Twilio: sends SMS
- SMS dispatch → SMS history and status: writes history
- SMS history and status → SMS dispatch: serves status
- Twilio → Node API: posts webhook
- FastAPI app → Authentication: includes router
- FastAPI app → Profiles: includes router
- FastAPI app → Contacts: includes router
- FastAPI app → Incidents: includes router
- FastAPI app → Supabase helpers: checks health
- Authentication → Supabase helpers: calls helpers
- Supabase helpers → Supabase: accesses
- Recording and tracking → Trusted contacts: notifies